If you have [PlantUML](http://plantuml.com/) installed and available on your path, _mkbook_ will try to render any code blocks with a language tag of `plantuml` as inline SVG images.
If you have [KaTeX](https://github.com/KaTeX/KaTeX) installed and available on your path, _mkbook_ will try to render any code blocks with a language tag of `katex` as inline math blocks.
The current version of _mkbook_ doesn't copy any assets into your book—it only parses `.md` files and generates `.html` files. So if you want to include images or other assets, you're on your own. Support for assets is planned for the next minor release.
Any files in the `src` directory which are not included in `.gitignore` and do not end in the extension `.md` will be copied to the output folder. You can use this to include images, files, etc, for example the following image is an asset bundled with the book:
```md
```
<p><em>mkbook</em> may be installed using <em>Cargo</em> (<code>cargo install --force --path .</code> in the <em>mkbook</em> repo directory), and after that it presents a command-line interface:</p>
<p>If you have <ahref="http://plantuml.com/">PlantUML</a> installed and available on your path, <em>mkbook</em> will try to render any code blocks with a language tag of <code>plantuml</code> as inline SVG images.</p>
<p>If you have <ahref="http://plantuml.com/">PlantUML</a> installed and available on your path, <em>mkbook</em> will try to render any code blocks with a language tag of <code>plantuml</code> as inline SVG images.</p>
<p>If you have <ahref="https://github.com/KaTeX/KaTeX">KaTeX</a> installed and available on your path, <em>mkbook</em> will try to render any code blocks with a language tag of <code>katex</code> as inline math blocks.</p>
<p>If you have <ahref="https://github.com/KaTeX/KaTeX">KaTeX</a> installed and available on your path, <em>mkbook</em> will try to render any code blocks with a language tag of <code>katex</code> as inline math blocks.</p>
<p>The current version of <em>mkbook</em> doesn’t copy any assets into your book—it only parses <code>.md</code> files and generates <code>.html</code> files. So if you want to include images or other assets, you’re on your own. Support for assets is planned for the next minor release.</p>
<p>Any files in the <code>src</code> directory which are not included in <code>.gitignore</code> and do not end in the extension <code>.md</code> will be copied to the output folder. You can use this to include images, files, etc, for example the following image is an asset bundled with the book:</p>
<prestyle="background-color:#2d2d2d;">
<spanstyle="color:#f99157;">![chapter-six](book-chapter-six-5834.jpg </span><spanstyle="color:#d3d0c8;">"</span><spanstyle="color:#f2777a;">Photo by Kaboompics.com from Pexels</span><spanstyle="color:#d3d0c8;">"</span><spanstyle="color:#f99157;">)
</span></pre>
<figure><imgsrc="../book-chapter-six-5834.jpg"alt="chapter-six"title="Photo by Kaboompics.com from Pexels"><figcaption>Photo by Kaboompics.com from Pexels</figcaption></figure>
<p><em>mkbook</em> works on mostly a flat directory structure, however one level of sub-directories are supported in order to create sections within chapters. Files that don’t end in a <code>.md</code> extension are completely ignored. Each <code>.md</code> file in the root source directly is it’s own chapter. To create chapters with sub-sections, create a sub-directory in the root directory and then create a <code>README.md</code> file, which will become the root of the chapter, with all <code>.md</code> files in the sub-directory becoming sections in the chapter. The <code>title</code> in the <code>README.md</code> file’s frontmatter will be used as the name of the chapter.</p>
<p>The order of the book is based on the alphabetical order of the file names (actually it’s based on Rust’s <ahref="https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html#impl-PartialOrd%3Cstr%3E">implementation of <code>PartialOrd</code> for str</a>). Thus, it is recommended to lay out your book chapters with manual numbering of the file names, as such:</p>
<p>This tool aims to work somewhat similarly to <em>mdbook</em>, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.</p>
<p><em>mkbook</em> is my simpler alternative to <ahref="https://crates.io/crates/mdbook">mdbook</a> which is a great tool, but for which I really dislike some of the decisions they took, such as relying on javascript for highlighting and navigation, and including a lot of bells and whistles such as javascript-based search.</p>
Kenton Hamaluik
5 years ago
