fix(docs): the published docs site had empty pages, and the build stayed green - #35
Merged
Merged
Conversation
…yed green Every `--8<--` include in this site was silently resolving to nothing. All nine used a `../` path -- `--8<-- "../ARCHITECTURE.md"` and friends -- which pymdownx.snippets refuses because it escapes `base_path`, and `check_paths: false` turned that refusal into silence. `mkdocs build --strict` then passed with nothing to say. The result is live: https://webdevsamran.github.io/devrepro-doctor/ has been serving an Architecture page of 68 words, all of it navigation chrome, and the same for Roadmap, Contributing, Security, Interop, Product gaps, Changelog and Code of conduct. The home page was missing its README section. Found while porting this docs setup to api-verity-lab: the same include pattern failed there, and rather than work around it I checked whether it had ever worked here. It had not. Fixed by pointing `base_path` at the repository root and dropping the `../` from every include, so the paths stay inside base_path. `check_paths` is now true, which makes a missing snippet a build failure rather than a silent skip. `validation.links.not_found` is downgraded to info, deliberately and with the reason recorded in mkdocs.yml: included root documents carry links written relative to the repository, where they are correct and where most people read them, but which sit outside the docs tree inside the site. That check is cosmetic here; `check_paths` is the one that matters, and it is now loud. scripts/check_docs_site.py asserts the built site has content rather than merely building. A page under 120 words is chrome, not a document -- empty pages measured 68, real ones 383 to 655. Verified by reintroducing the `../` path and watching the build fail. 16 pages now build with real content in all of them.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Every
--8<--include in this site was silently resolving to nothing.All nine used a
../path —--8<-- "../ARCHITECTURE.md"and friends — whichpymdownx.snippetsrefuses because it escapesbase_path.check_paths: falseturned that refusal into silence, andmkdocs build --strictpassed with nothing to say.The result is live
webdevsamran.github.io/devrepro-doctor has been serving an Architecture page of 68 words — all of it navigation chrome — and the same for Roadmap, Contributing, Security, Interop, Product gaps, Changelog and Code of conduct. The home page was missing its README section entirely.
Found while porting this docs setup to
api-verity-lab: the same include pattern failed there, and rather than work around it I checked whether it had ever worked here. It hadn't.The fix
base_pathpoints at the repository root, and every include drops its../, so paths stay insidebase_path.check_paths: true— a missing snippet is now a build failure, not a silent skip.validation.links.not_founddowngraded toinfo, deliberately and with the reasoning recorded inmkdocs.yml: included root documents carry repo-relative links that are correct where most people read them but sit outside the docs tree inside the site. That check is cosmetic here;check_pathsis the one that matters, and it is now loud.What keeps it fixed
scripts/check_docs_site.pyasserts the built site has content, not merely that it built. A page under 120 words is chrome rather than a document — the empty ones measured 68, the real ones 383–655.Verified by reintroducing the
../path and watching the build fail.16 pages now build, all carrying real content.