Skip to content

docs: switch the user guide to Markdown - #10717

Merged
paulbalandan merged 3 commits into
codeigniter4:developfrom
paulbalandan:docs-md-4-switch
Nov 3, 2026
Merged

paulbalandan merged 3 commits into
codeigniter4:developfrom
paulbalandan:docs-md-4-switch

Conversation

@paulbalandan

Copy link
Copy Markdown
Member

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/ and user_guide_src/ is removed.

Three commits:

  1. Remove the RST user guide. Deletes user_guide_src/, the three admin/next-*.rst templates, .php-cs-fixer.user-guide.php with its composer.json and .php-cs-fixer.dist.php references, utils/check_tabs_in_rst.php and its call in admin/pre-commit, and the root .nojekyll. The Sphinx job is gone from test-userguide.yml.
  2. Deploy the user guide to GitHub Pages. deploy-userguide-latest.yml builds develop into /develop/ and 4.8 into /next/, publishes versions.json at the Pages root, redirects / to develop/ and deploys the result as a Pages artifact. A branch without a mkdocs.yml is skipped with a notice, which is the case for 4.8 until the merge-up.
  3. Build the user guide with MkDocs in the release workflows.
    • deploy-userguide runs mkdocs build --strict, admin/llms.py and admin/anchors.py with SITE_URL=https://codeigniter.com/user_guide/, then copies site/ into the userguide repo's docs/. There is no epub any more.
    • deploy-distributables.yml installs from docs/requirements.txt, and verify-release.yml waits for docs/llms.txt instead of the epub.
    • admin/userguide/ gets a composer.json and a .gitattributes. The Composer package ships the Markdown pages and the llms*.txt files, not the built HTML.
    • RELEASE.md covers 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:

Each holds user_guide_src/, the RST templates and .php-cs-fixer.user-guide.php.

Before merging

  • Switch the repository's Pages source to "GitHub Actions". The deploy runs on the merge push, so the first run fails without it.
  • Until the first Pages deploy, https://codeigniter4.github.io/CodeIgniter4/versions.json is a 404 and the version switcher falls back to its built-in list.

After merging

  • Merge develop into 4.8. The user_guide_src/ deletion conflicts with 4.8's RST edits. The resolution is to take the deletion and add a sync commit that regenerates docs/ from 4.8's RST. After that, /next/ starts building.
  • The :!user_guide_src/ exclude in update-upgrade-guide.php stays on purpose, because the 4.7.7 diff base v4.7.6 still 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 .gitignore files and similar) are left for the last PR of the series.

Verified

  • mkdocs build --strict and php admin/update-docs-nav.php --check pass on this branch.
  • deploy-userguide ran against throwaway repos, with the push stubbed. It replaced docs/, committed, and git archive of the result has 326 .md pages and no .html.
  • update-upgrade-guide.php --dry-run runs against v4.7.6.
  • Not run yet: the Pages workflow and the release workflows, which need a real deploy or release.

Checklist:

  • Securely signed commits
  • Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
  • Unit testing, with >80% coverage
  • User guide updated
  • Conforms to style guide

@carson-codeigniter4 carson-codeigniter4 Bot added the github_actions Pull requests that update Github_actions code label Nov 3, 2026
@paulbalandan
paulbalandan merged commit 330fc9c into codeigniter4:develop Nov 3, 2026
55 checks passed
@paulbalandan
paulbalandan deleted the docs-md-4-switch branch November 3, 2026 17:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

github_actions Pull requests that update Github_actions code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants