documentation-layout caps blog posts and other site content, which are not documentation #1111

New issue

Open

opened 2026-08-17 01:58:54 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-17 01:58:54 +00:00

Member

documentation-layout walks every Markdown file in a repo and applies the band's per-file size cap. In a static-site repo that includes the site's own content.

coilysiren/website is the case. All nine blog posts under src/pages/posts/ exceed the small band's 40-line cap, the longest being a 480-line published article on Azure OpenAI and Terraform. Two more src/pages/ routes and a draft fail the same way.

Trimming a published article to 40 lines to satisfy a documentation rule is destroying writing. The rule has no business there.

Same shape as the skill exemption

This is the second instance of one pattern: the hook applies a documentation cap to Markdown that is not documentation. Kai settled the first one by exempting SKILL.md and COMPOSED.md because check-skills owns them (#1109, PR #1110).

Blog content has no other owning hook. It is simply not documentation, so the exemption has to be about the tree rather than about a basename.

Why excludes cannot solve it

The band rule deliberately removed the per-file escape: excludes governs placement and flatness and no longer reaches a size cap. That was the right call for the case it targeted, nine individually excluded SKILL.md files. It leaves a content repo with no way to comply short of not running the hook.

Options

A content-root declaration. A repo names its site content root, and the hook skips size caps beneath it while still enforcing placement. Narrow, declared once, and visible in pyproject.toml rather than accumulating per file.
Scope the hook to documentation roots. Cap docs/, the root allowlist, and skill trees, and stop walking everything else for size. That matches what the hook is named for.
website stops subscribing. Loses placement and flatness enforcement too, which it currently benefits from.

Option 2 is the smallest description of the rule and the one that stops this recurring.

Meanwhile

coilysiren/website has its docs/ migrated and clean. The repo still fails the hook on content, so it cannot be called done, and it is the reason its epic checkbox stays open.

Epic: coilysiren/inbox#374.

`documentation-layout` walks every Markdown file in a repo and applies the band's per-file size cap. In a static-site repo that includes the site's own content. `coilysiren/website` is the case. All **nine** blog posts under `src/pages/posts/` exceed the small band's 40-line cap, the longest being a 480-line published article on Azure OpenAI and Terraform. Two more `src/pages/` routes and a draft fail the same way. Trimming a published article to 40 lines to satisfy a documentation rule is destroying writing. The rule has no business there. ## Same shape as the skill exemption This is the second instance of one pattern: the hook applies a documentation cap to Markdown that is not documentation. Kai settled the first one by exempting `SKILL.md` and `COMPOSED.md` because `check-skills` owns them (#1109, PR #1110). Blog content has no other owning hook. It is simply not documentation, so the exemption has to be about the tree rather than about a basename. ## Why excludes cannot solve it The band rule deliberately removed the per-file escape: `excludes` governs placement and flatness and no longer reaches a size cap. That was the right call for the case it targeted, nine individually excluded `SKILL.md` files. It leaves a content repo with no way to comply short of not running the hook. ## Options 1. **A content-root declaration.** A repo names its site content root, and the hook skips size caps beneath it while still enforcing placement. Narrow, declared once, and visible in `pyproject.toml` rather than accumulating per file. 2. **Scope the hook to documentation roots.** Cap `docs/`, the root allowlist, and skill trees, and stop walking everything else for size. That matches what the hook is named for. 3. **website stops subscribing.** Loses placement and flatness enforcement too, which it currently benefits from. Option 2 is the smallest description of the rule and the one that stops this recurring. ## Meanwhile `coilysiren/website` has its `docs/` migrated and clean. The repo still fails the hook on content, so it cannot be called done, and it is the reason its epic checkbox stays open. Epic: coilysiren/inbox#374.

coilyco-ops referenced this issue from coilysiren/website

2026-08-17 01:59:10 +00:00

docs: declare a band, 4 oversized docs #118

coilyco-ops added the

labels

2026-08-17 02:36:08 +00:00