Skip to content

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

[lints.readme-index-clash]
level = "deny"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(readme-index-clash) <reason> (waivers); the code works there too, as in [lints.D0018].