mkdocs-llms-source 0.1.0__py3-none-any.whl

mkdocs_llms_source/__init__.py

@@ -0,0 +1,6 @@
+"""MkDocs plugin to generate /llms.txt for LLM-friendly documentation."""
+
+try:
+    from mkdocs_llms_source._version import __version__
+except ImportError:  # pragma: no cover
+    __version__ = "0.0.0+unknown"

mkdocs_llms_source/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

mkdocs_llms_source/plugin.py

@@ -0,0 +1,196 @@
+"""MkDocs plugin to generate /llms.txt, /llms-full.txt, and per-page .md files."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+
+from mkdocs.config import config_options
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.plugins import BasePlugin
+from mkdocs.structure.files import Files
+from mkdocs.structure.nav import Navigation, Section
+from mkdocs.structure.pages import Page
+
+log = logging.getLogger("mkdocs.plugins.llms_source")
+
+
+@dataclass
+class PageInfo:
+    """Metadata about a single documentation page."""
+
+    title: str
+    src_path: str
+    markdown: str = ""
+    description: str = ""
+
+    def md_url(self, base_url: str) -> str:
+        """Return the absolute URL to the .md version of this page."""
+        return f"{base_url}/{self.src_path}"
+
+
+@dataclass
+class SectionInfo:
+    """A section in the llms.txt output (maps to an H2 heading)."""
+
+    title: str
+    pages: list[PageInfo] = field(default_factory=list)
+
+
+class LlmsTxtPlugin(BasePlugin):
+    """Generate /llms.txt, /llms-full.txt, and per-page .md files."""
+
+    config_scheme = (
+        ("full_output", config_options.Type(bool, default=True)),
+        ("markdown_urls", config_options.Type(bool, default=True)),
+        ("description", config_options.Type(str, default="")),
+    )
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._pages: dict[str, str] = {}  # src_path -> markdown content
+        self._sections: list[SectionInfo] = []
+        self._all_page_paths: set[str] = set()
+
+    def on_config(self, config: MkDocsConfig) -> MkDocsConfig:
+        """Validate configuration."""
+        if not config.get("site_url"):
+            log.warning("llms-source: site_url is not set — llms.txt will use relative URLs.")
+        return config
+
+    def on_files(self, files: Files, config: MkDocsConfig) -> Files:
+        """Track all documentation source files."""
+        for f in files.documentation_pages():
+            self._all_page_paths.add(f.src_path)
+        return files
+
+    def on_nav(self, nav: Navigation, config: MkDocsConfig, files: Files) -> Navigation:
+        """Walk the nav tree to auto-derive llms.txt sections."""
+        self._sections = []
+        self._walk_nav(nav.items)
+        return nav
+
+    def on_page_markdown(self, markdown: str, page: Page, config: MkDocsConfig, files: Files) -> str:
+        """Capture raw markdown for each page."""
+        self._pages[page.file.src_path] = markdown
+        return markdown
+
+    def on_post_build(self, config: MkDocsConfig) -> None:
+        """Generate llms.txt, llms-full.txt, and copy .md files to site output."""
+        site_dir = Path(config["site_dir"])
+        site_url = (config.get("site_url") or "").rstrip("/")
+        site_name = config.get("site_name", "Documentation")
+        site_desc = self.config.get("description") or config.get("site_description", "")
+
+        # Populate page markdown content into section structures
+        for section in self._sections:
+            for page_info in section.pages:
+                page_info.markdown = self._pages.get(page_info.src_path, "")
+
+        # Write llms.txt
+        llms_txt = self._build_llms_txt(site_name, site_desc, site_url)
+        (site_dir / "llms.txt").write_text(llms_txt, encoding="utf-8")
+        log.info("llms-source: Generated llms.txt")
+
+        # Write llms-full.txt
+        if self.config.get("full_output", True):
+            llms_full = self._build_llms_full(site_name, site_desc)
+            (site_dir / "llms-full.txt").write_text(llms_full, encoding="utf-8")
+            log.info("llms-source: Generated llms-full.txt")
+
+        # Copy per-page .md files
+        if self.config.get("markdown_urls", True):
+            self._copy_md_files(config, site_dir)
+
+    # ── Nav walking ──────────────────────────────────────────────
+
+    def _walk_nav(self, items: list, parent_title: str | None = None) -> None:
+        """Recursively walk nav items to build sections."""
+        for item in items:
+            if isinstance(item, Section):
+                section = SectionInfo(title=item.title)
+                self._sections.append(section)
+                self._collect_pages(item.children, section)
+            elif isinstance(item, Page):
+                # Top-level page (not inside a section)
+                title = self._page_title(item)
+                if parent_title is None:
+                    # Create an implicit section for top-level pages
+                    section = SectionInfo(title=title)
+                    section.pages.append(
+                        PageInfo(title=title, src_path=item.file.src_path)
+                    )
+                    self._sections.append(section)
+            # Skip Link items (external URLs)
+
+    def _collect_pages(self, items: list, section: SectionInfo) -> None:
+        """Collect pages from a nav section, including nested subsections."""
+        for item in items:
+            if isinstance(item, Page):
+                title = self._page_title(item)
+                section.pages.append(
+                    PageInfo(title=title, src_path=item.file.src_path)
+                )
+            elif isinstance(item, Section):
+                # Flatten nested sections into the parent section
+                self._collect_pages(item.children, section)
+            # Skip Link items (external URLs)
+
+    @staticmethod
+    def _page_title(page: Page) -> str:
+        """Get the best available title for a page."""
+        if page.title:
+            return page.title
+        # Fallback: derive from filename
+        return PurePosixPath(page.file.src_path).stem.replace("-", " ").replace("_", " ").title()
+
+    # ── Output generation ────────────────────────────────────────
+
+    def _build_llms_txt(self, site_name: str, site_desc: str, site_url: str) -> str:
+        """Build the llms.txt index content."""
+        lines: list[str] = []
+        lines.append(f"# {site_name}\n")
+
+        if site_desc:
+            lines.append(f"> {site_desc}\n")
+
+        for section in self._sections:
+            lines.append(f"## {section.title}\n")
+            for page in section.pages:
+                url = page.md_url(site_url) if site_url else page.src_path
+                desc_part = f": {page.description}" if page.description else ""
+                lines.append(f"- [{page.title}]({url}){desc_part}")
+            lines.append("")
+
+        return "\n".join(lines).rstrip() + "\n"
+
+    def _build_llms_full(self, site_name: str, site_desc: str) -> str:
+        """Build the llms-full.txt with all page content concatenated."""
+        lines: list[str] = []
+        lines.append(f"# {site_name}\n")
+
+        if site_desc:
+            lines.append(f"> {site_desc}\n")
+
+        for section in self._sections:
+            lines.append(f"## {section.title}\n")
+            for page in section.pages:
+                if page.markdown:
+                    lines.append(f"### {page.title}\n")
+                    lines.append(page.markdown.strip())
+                    lines.append("")
+
+        return "\n".join(lines).rstrip() + "\n"
+
+    def _copy_md_files(self, config: MkDocsConfig, site_dir: Path) -> None:
+        """Copy source .md files into the site output directory."""
+        copied = 0
+
+        for src_path, markdown in self._pages.items():
+            dest = site_dir / src_path
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(markdown, encoding="utf-8")
+            copied += 1
+
+        log.info("llms-source: Copied %d .md files to site output", copied)

mkdocs_llms_source-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+mkdocs_llms_source/__init__.py,sha256=fs2s5gb88ambMksgQzvbIzD0MK0AogfwGjmILmXCfjQ,210
+mkdocs_llms_source/_version.py,sha256=5jwwVncvCiTnhOedfkzzxmxsggwmTBORdFL_4wq0ZeY,704
+mkdocs_llms_source/plugin.py,sha256=NDR_b-XdLInU0txJGU-w1TzaWabLSbp53KVUE2x0rOo,7798
+mkdocs_llms_source-0.1.0.dist-info/METADATA,sha256=VN6cRjMYs9QZWh-tD6bm4pPdAHxbVDA3srPj4nV8TLA,3647
+mkdocs_llms_source-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+mkdocs_llms_source-0.1.0.dist-info/entry_points.txt,sha256=lWLByqlEUegBdhGQEh1ekjCKnHIS_rd_2vKL1p5B8qU,71
+mkdocs_llms_source-0.1.0.dist-info/licenses/LICENSE,sha256=dM-_y73WaASlMKc125O9rlz2AXKO3tOtBhU1d2NX4ao,1066
+mkdocs_llms_source-0.1.0.dist-info/RECORD,,

mkdocs_llms_source-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mkdocs_llms_source-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+llms-source = mkdocs_llms_source.plugin:LlmsTxtPlugin

mkdocs_llms_source-0.1.0.dist-info/licenses/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.