mdBook
mdBook copied to clipboard
rust-lang
It is recommended that all md files in the directory be converted to html
It is recommended that all md files in the directory be converted to html instead of just the ones that appear in SUMMARY.md, so that the internal links will work as you would see in github.
As now, if my readme.md has this content:
[Link to xxx](xxx.md)
This only work when xxx.md is placed in SUMMARY.md
Tangential, but are there use cases where this is deliberate? I'm wondering whether it would be helpful to have the book build report any orphan (non-SUMMARY) pages it finds.
What I exactly want is, the link is only in a readme.md file but is not in the SUMMARY.md can still work.
Now, such content in a readme.md file:
[Link to xxx](xxx.md)
this link will be rendered as http://.../xxx.html, so if this link is not in the SUMMARY.md, the page won't be found.
`
I just stumbled across this issue trying to find out whether there's a way to do the same thing, more or less.
My use case would be a chapter that contains a complete reference of many concepts, each as individual markdown files. I would like to add just the chapter as such in the summary, and link to an index file. However, I wouldn't want to have 30 or more child pages linked underneath that chapter in the summary, i.e. not listed separately in the menu, as that would pretty much blow up the menu IMHO.
Apart from parsing non-referenced files, a solution could also be to suppress certain items from being displayed in the menu – I can't think of a markdown compatible way to do that though.
Another use case: my site contains many old versions of reference manuals, I don't want all of these linked in the sidebar but I would like them to be rendered so I can navigate to them (using some js that adds a version selector to manuals).
Similarly, I'm using mdbook to write a user and developer guide for my software. I'd like to be able to include a page with a table of design decisions in SUMMARY.md and have that page link to individual decisions.
Including each decision in the SUMMARY.md would be too verbose.
Similarly, I'm using mdbook to write a user and developer guide for my software. I'd like to be able to include a page with a table of design decisions in SUMMARY.md and have that page link to individual decisions.
Including each decision in the SUMMARY.md would be too verbose.
This is exactly what I'm also trying to do with adrs, a Rust-base CLI tool which creates ADR files and generates a TOC for each decision. Same would be true for adr-tools and the many other CLI ports.
This point being that there are many tools that generate and manage collections of markdown files, wikis come to mind, that are already linked in a specific way. Being able to the starting page(s) of a collection without having to manually link every page in the collection via SUMMARY.md seems reasonable and doable.
I see this has been asked for in many other issues and all have been closed accept #703 and #830. I'd be interested to tackle this issue, but don't want to tackle something that's going to be rejected because the maintainers don't like the idea. It would be helpful if the maintainers could indicate a preference or that they feel the current all-pages-must-be-in-the-summary approach is what they want.
