search

rust-lang / mdBook

Create book from markdown files. Like Gitbook but implemented in Rust
https://rust-lang.github.io/mdBook/
Mozilla Public License 2.0
17.61k stars 1.61k forks source link

It is recommended that all md files in the directory be converted to html #830

Open riverlow opened 5 years ago

riverlow commented 5 years ago

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.mdhas this content:

[Link to xxx](xxx.md)

This only work when xxx.md is placed in SUMMARY.md

mrec commented 5 years ago

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.

riverlow commented 5 years ago

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.

`

meichstedt commented 5 years ago

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.

simonmichael commented 3 years ago

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).

stewartadam commented 1 year ago

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.

n8behavior commented 4 months ago

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.