Skip to content

chore: add the MkDocs build for the user guide - #10715

Merged
paulbalandan merged 1 commit into
codeigniter4:developfrom
paulbalandan:docs-md-2-build
Nov 3, 2026
Merged

paulbalandan merged 1 commit into
codeigniter4:developfrom
paulbalandan:docs-md-2-build

Conversation

@paulbalandan

Copy link
Copy Markdown
Member

Description
Part 2 of the user guide migration agreed in #10683. It builds on #10714, so it needs that PR merged first. The Sphinx build and the deployment are unchanged, and nothing publishes the Markdown yet.

What this adds

  • mkdocs.yml and the Material theme in docs/overrides/, with docs/requirements.txt for the Python packages. The theme and the requirements file live in docs/ so that only mkdocs.yml is added at the repository root. exclude_docs keeps them out of the built site.
  • admin/llms.py writes llms.txt, llms-full.txt and a Markdown copy of each page beside its HTML (item 8 of docs: decisions needed to migrate the user guide to MkDocs #10683). It reads only the nav and the Markdown, so it does not depend on MkDocs.
  • admin/anchors.py adds the anchor ids that the Sphinx guide used (RST labels and PHP object ids) to the built HTML, so that old links with a #fragment still scroll to their section. The ids are listed in docs/.anchors.json, which keeps the Markdown clean.
  • admin/update-docs-nav.php keeps docs/.nav.yml up to date. It adds a page that is missing from the nav to the section whose first page links to it, in the order of that list. --check changes nothing and exits with 1 when a page is missing or a nav entry has no file. It has a test in tests/system/AutoReview/UpdateDocsNavTest.php.
  • A markdown_check job in test-userguide.yml that runs the nav check, the strict MkDocs build, llms.py and anchors.py. The job fails when a page is missing from docs/.nav.yml. Running php admin/update-docs-nav.php fixes it.
  • .gitattributes excludes docs/ and mkdocs.yml from the Composer archive, .editorconfig keeps the two trailing spaces that the converted pages use as line breaks, and .gitignore covers site/, venv/ and __pycache__/.

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 removed the github_actions Pull requests that update Github_actions code label Nov 3, 2026
@carson-codeigniter4 carson-codeigniter4 Bot added the github_actions Pull requests that update Github_actions code label Nov 3, 2026
@paulbalandan paulbalandan removed the github_actions Pull requests that update Github_actions code label Nov 3, 2026
@carson-codeigniter4 carson-codeigniter4 Bot added the github_actions Pull requests that update Github_actions code label Nov 3, 2026
@paulbalandan
paulbalandan merged commit 8e03e03 into codeigniter4:develop Nov 3, 2026
29 checks passed
@paulbalandan
paulbalandan deleted the docs-md-2-build branch November 3, 2026 13:21
@paulbalandan paulbalandan removed the github_actions Pull requests that update Github_actions code label Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants