Update our documentation to use AsciiDoc markdown format

TIL https://www.drupal.org/project/user_guide → !

Ironically, #3384688: Automatically publish a GitLab pages site → seems to be competing with this? 😅🙈

GitLab pages site automation seems very cool. Will this eventually replace the Drupal.org documentation areas? If so, we should definitely look at that. If not, the User Guide approach may be better.

But, TIL #3384688: Automatically publish a GitLab pages site!!! Looks super cool for contrib modules for sure!

> GitLab pages site automation seems very cool. Will this eventually replace the Drupal.org documentation areas? If so, we should definitely look at that. If not, the User Guide approach may be better.

I don't think there is a definitive answer to any of these questions yet. As the maintainer of the User Guide I can say that it's a bit of a one off approach, and I'm not sure we should replicate it again. Right now it requires converting the asciidoc to HTML and then using Feeds to import the HTML to Drupal.org nodes ... and it's prone to breaking. Long term I think we'll move to something else, but what that is remains to be seen.

Using asciidoc for the content has been great. It supports a whole bunch of features that Markdown doesn't and that the guide makes use of. Cross references, admonitions, ebook publication, etc. It's just that having a custom to Drupal.org build system means there are very few people who know how it works and can help keep things updated.

I can try and help answer questions about the user guide process though if you've got any.

Looks like #3384688: Automatically publish a GitLab pages site → hit with documentation here:

https://www.drupal.org/node/3356364#s-publishing-a-documentation-site →

For us to take advantage of that permanently, core would have to have a /docs folder, which I can't find an issue for.

We could try to use this now to see what it would look like.

I created followed the directions above and moved the docs from the 1.x branch into the fork in https://git.drupalcode.org/issue/distributions_recipes-3409318.

However, it is not working. The build-patch job is failing, so I believe that the docs job isn't being reached.

https://git.drupalcode.org/issue/distributions_recipes-3409318/-/pipelin...

It's supposed to look like: https://git.drupalcode.org/project/keycdn/-/pipelines/67741

I tried a few things like commenting out the build-patch job and adding the - '/includes/include.drupalci.main.yml' include, but didn't work. Leaving this as Needs work.