mkdocs-llms-source 0.1.0__tar.gz

mkdocs_llms_source-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,65 @@
+# Copilot Instructions for mkdocs-llms-source
+
+## Repository Overview
+
+This is a MkDocs plugin that generates /llms.txt files following the
+[llmstxt.org](https://llmstxt.org/) specification. It makes MkDocs documentation
+sites easily consumable by LLMs and AI coding tools.
+
+## Tech Stack
+
+- Python 3.10+, MkDocs plugin API
+- Build: hatchling
+- Test: pytest
+- Lint: ruff
+- Docs: MkDocs Material (dogfooding this plugin)
+
+## How to Build / Test / Run
+
+```bash
+# Install in dev mode
+uv sync --all-extras
+
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check src/ tests/
+
+# Build docs (dogfooding)
+uv run mkdocs build
+
+# Serve docs locally
+uv run mkdocs serve
+```
+
+## Architecture
+
+- `src/mkdocs_llms_source/plugin.py` — Main plugin class using MkDocs hook API
+- Plugin hooks used: on_config, on_files, on_nav, on_page_markdown, on_post_build
+- Source-first approach: uses original markdown, no HTML→MD conversion
+- Auto-derives llms.txt sections from MkDocs nav config (zero-config)
+
+## Key Design Decisions
+
+- **Source-first**: We use the original .md source, not HTML→Markdown conversion.
+  This is simpler and more reliable. Trade-off: dynamically generated content
+  (API docs, executed code blocks) won't appear in the markdown output.
+- **Nav-derived sections**: By default, the llms.txt H2 sections mirror the
+  MkDocs nav structure. No duplicate config needed.
+- **Three outputs**: /llms.txt (index), /llms-full.txt (all content), per-page
+  .md files (individual pages).
+
+## Documentation Structure
+
+- `docs/` — Human-facing docs published via MkDocs
+- `agent-docs/` — Agent working notes (NOT published). Check todo.md at session
+  start, update progress.md after milestones.
+- `.github/copilot-instructions.md` — This file. Auto-loaded by Copilot.
+
+## Common Pitfalls
+
+- `site_url` must be set in mkdocs.yml for absolute URLs in llms.txt
+- `use_directory_urls` affects where .md files get written in site output
+- The plugin entry point in pyproject.toml must match the class path exactly
+- When editing plugin.py, remember that MkDocs calls hooks in a specific order: on_config → on_files → on_nav → on_page_markdown (per page) → on_post_build

mkdocs_llms_source-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uvx ruff check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-extras
+      - run: uv run python -m pytest --cov=mkdocs_llms_source

mkdocs_llms_source-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

mkdocs_llms_source-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Auto-generated version file
+src/mkdocs_llms_source/_version.py
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# MkDocs build output
+site/
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Other repos used for E2E testing
+other_repos/
+
+# OS
+.DS_Store
+Thumbs.db

mkdocs_llms_source-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Child
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocs_llms_source-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: mkdocs-llms-source
+Version: 0.1.0
+Summary: MkDocs plugin to generate /llms.txt files for LLM-friendly documentation
+Project-URL: Homepage, https://github.com/TimChild/mkdocs-llms-source
+Project-URL: Documentation, https://github.com/TimChild/mkdocs-llms-source
+Project-URL: Repository, https://github.com/TimChild/mkdocs-llms-source
+Project-URL: Issues, https://github.com/TimChild/mkdocs-llms-source/issues
+Author: Tim Child
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,documentation,llms,llmstxt,mkdocs
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Requires-Dist: mkdocs>=1.5
+Provides-Extra: dev
+Requires-Dist: mkdocs-material>=9.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mkdocs-llms-source
+
+[![CI](https://github.com/TimChild/mkdocs-llms-source/actions/workflows/ci.yml/badge.svg)](https://github.com/TimChild/mkdocs-llms-source/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mkdocs-llms-source)](https://pypi.org/project/mkdocs-llms-source/)
+[![Python](https://img.shields.io/pypi/pyversions/mkdocs-llms-source)](https://pypi.org/project/mkdocs-llms-source/)
+
+MkDocs plugin to generate [`/llms.txt`](https://llmstxt.org/) files for LLM-friendly documentation.
+
+## What It Does
+
+Generates three outputs from your MkDocs site:
+
+1. **`/llms.txt`** — A curated index following the [llmstxt.org spec](https://llmstxt.org/) with links to per-page markdown files
+2. **`/llms-full.txt`** — All documentation concatenated into a single file (for stuffing into LLM context windows)
+3. **Per-page `.md` files** — Raw markdown accessible at the same URL path as HTML pages
+
+## Install
+
+```bash
+uv add mkdocs-llms-source
+```
+
+## Usage
+
+Add to your `mkdocs.yml`:
+
+```yaml
+site_name: My Project
+site_url: https://docs.example.com
+site_description: Documentation for My Project
+
+plugins:
+  - search
+  - llms-source
+```
+
+Build your site:
+
+```bash
+mkdocs build
+```
+
+The plugin auto-derives the llms.txt section structure from your MkDocs `nav` — zero extra configuration needed.
+
+## Configuration
+
+```yaml
+plugins:
+  - llms-source:
+      full_output: true           # Generate llms-full.txt (default: true)
+      markdown_urls: true         # Copy .md source files to output (default: true)
+      description: "Override description for llms.txt header"
+```
+
+## How It Works
+
+**Source-first approach**: The plugin uses your original markdown source files directly — no HTML-to-Markdown conversion. This is simpler, more reliable, and preserves your intended formatting.
+
+The llms.txt sections are automatically derived from your MkDocs `nav` configuration, so top-level nav items become H2 sections in the output.
+
+## Example Output
+
+Given this nav:
+
+```yaml
+nav:
+  - Home: index.md
+  - Guides:
+    - Getting Started: guides/setup.md
+```
+
+The generated `/llms.txt`:
+
+```markdown
+# My Project
+
+> Documentation for My Project
+
+## Home
+
+- [My Project](https://docs.example.com/index.md)
+
+## Guides
+
+- [Getting Started](https://docs.example.com/guides/setup.md)
+```
+
+## License
+
+MIT

mkdocs_llms_source-0.1.0/README.md

@@ -0,0 +1,90 @@
+# mkdocs-llms-source
+
+[![CI](https://github.com/TimChild/mkdocs-llms-source/actions/workflows/ci.yml/badge.svg)](https://github.com/TimChild/mkdocs-llms-source/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mkdocs-llms-source)](https://pypi.org/project/mkdocs-llms-source/)
+[![Python](https://img.shields.io/pypi/pyversions/mkdocs-llms-source)](https://pypi.org/project/mkdocs-llms-source/)
+
+MkDocs plugin to generate [`/llms.txt`](https://llmstxt.org/) files for LLM-friendly documentation.
+
+## What It Does
+
+Generates three outputs from your MkDocs site:
+
+1. **`/llms.txt`** — A curated index following the [llmstxt.org spec](https://llmstxt.org/) with links to per-page markdown files
+2. **`/llms-full.txt`** — All documentation concatenated into a single file (for stuffing into LLM context windows)
+3. **Per-page `.md` files** — Raw markdown accessible at the same URL path as HTML pages
+
+## Install
+
+```bash
+uv add mkdocs-llms-source
+```
+
+## Usage
+
+Add to your `mkdocs.yml`:
+
+```yaml
+site_name: My Project
+site_url: https://docs.example.com
+site_description: Documentation for My Project
+
+plugins:
+  - search
+  - llms-source
+```
+
+Build your site:
+
+```bash
+mkdocs build
+```
+
+The plugin auto-derives the llms.txt section structure from your MkDocs `nav` — zero extra configuration needed.
+
+## Configuration
+
+```yaml
+plugins:
+  - llms-source:
+      full_output: true           # Generate llms-full.txt (default: true)
+      markdown_urls: true         # Copy .md source files to output (default: true)
+      description: "Override description for llms.txt header"
+```
+
+## How It Works
+
+**Source-first approach**: The plugin uses your original markdown source files directly — no HTML-to-Markdown conversion. This is simpler, more reliable, and preserves your intended formatting.
+
+The llms.txt sections are automatically derived from your MkDocs `nav` configuration, so top-level nav items become H2 sections in the output.
+
+## Example Output
+
+Given this nav:
+
+```yaml
+nav:
+  - Home: index.md
+  - Guides:
+    - Getting Started: guides/setup.md
+```
+
+The generated `/llms.txt`:
+
+```markdown
+# My Project
+
+> Documentation for My Project
+
+## Home
+
+- [My Project](https://docs.example.com/index.md)
+
+## Guides
+
+- [Getting Started](https://docs.example.com/guides/setup.md)
+```
+
+## License
+
+MIT

mkdocs_llms_source-0.1.0/agent-docs/progress.md

@@ -0,0 +1,21 @@
+# Progress
+
+## 2026-03-22 — Initial scaffolding
+
+- Created full project structure with pyproject.toml, src/, tests/, docs/, agent-docs/
+- Implemented MVP plugin with all core MkDocs hooks:
+  - `on_config` — validates site_url
+  - `on_files` — tracks source files
+  - `on_nav` — walks nav tree to build section structure
+  - `on_page_markdown` — captures raw markdown per page
+  - `on_post_build` — writes llms.txt, llms-full.txt, copies .md files
+- Wrote integration test suite covering:
+  - Basic build verification
+  - llms.txt content/structure
+  - llms-full.txt generation
+  - Per-page .md file copying
+  - Config options (full_output, markdown_urls, description)
+  - Edge cases (trailing slash, nested nav, no site_url)
+- Created docs (index, quickstart, configuration, development)
+- Set up CI workflows (lint+test on PR, publish on release)
+- Created .github/copilot-instructions.md for agent context

mkdocs_llms_source-0.1.0/agent-docs/todo.md

@@ -0,0 +1,26 @@
+# TODO
+
+## Phase 1 — MVP
+- [x] Scaffold project structure (pyproject.toml, src/, tests/)
+- [x] Implement basic plugin: on_config, on_files, on_nav, on_page_markdown, on_post_build
+- [x] Auto-derive sections from MkDocs nav
+- [x] Generate /llms.txt with proper spec format
+- [x] Generate /llms-full.txt with all content
+- [x] Copy per-page .md files to site output
+- [x] Write integration tests with a fixture MkDocs site
+- [ ] Dogfood: use plugin on its own docs site
+- [ ] Publish v0.1.0 to PyPI
+
+## Phase 2 — Polish
+- [ ] Explicit `sections` config with glob support
+- [ ] `optional` section support
+- [ ] Handle `use_directory_urls: false`
+- [ ] Handle missing site_url gracefully (✓ partial — logs warning, uses relative)
+- [ ] CI workflow (lint + test on PR)
+- [ ] Publish workflow (PyPI on release tag)
+
+## Phase 3 — Advanced
+- [ ] Optional HTML→Markdown fallback for generated pages (API docs, macros)
+- [ ] Preprocessing hooks (custom transforms)
+- [ ] `base_url` override (for versioned docs / Read the Docs)
+- [ ] Per-page description annotations (via frontmatter)

mkdocs_llms_source-0.1.0/docs/configuration.md

@@ -0,0 +1,73 @@
+# Configuration Reference
+
+All configuration options are set under the `llms-source` plugin in `mkdocs.yml`.
+
+## Options
+
+### `full_output`
+
+- **Type**: `bool`
+- **Default**: `true`
+
+Generate `/llms-full.txt` containing all documentation content concatenated.
+
+```yaml
+plugins:
+  - llms-source:
+      full_output: false  # Disable llms-full.txt generation
+```
+
+### `markdown_urls`
+
+- **Type**: `bool`
+- **Default**: `true`
+
+Copy source `.md` files into the site output directory, making them accessible at the same URL path as the HTML pages but with a `.md` extension.
+
+```yaml
+plugins:
+  - llms-source:
+      markdown_urls: false  # Don't copy .md files to output
+```
+
+### `description`
+
+- **Type**: `str`
+- **Default**: `""` (uses `site_description` from mkdocs.yml)
+
+Override the description shown in the llms.txt blockquote header.
+
+```yaml
+plugins:
+  - llms-source:
+      description: "Custom description for LLM consumers"
+```
+
+## Full Example
+
+```yaml
+site_name: My Project
+site_url: https://docs.example.com
+site_description: Documentation for My Project
+
+plugins:
+  - search
+  - llms-source:
+      full_output: true
+      markdown_urls: true
+      description: "API and usage docs for My Project"
+
+nav:
+  - Home: index.md
+  - Guides:
+    - Getting Started: guides/getting-started.md
+    - Advanced Usage: guides/advanced.md
+  - API Reference:
+    - Overview: api/index.md
+    - Endpoints: api/endpoints.md
+```
+
+## Requirements
+
+- **`site_url`** must be set in `mkdocs.yml` for absolute URLs in `llms.txt`. Without it, the plugin falls back to relative paths and logs a warning.
+- **`nav`** should be defined for best results. The plugin auto-derives llms.txt sections from the nav structure. Without nav, MkDocs auto-generates one from the file structure.

mkdocs_llms_source-0.1.0/docs/development.md

@@ -0,0 +1,63 @@
+# Development
+
+## Setup
+
+Clone the repository and install in development mode:
+
+```bash
+git clone https://github.com/TimChild/mkdocs-llms-source.git
+cd mkdocs-llms-source
+uv sync --all-extras
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+With coverage:
+
+```bash
+pytest --cov=mkdocs_llms_source
+```
+
+## Linting
+
+```bash
+ruff check src/ tests/
+```
+
+Auto-fix:
+
+```bash
+ruff check --fix src/ tests/
+```
+
+## Building Docs
+
+The project dogfoods its own plugin:
+
+```bash
+mkdocs serve    # Local dev server
+mkdocs build    # Build static site
+```
+
+## Project Structure
+
+- `src/mkdocs_llms_source/plugin.py` — Main plugin implementation
+- `tests/` — Test suite with fixtures
+- `docs/` — Human-facing documentation (published via MkDocs)
+- `agent-docs/` — Agent working notes (not published)
+
+## Architecture
+
+The plugin hooks into MkDocs' build lifecycle:
+
+1. **`on_config`** — Validates that `site_url` is set
+2. **`on_files`** — Tracks available source files
+3. **`on_nav`** — Walks the nav tree to build llms.txt section structure
+4. **`on_page_markdown`** — Captures raw markdown content for each page
+5. **`on_post_build`** — Writes `llms.txt`, `llms-full.txt`, and copies `.md` files
+
+Key design decision: **source-first** — we use original markdown source files, not HTML-to-Markdown conversion. This is simpler and preserves author formatting.

mkdocs_llms_source-0.1.0/docs/index.md

@@ -0,0 +1,41 @@
+# mkdocs-llms-source
+
+MkDocs plugin to generate `/llms.txt` files for LLM-friendly documentation.
+
+## Overview
+
+mkdocs-llms-source generates [llms.txt](https://llmstxt.org/) files from your MkDocs documentation site so that AI tools can efficiently consume your docs without parsing HTML.
+
+The plugin produces three outputs:
+
+1. **`/llms.txt`** — A curated index following the llmstxt.org spec with links to per-page markdown files
+2. **`/llms-full.txt`** — All documentation concatenated into a single file
+3. **Per-page `.md` files** — Raw markdown at the same URL path as HTML pages
+
+## Quick Start
+
+Install the plugin:
+
+```bash
+pip install mkdocs-llms-source
+```
+
+Add it to your `mkdocs.yml`:
+
+```yaml
+plugins:
+  - search
+  - llms-source
+```
+
+Build your site:
+
+```bash
+mkdocs build
+```
+
+That's it! Your site will now include `/llms.txt`, `/llms-full.txt`, and per-page `.md` files.
+
+## Configuration
+
+See the [configuration reference](configuration.md) for all options.

mkdocs_llms_source-0.1.0/docs/quickstart.md

@@ -0,0 +1,65 @@
+# Quick Start
+
+## Installation
+
+```bash
+uv add mkdocs-llms-source
+```
+
+## Basic Usage
+
+Add the plugin to your `mkdocs.yml`:
+
+```yaml
+site_name: My Project
+site_url: https://docs.example.com
+site_description: Documentation for My Project
+
+plugins:
+  - search
+  - llms-source
+```
+
+**Important**: Set `site_url` in your `mkdocs.yml` — the llms.txt spec requires absolute URLs.
+
+Build your site as usual:
+
+```bash
+mkdocs build
+```
+
+The plugin will generate:
+
+- `site/llms.txt` — Index file following the llmstxt.org spec
+- `site/llms-full.txt` — All docs concatenated into one file
+- `site/*.md` — Per-page markdown files alongside the HTML
+
+## How It Works
+
+The plugin uses a **source-first** approach:
+
+1. It reads your original markdown source files (no HTML-to-Markdown conversion)
+2. It auto-derives the llms.txt section structure from your MkDocs `nav` configuration
+3. It generates the output files during the MkDocs build process
+
+This means zero extra configuration is needed for most sites.
+
+## Verify
+
+After building, check that the files were created:
+
+```bash
+cat site/llms.txt
+```
+
+You should see something like:
+
+```markdown
+# My Project
+
+> Documentation for My Project
+
+## Home
+
+- [My Project](https://docs.example.com/index.md)
+```

mkdocs_llms_source-0.1.0/mkdocs.yml

@@ -0,0 +1,16 @@
+site_name: mkdocs-llms-source
+site_url: https://TimChild.github.io/mkdocs-llms-source
+site_description: MkDocs plugin to generate /llms.txt files for LLM-friendly documentation
+
+theme:
+  name: material
+
+plugins:
+  - search
+  - llms-source
+
+nav:
+  - Home: index.md
+  - Quick Start: quickstart.md
+  - Configuration: configuration.md
+  - Development: development.md