Repository navigation
docs: switch the user guide to Markdown - #10717
Merged
Merged
Conversation
paulbalandan
force-pushed
the
docs-md-4-switch
branch
from
November 3, 2026 16:13
a63b80e to
1b8abce
Compare
michalsn
approved these changes
Nov 3, 2026
3 of 5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Part 4 of the user guide cutover in #10683, after #10714, #10715 and #10716. This is the switch: the site is now built from
docs/anduser_guide_src/is removed.Three commits:
user_guide_src/, the threeadmin/next-*.rsttemplates,.php-cs-fixer.user-guide.phpwith itscomposer.jsonand.php-cs-fixer.dist.phpreferences,utils/check_tabs_in_rst.phpand its call inadmin/pre-commit, and the root.nojekyll. The Sphinx job is gone fromtest-userguide.yml.deploy-userguide-latest.ymlbuildsdevelopinto/develop/and4.8into/next/, publishesversions.jsonat the Pages root, redirects/todevelop/and deploys the result as a Pages artifact. A branch without amkdocs.ymlis skipped with a notice, which is the case for4.8until the merge-up.deploy-userguiderunsmkdocs build --strict,admin/llms.pyandadmin/anchors.pywithSITE_URL=https://codeigniter.com/user_guide/, then copiessite/into the userguide repo'sdocs/. There is no epub any more.deploy-distributables.ymlinstalls fromdocs/requirements.txt, andverify-release.ymlwaits fordocs/llms.txtinstead of the epub.admin/userguide/gets acomposer.jsonand a.gitattributes. The Composer package ships the Markdown pages and thellms*.txtfiles, not the built HTML.RELEASE.mdcovers MkDocs instead of Sphinx and the epub.RST backup
The removed RST is kept in two orphan branches, each with one commit and no link to this history:
rst-user-guide/developat 91193f5rst-user-guide/4.8at a26422eEach holds
user_guide_src/, the RST templates and.php-cs-fixer.user-guide.php.Before merging
https://codeigniter4.github.io/CodeIgniter4/versions.jsonis a 404 and the version switcher falls back to its built-in list.After merging
developinto4.8. Theuser_guide_src/deletion conflicts with 4.8's RST edits. The resolution is to take the deletion and add a sync commit that regeneratesdocs/from 4.8's RST. After that,/next/starts building.:!user_guide_src/exclude inupdate-upgrade-guide.phpstays on purpose, because the 4.7.7 diff basev4.7.6still contains that folder. It has a comment to remove it after 4.7.7.Contributor docs and tooling references to the old guide (
contributing/,AGENTS.md, the.gitignorefiles and similar) are left for the last PR of the series.Verified
mkdocs build --strictandphp admin/update-docs-nav.php --checkpass on this branch.deploy-userguideran against throwaway repos, with the push stubbed. It replaceddocs/, committed, andgit archiveof the result has 326.mdpages and no.html.update-upgrade-guide.php --dry-runruns againstv4.7.6.Checklist: