Skip to content

docs: add llms.txt via mkdocs-llmstxt plugin#1948

Open
bearomorphism wants to merge 3 commits intomasterfrom
docs/add-llms-txt
Open

docs: add llms.txt via mkdocs-llmstxt plugin#1948
bearomorphism wants to merge 3 commits intomasterfrom
docs/add-llms-txt

Conversation

@bearomorphism
Copy link
Copy Markdown
Collaborator

@bearomorphism bearomorphism commented May 7, 2026

Description

Add auto-generated llms.txt and llms-full.txt for the docs site using the mkdocs-llmstxt plugin.

Instead of a hand-crafted static file, the plugin auto-generates both files from mkdocs.yml on every build, keeping them in sync with docs automatically. llms-full.txt includes expanded page contents for direct LLM consumption.

Checklist

Was generative AI tooling used to co-author this PR?

  • Yes (GitHub Copilot CLI)

Generated-by: GitHub Copilot CLI following the guidelines

Code Changes

  • Add test cases to all the changes you introduce (N/A - docs config only)
  • Run uv run poe all locally to ensure this change passes linter check and tests
  • Manually test the changes:
    • Verify the feature/bug fix works as expected in real-world scenarios
    • Test edge cases and error conditions
    • Ensure backward compatibility is maintained
    • Document any manual testing steps performed
  • Update the documentation for the changes

Documentation Changes

  • Run uv run poe doc locally to ensure the documentation pages renders correctly
  • Check and fix any broken links (internal or external)

Expected Behavior

After mkdocs build, both site/llms.txt (index) and site/llms-full.txt (expanded contents) are generated automatically from the mkdocs.yml plugin config.

Steps to Test This Pull Request

  1. Run uv run mkdocs build --strict
  2. Verify site/llms.txt and site/llms-full.txt exist
  3. Check that llms.txt contains grouped links matching the mkdocs.yml nav

Additional Context

Part of #1936. The SKILL.md portion is addressed in PR #1949.

Switched from a hand-crafted docs/llms.txt to the mkdocs-llmstxt plugin based on research showing that auto-generation keeps docs in sync and also produces the commonly-expected llms-full.txt companion file.

Add docs/llms.txt to expose a structured, LLM-friendly index of the documentation site.

No mkdocs configuration changes are required because MkDocs copies docs/llms.txt as a static asset, which was verified with uv run mkdocs build --strict.

Refs #1936

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds an llms.txt static asset to the MkDocs documentation site to provide an agent/LLM-friendly index of key Commitizen docs pages (grouped by topic), supporting discoverability for automated tooling.

Changes:

  • Add docs/llms.txt with grouped, canonical links to major documentation sections (overview, commands, configuration, tutorials, plugins, contributing).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/llms.txt Outdated
Comment thread docs/llms.txt Outdated
Comment thread docs/llms.txt Outdated
Add a root-level SKILL.md that follows the Agent Skills specification and guides agents to Commitizen commands, configuration, versioning, changelog, CI, and exit-code references.

Refs: #1936

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@bearomorphism
Copy link
Copy Markdown
Collaborator Author

Validation

Verified that all review comments have been addressed:

Currently researching whether the file placement at /commitizen/llms.txt (GitHub Pages subpath) is discoverable by LLM tools in practice. Will update with findings.

@bearomorphism bearomorphism marked this pull request as draft May 7, 2026 10:05
Replace hand-crafted docs/llms.txt with the mkdocs-llmstxt plugin that auto-generates llms.txt and llms-full.txt from mkdocs.yml config.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@bearomorphism bearomorphism changed the title docs: add llms.txt for docs site docs: add llms.txt via mkdocs-llmstxt plugin May 7, 2026
@bearomorphism bearomorphism marked this pull request as ready for review May 7, 2026 10:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants