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.64k stars 1.61k forks source link

[Suggestion] Special Links Document for Common Links #502

Open Havvy opened 6 years ago

Havvy commented 6 years ago

In the Rust Reference, but presumably in other books as well, there is a lot of cross-linking. Every page has to copy this link around, and if the link changes, every page that links to it has to be updated. I'd rather there be a central list of these common links.

As such, much like there's a SUMMARY.md, I'd like to see a new special filed added called LINKS.md or LINKS.mdbook.md or LINKS.mdbook or something similar. This special page would only be able to only contain reference links of the style [name]: url. This page would then be appended (not prepended) to each normal markdown page (so not SUMMARY.md) before passed to the markdown renderer.

The reason for being appended is that the first reference link definition is used, so if a page defines one itself that clashes with one from the common list, it should be the one that is used.

Thoughts?

Michael-F-Bryan commented 6 years ago

This sounds like something which would be perfect for a pre-processor plugin to do. Technically it could be added as part of the html renderer, but it sounds more like something you'd do as part of pre-processing before sending the document to the renderer...

schell commented 3 years ago

I am looking for this specifically. Has anyone started on a pre-processor like this yet? If not, I'd gladly make this contribution.

schell commented 3 years ago

I think this may be accomplished by using the default #include behavior to add a set of links to the bottom of your files:

{{#include reflinks.md}}

of course this process isn't totally automatic.