docs-site
Skill673 starsChanged 15 days agoMITView on GitHub
Use when adding/editing doc pages or building/previewing/deploying the properdocs site — "add a doc page", "deploy docs", "why isn't my new page showing up". Covers the docs_dir:. quirk, the exclude-glob trap and auto-generated pages.
5 other projects use a version of this.
Adopted by
Most recently taken up by
- navjyotnishant/nj-agentstheir own version, first seen Oct 15, 2026
- Lee-Dongwook/E2E-Self-Healtheir own version, first seen Oct 9, 2026
- VPDPersonal/Aspid.MVVMtheir own version, first seen Oct 9, 2026
- INERATE/ateliertheir own version, first seen Sep 22, 2026
- sentasity/cadencetheir own version, first seen Aug 5, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- VPDPersonal/Aspid.MVVM★ 65same name
- Lee-Dongwook/E2E-Self-Heal★ 9same name
- INERATE/atelier★ 2same name
- navjyotnishant/nj-agents★ 1same name
- sentasity/cadence★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- add-system-actionSkill
- chezmoi-scriptsSkill
- fork-and-customizeSkill
- repo-gotchasSkill
- run-testsSkill
- ship-featureSkill
- skill-layoutSkill
- vm-labSkill
The file
Files
Docs site (properdocs/mkdocs) in personal-os-setup
The config file is properdocs.yml at repo root (not the conventional mkdocs.yml).
The one thing to know before touching anything here
docs_dir: . — the entire repo root is the mkdocs source, not a docs/ subfolder in the usual sense. That's why README.md, CHANGELOG.md and CONTRIBUTING.md at repo root are part of the published site (see the nav: block), and why any new top-level directory you add is crawled into the docs build unless excluded. The mkdocs-exclude plugin's glob list in properdocs.yml keeps .venv/**, dist/**, .ruff_cache/**, .github/**, etc. out; mkdocs-same-dir is the other half of making docs_dir: . work.
If you add a new top-level directory (a cache dir, a build output dir, a new tool's data dir) — add it to that exclude list, or it may get published.
Auto-generated pages — don't hand-maintain these
scripts/gen_doc_stubs.py(via thegen-filesplugin) walkssrc/**/*.pyand generates one API-reference stub per module underpackage/<path>.md(::: <dotted.module.path>mkdocstrings directive) pluspackage/SUMMARY.md. A new module undersrc/automatically gets an API-reference page — no manual nav edit. Skips__init__.py.scripts/gen_example_pages.pydoes the same fordocs/examples/**/*.py, pulling each file's module docstring (viaast.get_docstring) intodocs/examples/index.md's table. ASyntaxErrorin an example is swallowed silently — the build won't fail, the example just loses its description.literate-nav(nav_file: SUMMARY.md) drives theAPI Reference:/examples sub-navs from those generated files.
Adding a genuinely new hand-written doc page
Files added under docs/ generally surface automatically via same-dir/mkdocs-material conventions. If a page needs a specific slot in the top-level nav, edit properdocs.yml's nav: list directly. Always verify with a local preview — auto-discovery interacting with docs_dir: . isn't always intuitive.
Building/previewing
make deploy-doc-local→properdocs serve -f properdocs.yml— local live preview; run it after any docs change before opening a PR.make deploy-doc-gh→properdocs gh-deploy -f properdocs.yml --strict— pushes directly to thegh-pagesbranch. Remote-mutating: run it deliberately (CI normally does it), and confirm with the user first.
When docs actually go live in CI
main-release.yml deploys docs only on main after successful artifact publication, including a recovered release, and checks out the released tag. A PR with only docs:/chore: commits merged to main will not deploy docs even though the content changed — those types don't bump the version. To publish immediately, bundle the doc change with a releasable commit (feat/fix/perf), or run make deploy-doc-gh after confirming with the user (it pushes to a shared branch).
First-time GitHub Pages setup (rarely needed again): repo Settings → Actions → General → Workflow permissions → "Read and write permissions"; Pages settings → "Deploy from a branch" → gh-pages.
Restructuring an existing page (splits, moves)
Shape a reader-facing guide two-track: a Quick start part (numbered steps ending in a "if something doesn't work" symptom→fix list) then an Advanced part (how the pieces relate, then one section per feature). When one page serves two audiences, split it by topic rather than deepening it — cross-link both halves top and bottom.
When splitting: write the new page, trim the old one to its own topic, add the index bullet in docs/index.md (nav is filesystem-derived, but that link list is manual), cross-link both ways, and keep a moved page's images in whichever file still references them (relative image paths break silently). Repoint every reference in the same pass — including skill files, since a stale pointer sends a reader hunting for moved content.
Verify a restructure with the URL-coverage check, not a re-read — the procedure is in references/docs-build.md. It catches dropped links; it says nothing about prose, so still re-read the new page for the small things a rewrite thins out (workarounds, captions, caveats).
Published docs are public — some findings don't belong here
docs/ is crawled into the published site, so anything written under it is public advice. Never document a specific live exposure finding about a real deployment (which network path bypasses a safeguard, a real router/firewall state) — that's chat-only guidance. When a security caveat is deliberately kept out of a doc, say so in chat and name where the real fix lives. Before pushing to a public doc: scan for URLs, UUID/email/IPv4/hostname-shaped values and long token-shaped strings — a debrid/API key can hide percent-encoded inside a manifest URL that looks harmless.
Linked Files
references/docs-build.md— how the mkdocstrings auto-stub walker works, the hyphenated-module-path trap when vendoring code that ships.pyunder a data dir, local strict build verification, and the URL-coverage check for restructures.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

