guide: use more root-relative links, and replace duplication with templated markdown #310
Conversation
|
Can we enforce any of these conventions with CI (or did this PR do that and I just missed it)? |
| You can install it locally by running: `cargo install cargo-nextest --locked` | ||
|
|
||
| See the [cargo-nextest](https://nexte.st/) documentation for more info. | ||
| {{ #include /_fragments/nextest_tip.md }} |
There was a problem hiding this comment.
Did you have to put the fragment inside the admonish block here, at the consuming side? (Or did you do it this way so that consumers of the fragment can decide if it's in an admonishment or not).
There was a problem hiding this comment.
unfortunately, this is a limitation of how the current templating infrastructure works :(
I'm sure with a bit more custom preprocessing / hacking I could maybe get this working, but at a certain point, you gotta throw in the towel and bend to the tool you're using
We don't have much guide-level linting infrastructure, but we could certainly look into extending our |
…with templated markdown (microsoft#310)" This reverts commit b09016f.
…tion with templated markdown (#310)" (#322) Turns out absolute links don't work correctly: rust-lang/mdBook#1764 This means that the guide is busted when published on openvmm.dev/guide, even if it works correctly locally. Unfortunate...
This PR contains a few related changes:
../../foo, just use/path/to/foo, which is likely to be a more stable in the face of content being reorganized._images/folders, just have a single_images/folder, which can be referred to via/_images/image.pngregardless where themdfile is in the repo._fragments/folder, and leveraging mdbook's built-in{{ #include path/to/content.md }}directives.These are all relatively straightforward changes, though I did run in rust-lang/mdBook#1512 while working on 3.
I quickly hacked together a workaround using the existing
mdbook-openvmm-shimpreprocessor we have, which did the trick.Of course, it'd be nice if this was fixed upstream, but we'll cross that bridge another day...