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.

thejimbirch → changed the visibility of the branch 11.x to hidden.

thejimbirch → changed the visibility of the branch 3409318-update-recipes-documentation to hidden.

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.

Thanks for the input. We are going to shift to the mkdocs and use Gitlab pages for publishing.

The https://www.drupal.org/project/ai → has done this, so we can use their code as a guide.

The last comment referenced GitLab Pages, but also changed the title to reference GitHub Pages. Will leave it to @thejimbirch to correct whichever is inaccurate.

I'm interested in the eventual solution here for 📌 Set up MkDocs for docs.memberplatform.org Active

Thanks for that, brain slip. GitLab.

Hmmm, not working and I don't know why. Need to pause on this for now.

@thejimbirch We accomplished this for Member Platform today in 📌 Set up MkDocs for docs.memberplatform.org Active

Merged that. Lets see if that works.

Nope. Swing and a miss.

thejimbirch → changed the visibility of the branch 3409318-3rd-time-charm to hidden.

thejimbirch → changed the visibility of the branch 3409318-gitlab-config to hidden.

thejimbirch → changed the visibility of the branch 3409318-mkdocs to hidden.

ok, the CI needed some updating behind the scenes to get the job to run. Which it is now, all green and you can preview the docs build here:

https://project.pages.drupalcode.org/-/distributions_recipes/-/jobs/4909...

Looks good. Thanks @thejimbirch

Success!

https://project.pages.drupalcode.org/distributions_recipes/