From 7bdb29a042faaa9e4f125c8c479fe35f54d8a2e6 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 7 May 2026 09:40:51 +0300 Subject: docs(llms.txt): update dirhtml-skip rationale after .md pivot MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous comment on `_write_llms_txt` (and on the LLM-Facing Files section in CLAUDE.md) justified the `dirhtml` skip by claiming the template's `.html` URLs wouldn't resolve under `dirhtml` output. That became stale after [#1874@5fe7f9ad](https://github.com/vyos/vyos-documentation/pull/1874/commits/5fe7f9ad) (and parity commits on [#1876](https://github.com/vyos/vyos-documentation/pull/1876)/[#1903](https://github.com/vyos/vyos-documentation/pull/1903)) pivoted the curated template to `.md` URLs — `_copy_md_sources` puts `.md` files at their source-relative paths regardless of builder, so the rendered llms.txt would actually resolve fine under `dirhtml` now. The real reason we skip `dirhtml` is simpler: production publishes only via the `html`/`readthedocs` builders, and we don't render llms.txt for builds we don't ship. Local `make dirhtml` is a developer convenience, not a publish target. Reword the conf.py comment and the CLAUDE.md section to say that plainly. No code-behavior change. Addresses Copilot review feedback on PR #1874 (3 threads on docs/conf.py, docs/_templates/llms.txt.j2, and CLAUDE.md flagging the inconsistency). \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io) --- docs/conf.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 26ce346c..dddb78fe 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -267,10 +267,12 @@ def _write_llms_txt(app, exception): ``release``, and writes ``/llms.txt``. ``llms-full.txt`` is handled separately by the ``sphinx_llms_txt`` extension. """ - # Skip dirhtml: the curated template encodes `.html` URLs (e.g. - # `quick-start.html`), which don't exist under `dirhtml` output - # (`quick-start/index.html`). Production publishes via the html / - # readthedocs builders, so dirhtml output would just be misleading. + # Skip dirhtml: production publishes via the `html` / `readthedocs` + # builders only. The `.md` links in the curated template do + # actually resolve under `dirhtml` (`_copy_md_sources` puts `.md` + # files at their source-relative paths regardless of builder), but + # we still don't render llms.txt for builds we don't ship — local + # `make dirhtml` is a developer convenience, not a publish target. if exception is not None or app.builder.name not in ( 'html', 'readthedocs'): return -- cgit v1.2.3