>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3530343. --> Reported by: [marcus_johansson](https://www.drupal.org/user/385947) Related to !679 >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Currently we have all our docs in the docs directory and its being pushed to <a href="https://project.pages.drupalcode.org/ai/">https://project.pages.drupalcode.org/ai/</a>. This is done via MKDocs.</p> <p>We haven't kept up with documentation as much as we should and should add more effort to it - but also something that is important for this to work is that we are still in a phase where we change and add a lot of stuff that its versionized.</p> <p>There exists a tool called <a href="https://github.com/jimporter/mike">mike</a> that takes care of handling verisoning, by creating a branch called gh-pages and push all changes there. It needs some <a href="https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/">tweaks</a> to work with material theme.</p> <p>The idea in the end is that you just change the docs on the branch that the documentation affects and it will automatically show up there.</p> <p>Switching what is the default branch, can be done manually via the maintainers and will be documented.</p> <p>It has been tested on Unstructured module and can be seen there: <a href="https://unstructured-project-6813bcd9d1dcc4b99d744ad8ab1d61c9c0511b0521.pages.drupalcode.org/">https://unstructured-project-6813bcd9d1dcc4b99d744ad8ab1d61c9c0511b0521.pages.drupalcode.org/</a></p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>* Change in Gitlab CI so it runs on any x.x.x branch, but not feature branches.<br> * Change in Gitlab CI so it only run s on docs directory changes<br> * Set the version to 1.0.x, 1.1.x, 2.0.x etc - meaning only major and minor changes matters. If you push 1.1.5 it will store under 1.1.x<br> * In the jobb install mike, setup the repo, use mike to push and then get the gh-pages and add that to the artifact that is published.<br> * In mkdocs.yml define changes for material theme, what is the canonical version and that we want a version selector.<br> * Document how we document things - even with how we set a new main branch with Mike for the maintainers.</p>