D0018 readme-index-clash¶
Rule: No docs folder holds both README.md and index.md.
| Code | D0018 (stable, never reused) |
| Id | readme-index-clash |
| Category | book |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | deny |
Zensical does not say which of README.md and index.md it builds when a folder holds both |
| small-workspace | deny |
Zensical does not say which of README.md and index.md it builds when a folder holds both |
| medium | deny |
Zensical does not say which of README.md and index.md it builds when a folder holds both |
| big | deny |
Zensical does not say which of README.md and index.md it builds when a folder holds both |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Why¶
Zensical turns both README.md and index.md into a folder's page; its docs call the result of having both in the same folder undefined. One of the two is built and the other sits in the repository unread, and which one wins can change with a Zensical release.
The lint looks for a docs folder that holds both names. The project root is outside the docs folder and never counts: a repository's own README.md is for GitHub, not the book.
How to fix¶
Keep one of the two files. index.md is Zensical's own convention for a folder's page; fold any content worth keeping from README.md into it and delete README.md, or the other way round if the project prefers README.md throughout its docs folder.
Configure¶
Allow one finding in the code with // spirit-level: allow(readme-index-clash) <reason> (waivers); the code works there too, as in [lints.D0018].