>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3568591. --> Reported by: [phenaproxima](https://www.drupal.org/user/205645) Related to !771 !769 !768 !767 >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Drupal CMS's documentation lives completely out of our control. It's somewhere on drupal.org and only a couple of us have the ability to edit it.</p> <p>Needless to say, this is not The Way to have documentation that keeps pace with the rapid speed of change in Drupal CMS. We should do what every other open-source project in the world does, and have our docs in source control, compiled into a static site by a CI job.</p> <p>WIP docs: <a href="https://project.pages.drupalcode.org/drupal_cms/">https://project.pages.drupalcode.org/drupal_cms/</a></p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <ul> <li>Let's get a CI job set up that uses mkdocs to generate a static documentation site and expose it as an artifact that expires in a week. That job should also perform a spell check, and fail if there are any spelling errors.</li> <li>There should also be a job that pushes the docs to GitLab pages when a release is tagged (we probably don't want untagged features in the official documentation).</li> <li>Convert the existing documentation (<a href="https://new.drupal.org/docs/drupal-cms">https://new.drupal.org/docs/drupal-cms</a>) to this new form to start with.</li> <li>Inform @B_man at the DA when the documentation conversion is usable for testing on staging</li> <li>Inform @B_man at the DA when the documentation conversion is finished and the old pages can be replaced with automatic publishing from the docs as code repo into nodes</li> </ul> <h4>For reference:</h4> <ul> <li>Documentation on how to set this up: <a href="https://project.pages.drupalcode.org/gitlab_templates/jobs/pages/">https://project.pages.drupalcode.org/gitlab_templates/jobs/pages/</a></li> <li>Example of another project using this: <a href="https://git.drupalcode.org/project/gitlab_templates/-/tree/main/docs?ref_type=heads">https://git.drupalcode.org/project/gitlab_templates/-/tree/main/docs?ref_type=heads</a></li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>We will want to be sure that we link to the published docs in the navigation sidebar. Right now it links to the old place.</p>