rust-lang
Include external, raw file
I'm sorry if this is obvious, I couldn't figure it out, though: Putting a thought into rust-lang-nursery/reference#398, one could include a SVG into the book which reacts to the book's CSS variables to stay on par with the theme chosen by the user. This however would require one to include the SVG directly into the final HTML (that is, instead of <object or <img), so that the CSS inherited from mdbook's <body> actually applies.
I can see no way to include a raw, external file into a book's final HTML, given a .md as the starting point. The provided {{#include }} seems to tinker quite a lot with file's content and it destroys the SVG's syntax.
Is there a way to pull raw, external stuff into the final HTML, with .md as the starting point and without using the API ?
I have a similar situation where I want to insert SVG graphs that adapt to the current theme. Would be great if there were a {{#include_raw }} to just embed files directly.
Actually I was able to use {{#include foo.svg}} by making sure the contents inside of the
Instead of making a {{#include_raw }}, maybe the best option is for {{#include }} to detect when it is getting called inside of a html context, in which case it doesnt modify what it is being inserted. So user would have to do this:
<div>
{{#include_raw foo.svg}}
</div>
I have found a very compact solution to enable SVG images to be rendered nicely with a dark theme that doesn't rely on #include or preprocessors: a small extra CSS file that sets img { color-scheme: light | dark; } appropriately, with one rule per theme, and a small modification to the SVG files that looks like this (the exact rules depend on the SVG file contents but can usually be discovered easily):
<defs>
<style>
:root { color: #1e1e1e; }
@media (prefers-color-scheme: dark) {
:root { color: #d3d3d3; }
}
</style>
</defs>
While decidedly not perfect, it's flexible and leaves the <img> tags in the source Markdown so that they can be rendered by GitHub. (And yes, the GitHub Markdown preview is legible too!)
You can see it in action in https://github.com/amaranth-lang/rfcs/commit/43f8f04e2a563381573c9e6cc9b12a67ac8f71fb.
I also would like this feature but from a different point of view.
I have a project and I would like to include its man pages in the online mdbook render. My current solution is to use pandoc to convert the man pages into markdown which are then included in the mdbook source, but this produces man pages that look pretty different that what is seen on the command line when running man ...). Other tools are already able to process man pages into HTML persisting the layout and look (namely, aha can do this with MAN_KEEP_FORMATTING=1 COLUMNS=80 man aha | ul | aha > man-aha.html). Using the {{ #include ... }} with these files mangles the ascii-style layout (most obviously converting indented lines to code blocks). This mangling is still done when using a preprocessor like mdbook-cmdrun to inject the HTML directly into the markdown (what I presume the {{ #include }} is doing as well).
I was able to get a solution for my situation after reading the common mark spec on HTML blocks. I am using the cmdrun preprocessor and wrapping the resulting headerless HTML with the pre HTML tag.
The entire contents of my file are then
<pre>
<!-- cmdrun MAN_KEEP_FORMATTING=1 COLUMNS=80 man path/to/man.1 | ul | aha --no-header -->
</pre>
which is then rendered as if the aha-generated HTML was placed within the boundaries of the mdbook sidebar and top bar :smile:
I still support the possibility of bypassing the common-mark spec and, in general, having a solution for including some sort of "pre-generated" or "raw" files that can be included without further modification by the cmark markdown->html translation.