Expose page Markdown at page.md instead of page/index.md

[haranrk]

Summary

Changes the per-page raw Markdown exposure from page/index.md to a flat page.md (e.g. /agents/config/index.md → /agents/config.md). HTML URLs and pretty directory URLs are unchanged; this is a full switch with no page/index.md output remaining.

How it works

use_directory_urls: true means mkdocs-llmstxt writes each page's Markdown next to its HTML output (site/agents/config/index.md), and the plugin's output path isn't configurable. Rather than flip use_directory_urls (which would rewrite every HTML URL) or fork the plugin, a small post-build hook runs after it and flattens the result. This also works on GitHub Pages, which serves static files only (no redirects).

Changes

• scripts/flatten_md.py (new):
  • flat_md_target() / rewrite_index_links() — pure helpers mapping <dir>/index.md → <dir>.md and rewriting site-internal .../index.md link targets to the flat form.
  • on_post_build hook (@event_priority(-100), so it runs after mkdocs-llmstxt) that renames the generated Markdown files and rewrites links in the generated *.md files plus llms.txt / llms-full.txt.
• mkdocs.yml — registers the hook via top-level hooks:.
• overrides/partials/actions.html — the "view as Markdown" link and "copy page as Markdown" button now point at the flat ../<page>.md.
• scripts/test_flatten_md.py (new) — unit tests for the helpers plus a tmp_path integration test for on_post_build.

Behavior

Pretty URL	Before	After
/agents/config/	/agents/config/index.md	/agents/config.md
/agents/ (section index)	/agents/index.md	/agents.md

Testing

• pytest scripts/test_flatten_md.py — 11/11 passing.
• mkdocs build --strict — exits 0; hook renamed 217 Markdown files, rewrote links in 44 files.
• Verified: flat files exist, old index.md files gone, no stale .../index.md link targets remain, and buttons resolve to ../config.md / ../agents.md.

[netlify]

✅ Deploy Preview for adk-docs-preview ready!

Name	Link
🔨 Latest commit	2f14ec8
🔍 Latest deploy log	https://app.netlify.com/projects/adk-docs-preview/deploys/6a51725108306300098027bb
😎 Deploy Preview	https://deploy-preview-1950--adk-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[koverholt]

This introduces a lot of complex machinery into our build, which risks broken builds in the future, or silently producing broken converted Markdown during the build.

The benefit seems small: mkdocs-llmstxt already emits working per-page .md links in llms.txt and llms-full.txt today, and an agent consuming those retrieves identical content whether the link ends in page/index.md or page.md. This only changes the link form, not what agents can retrieve, and then we have to add a link-rewriting pass over llms.txt/llms-full.txt specifically to keep those already-working links consistent after the rename.

One of the nice things about the current setup is that we depend entirely on the external plugin, with no custom build steps, config, or post-processing. This might make more sense as part of the plugin functionality itself and an option rather than maintaining as post-processing scripts.

I'll wait for @joefernandez to review as well since this is a big change to the build process, but in general I am -1 on this change since it gives us 200+ more lines to maintain and added risk to the docs build.

[zeroasterisk]

Would this be an upstream change, for all mkdocs users