Repository navigation
fix: use structure.readme as index.html when README.md also exists - #535
Conversation
fileToOutput() mapped every file named README to its directory's index.html, in addition to the configured book readme. When `structure.readme` points to another file in the same directory and a README.md page also exists (e.g. it is linked from SUMMARY.md), both pages were written to the same index.html and whichever was written last won. Keep README files as their directory's index only when the book readme does not already use that directory's index.html. Otherwise the README page is written to README.html like any other page. Fixes #287 Co-Authored-By: Claude Opus 5.5 <[email protected]>
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
There was a problem hiding this comment.
Devin Review found 1 potential issue.
1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)
| const isDirectoryReadme = | ||
| path.basename(filePath, path.extname(filePath)) == "README" && | ||
| !(fileReadme.exists() && path.dirname(filePath) == path.dirname(fileReadme.getPath())); | ||
|
|
||
| if ( | ||
| path.basename(filePath, path.extname(filePath)) == "README" || | ||
| (fileReadme.exists() && filePath == fileReadme.getPath()) | ||
| ) { | ||
| if (isBookReadme || isDirectoryReadme) { |
There was a problem hiding this comment.
🟡 Sibling README pages share one output
When a custom introduction shares a directory with README.md and README.markdown, isDirectoryReadme maps both pages to README.html. One article overwrites the other, so both sidebar links open the same content.
Learn more
HonKit generates one HTML file per page in the summary. Both .md and .markdown are supported page extensions (EXTENSIONS_MARKDOWN), and generatePages writes their output concurrently. With a custom introduction in their directory, the new branch sends both sibling README files through fileToOutput to README.html. Both pages remain separate in the summary but share one physical output file.
Example: Set structure.readme to intro.md, and list README.md and README.markdown with different content in SUMMARY.md. Both sidebar links target README.html; only whichever page wrote last is visible.
Recommended fix: Detect output-path collisions among prepared pages and assign distinct paths or reject conflicting source names before writing. Ensure URL generation uses the same mapping, and cover multiple supported README extensions in a website generation test.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Two files that only differ in extension (foo.md and foo.markdown) already map to the same .html anywhere in a book, and before this change both READMEs went to index.html together with the custom readme. So this isn't new, and having both README.md and README.markdown in the same folder seems rare enough that I'd keep it out of this PR.
<!-- Release notes generated using configuration in .github/release.yml at master --> ## What's Changed ### Bug Fixes * fix: use structure.readme as index.html when README.md also exists by @b84330808 in #535 ## New Contributors * @b84330808 made their first contribution in #535 **Full Changelog**: v6.2.2...v6.2.3 Co-authored-by: azu <[email protected]>
<!-- Release notes generated using configuration in .github/release.yml at master --> ## What's Changed ### Bug Fixes * fix: use structure.readme as index.html when README.md also exists by @b84330808 in #535 ### CI * fix: remove --scripts-prepend-node-path flag for npm 12 by @azu in #537 ## New Contributors * @b84330808 made their first contribution in #535 **Full Changelog**: v6.2.2...v6.2.4 Co-authored-by: azu <[email protected]>
Fixes #287
Summary
When
structure.readmepoints to a different file (e.g.README.other.md) and aREADME.mdpage also exists in the same directory (for example because SUMMARY.md still links to it, as thehonkit inittemplate does), both pages are written toindex.html. Which one ends up there depends on which page is written last, so the result can change between builds, and both sidebar entries link to./.The cause is
fileToOutput(): it sends every file namedREADME.*to its directory'sindex.html, in addition to the configured book readme.Changes
fileToOutput()now treats aREADME.*file as its directory's index only when the book readme doesn't already use that directory'sindex.html. Otherwise the page is written toREADME.htmllike any other page.README.mdis the book readme, andsub/README.mdstill becomessub/index.html(so thefileToOutputtests in feat: add prettyUrls option for clean directory URLs #499 still hold).Breaking Changes
None for default setups. In the setup above,
README.mdis now emitted asREADME.html(and links to it resolve there) instead of overwriting the configured readme'sindex.html.The JSON generator has a similar collision on
README.json. I left it out of this PR becausejson/onFinish.tsrelies on that file name.Test Plan
src/output/__tests__/website.tsfails without the change (noREADME.htmlis generated) and passes with it, along with the rest ofnpx jest srcinpackages/honkit.README.md,README.other.md,book.json("structure": { "readme": "README.other.md" }) and* [Introduction](README.md)in SUMMARY.md.index.htmlnow always has theREADME.other.mdcontent andREADME.htmlhas theREADME.mdcontent.I used Claude Code to write this change.