1.3 KiB
Documentation Guidelines
Markdown Linting
Run: bunx markdownlint-cli2 'docs/**/*.md'
Word Count Rule (file-length)
Documents are limited to 3,000 words (error) with a warning at 2,500 words. This counts words, not lines.
Excluding Tables from Word Count
Large data tables (3+ rows) should be wrapped with <!-- wordcount:off --> / <!-- wordcount:on --> directives so they don't inflate the word count. The rule reads these from disk since markdownlint redacts HTML comment content.
Some prose here counts toward the limit.
<!-- wordcount:off -->
| Column A | Column B | Column C |
|----------|----------|----------|
| data | data | data |
| ... hundreds of rows ... |
<!-- wordcount:on -->
More prose here counts again.
When to use: Any table with 3+ rows in a document approaching the word limit. A helper script wraps all tables automatically:
./tooling/scripts/wrap-tables-with-directives.sh docs/path/to/file.md
When NOT to use: Don't wrap prose sections — the limit exists to enforce document decomposition (SRP for docs).
Adding Directives to New Documents
When creating data-heavy documents (research, inventories, competitive analysis), wrap tables proactively. The word count limit applies to prose — tables are structured data that doesn't benefit from splitting.