Expose page Markdown at page.md instead of page/index.md#1950
Conversation
✅ Deploy Preview for adk-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
8b9df62 to
2f14ec8
Compare
koverholt
left a comment
koverholt
left a comment
There was a problem hiding this comment.
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.
|
Would this be an upstream change, for all mkdocs users |
| return f"{parent.as_posix()}.md" | ||
|
|
||
|
|
||
| def rewrite_index_links(text: str, site_url: str) -> str: |
There was a problem hiding this comment.
rewriting the links of the markdown file is unnecessary. The links as provided work just fine, and you are introducing complexity, dependency on this URL re-writing script, and creating potential link failures by doing this. Recommend removing this.
| site_dir = Path(config["site_dir"]) | ||
| site_url = config["site_url"] | ||
|
|
||
| # Pass 1: rename <dir>/index.md -> <dir>.md (root index.md is left alone). |
There was a problem hiding this comment.
You are restructuring the documentation file serving structure on the fly for the sole purpose of providing a new access method (**/page.md URL pattern). This solution not appropriate to the outcome and will likely create serving and maintenance issues in the future.
Since this functionality is purely meant to provide a new access pattern (**/page.md), and since we already provide a markdown output (e.g., https://adk.dev/get-started/index.md ), I recommend you create a extension of the redirect functionality that runs after all configured redirects in mkdoc.yaml to capture requests for the **/page.md URL pattern, such that a request for https://adk.dev/get-started.md is redirected to https://adk.dev/get-started/index.md , without rewriting the existing page source.
4 participants
Summary
Changes the per-page raw Markdown exposure from
page/index.mdto a flatpage.md(e.g./agents/config/index.md→/agents/config.md). HTML URLs and pretty directory URLs are unchanged; this is a full switch with nopage/index.mdoutput remaining.How it works
use_directory_urls: truemeansmkdocs-llmstxtwrites 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 flipuse_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>.mdand rewriting site-internal.../index.mdlink targets to the flat form.on_post_buildhook (@event_priority(-100), so it runs aftermkdocs-llmstxt) that renames the generated Markdown files and rewrites links in the generated*.mdfiles plusllms.txt/llms-full.txt.mkdocs.yml— registers the hook via top-levelhooks:.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 atmp_pathintegration test foron_post_build.Behavior
/agents/config//agents/config/index.md/agents/config.md/agents/(section index)/agents/index.md/agents.mdTesting
pytest scripts/test_flatten_md.py— 11/11 passing.mkdocs build --strict— exits 0; hook renamed 217 Markdown files, rewrote links in 44 files.index.mdfiles gone, no stale.../index.mdlink targets remain, and buttons resolve to../config.md/../agents.md.