Use markdown for high-level documentation

While the core issue is RTBC, there were no objections to moving in this direction. Therefore, I have made this issue so folks here are aware and perhaps can comment on next steps.

I see that the issue mentions "GitLab pages" as the agreed way forwards. A GitLab pages site is a separate site from api.drupal.org.
Is there any way that is expected for these two sites to communicate? Or is the goal to completely move away from api.drupal.org for code documentation?

@fjgarlin this is not really for code documentation as such, it's for high level documentation of subsystems.

The example I've been using (partly because I'm familiar with it, partly because it shows the issue), is the cache API.

We have:

https://www.drupal.org/docs/8/api/cache-api/cache-api →

And https://api.drupal.org/api/drupal/core%21core.api.php/group/cache/11.x

Both of these are prose, the information is split between the two, as cache API maintainer I know I can submit an MR for the api.drupal.org output (although I dread doing that due to the format), but I have no idea what sign-offs are required to update the handbook documentation, it looks like the section is owned by Wim Leers, I didn't know this until I checked, I'm not sure Wim even does.

The bigger problem is the two of these shouldn't exist, we should have one canonical place for this documentation without obvious duplication. The handbook could potentially have sections about other caching things like how to set up contrib modules (redis, varnish_purge) but at the moment the documentation is split.

We can compare this to Symfony's cache API documentation: https://symfony.com/doc/current/components/cache.html

or Laravel's https://laravel.com/docs/11.x/cache

Both of these are the first result on google and it's pretty clear that's where they want you to start reading. Additionally in the side nav it's clear how to get from there to other component documentation that's equivalent.

I'm not sure there is a fixed view on the other issue that gitlab pages should be used, that feels like more of a DA decision to me anyway.

Using GitLab Pages for core documentation is, I think, a core decision, not a DA.

Those Symfony and Laravel documentation pages are the equivalent of "GitLab pages", probably generated from MD files.
The api.drupal.org just parses code.

If we take the example of Laravel, these would be the matching sites in Drupal:
- https://laravel.com/docs/12.x => Site generated with GitLab pages from MD files in Drupal core (easy to achieve but maintained by core and generated via GitLab CI)
- https://api.laravel.com/docs/12.x/index.html => api.drupal.org (this is generated with Doctum, a tool I evaluated before porting the "api" module/site to modern Drupal)

Following on the "Cache" example, we'd have:
- Generated 100% by code: https://api.laravel.com/docs/12.x/Illuminate/Support/Facades/Cache.html (this is what api.drupal.org does)
- Generated 100% by MD files: https://laravel.com/docs/12.x/cache (source code at https://github.com/laravel/docs/blob/12.x/cache.md)

OK interesting. I think if the DA doesn't have any objection to gitlab pages, and also doesn't want to provide some kind of alternative hosting, then that is fine then!

For me this is less a replacement for api.drupal.org and more for certain parts of the handbook. We can then remove a lot of the long prose on api.drupal.org and link from there to the new docs for higher level concepts. So https://api.drupal.org/api/drupal/core%21core.api.php/group/cache/11.x would be much shorter, with a link, but still there with the overview of interfaces/classes etc.

I think if the DA doesn't have any objection to gitlab pages, and also doesn't want to provide some kind of alternative hosting, then that is fine then!

I'll tag @drumm to chip in just in case, but I don't think we have any objection. In fact, we support it by default in all contrib: https://project.pages.drupalcode.org/gitlab_templates/jobs/pages/

The hosting for that is done automatically in our GitLab instance.

I fully agree with that approach, one can be way more user friendly, one can be more technical. Both have a place and an audience and should be able to coexist (eg: the Laravel links and repos provided before).

Should you want quicker progress, you could start with a contrib project where you start putting all the MD files, structure, menu, etc and build the site from there and play with all the options available. Once fully validated and agreed, it can easily be moved to core under a "docs" folder if needed.

@fjgarlin, thank you.

GitLab pages will not be indexed in the Drupal.org site search, so there will be some loss of findability, but we probably will want to de-emphasize the site search anyway, as some important projects are on GitLab pages already.

The unique thing API module could do, and does for .txt files, is auto-link references to classes/functions/etc like any docblock comment. For example https://api.drupal.org/api/drupal/core%21INSTALL.txt/11.x has links to other files. That is not used much, so I’m sure serious use would find improvements to be made (URLs aren’t auto linked, but would be less-relevant for markdown) in addition to adding markdown parsing.

That said, I think it is all good to go ahead with GitLab pages. There should be some plan to completely replace and delete documentation like https://www.drupal.org/docs/8/api/cache-api/cache-api → , so we try to avoid the usual problem of good documentation initiatives accumulating into just more versions of more documentation to be disorganized.

> The unique thing API module could do, and does for .txt files, is auto-link references to classes/functions/etc like any docblock comment. For example https://api.drupal.org/api/drupal/core%21INSTALL.txt/11.x has links to other files. That is not used much,

?!

In the entity topic alone, I see 14 links to classes or interfaces.

I thought the issue about using markdown would be keeping API module responsible for outputting them. Moving to gitlab pages is scope creep.