_mkbook_ is my simpler alternative to [_mdbook_](https://crates.io/crates/mdbook) 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.
This tool aims to work somewhat similarly to _mdbook_, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.
If you're not familiar with _mdbook_, _mkbook_ is a tool to convert a collection of [Markdown](https://commonmark.org/) files into a static website / book which can be published online. It was created to help me write documentation with minimum fuss while presenting it in an easy-to-consume manner.
## Command-line Interface
_mkbook_ may be installed using _Cargo_ (`cargo install --force --path .` in the _mkbook_ repo directory), and after that it presents a command-line interface:
```
```sh
$ mkbook
mkbook 0.1.0
mkbook 0.2.0
Kenton Hamaluik <kenton@hamaluik.ca>
@ -33,9 +37,31 @@ SUBCOMMANDS:
init initialize a mkbook directory tree
```
Currently, only the `build` subcommand does anything (it builds your book!), but this functionality is still WIP:
### The Init Command
The init command is a tool to help you get started, and will create an initial `README.md` file and a stub of your first chapter.
```sh
$ mkbook init --help
mkbook-init
initialize a mkbook directory tree
USAGE:
mkbook init [OPTIONS]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-d, --directory <directory> an optional directory to initialize into [default: src]
```
### The Build Command
The build command is the primary command for _mkbook_, and is responsible for taking the `.md` files and building the resulting website.
_mkbook_ nominally utilizes [CommonMark](https://commonmark.org/) with some [GFM](https://github.github.com/gfm/) extensions through the use of the [comrak](https://crates.io/crates/comrak) crate. In using _comrak_, a specific set of options are used, which are listed here:
_mkbook_ relies pretty extensively on [Markdown](https://daringfireball.net/projects/markdown/) for its ease of use. If you're not familiar with _Markdown_, it is a simple markup language that is design to be easy to read and write in plain text, and then (relatively) easy for a computer to convert into other formats such as HTML or LaTeX.
Each `.md` file can optionally contain a header with metadata describing the document. If the header isn't present, default values will be used which may look ugly.
# Front Matter
To insert a header into a `.md` file, insert three dashes (`---`), followed by a new-line, followed by the front matter contents, followed by a newline, then another three dashes and a new-line. The metadata is in the [TOML](https://github.com/toml-lang/toml) format, so for example the front-matter (and first line) for this file looks like:
Each `.md` file can optionally contain a header with metadata describing the document. If the header isn't present, or if any keys are missing, default values will be used.
To insert a header into a `.md` file, insert three dashes (`---`), followed by a new-line, followed by the front matter contents, followed by a newline, then another three dashes and a new-line. The metadata is in the [TOML](https://github.com/toml-lang/toml) format, so for example the front-matter (and first line) for a file could look like this:
```md
---
title = "Front Matter"
author = "Kenton Hamaluik"
pubdate = 2019-11-29T15:22:00-07:00
---
Each `.md` file can optionally contain a header with metadata describing the document. If the header isn't present, default values will be used which may look ugly.
# Front Matter
Each `.md` file can optionally contain a header with metadata describing the document. If the header isn't present, or if any keys are missing, default values will be used.
```
## Supported Keys
@ -20,5 +26,16 @@ The list of supported keys is subject to change, but for now it is as follows:
title
: A human-readable title for the document
: A human-readable title for the document (defaults to the filename)
author
: The author (or authors) who wrote the chapter (defaults to "Anonymous")
pubdate
: The [RFC 3339](http://tools.ietf.org/html/rfc3339) timestamp of when the chapter was published (defaults to the time at build)
url
: The relative URL of the file, defaults to the generated route (you probably shouldn't set this one)
_mkbook_ follows a fairly simple directory structure for now, with a `mkbook.toml` file declaring the book's metadata, and `.md` files defining each chapter of the book.
# Structure
## `mkbook.toml`
_mkbook_ follows a fairly simple directory structure for now, with a `README.md` file declaring the book's metadata, and `.md` files defining each chapter of the book.
_mkbook_ generally requires a `mkbook.toml` file to reside in your source directory. This file is responsible for defining the metadata associated with your book:
## `README.md`
_mkbook_ generally requires a `README.md` file to reside in your source directory. This file is responsible for defining the metadata associated with your book:
* The book's title (`title`)
* The book's author (`author`)
* The publication date (`pubdate`)
* The canonical URL for the book (`url`)
* A markdown-formatted description of the book (`description`)
* A markdown-formatted description of the book
If the `mkbook.toml` file or any of the entries are missing, default values will be used.
If the `README.md` file or any of the entries are missing, default values will be used. The `README.md` file should be formatted as any other page, with the `title`, `author`, `pubdate`, and `url` specified in the frontmatter, and the book description the _Markdown_ contents of the `README.md` file.
### Sample
```toml
```md
---
title = "The mkbook Book"
author = "Kenton Hamaluik"
url = "https://hamaluik.github.io/mkbook/"
description = """
_mkbook_ is my simpler alternative to [mdbook](https://crates.io/crates/mdbook) 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.
---
This tool aims to work somewhat similarly to _mdbook_, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.
"""
_mkbook_ is my simpler alternative to [mdbook](https://crates.io/crates/mdbook)
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.
This tool aims to work somewhat similarly to _mdbook_, but is generally intended
to be a more minimal alternative that is customized more towards my needs and
desires than anything else.
```
### Default Values
@ -53,9 +61,7 @@ This tool aims to work somewhat similarly to _mdbook_, but is generally intended
## Assets
```rust
unimplemented!()
```
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.
There isn't any way to customize the templates nor the CSS yet, though I will investigate this if the need arises.
# Customization
There isn't any way to customize the templates nor the CSS yet, though I will investigate this if the need arises. This is because both the templates and CSS are currently compiled at compile-time instead of run-time.
_mkbook_ generates a completely static, javascript-free website from a series of Markdown files. All of the layout and styling is controlled purely by hand-crafted CSS specific to this book's purpose.
_mkbook_ is my simpler alternative to [mdbook](https://crates.io/crates/mdbook) 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.
This tool aims to work somewhat similarly to _mdbook_, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.
<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"><em>mdbook</em></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>
<p><em>mkbook</em> is my simpler alternative to <ahref="https://crates.io/crates/mdbook"><em>mdbook</em></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>
<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>If you’re not familiar with <em>mdbook</em>, <em>mkbook</em> is a tool to convert a collection of <ahref="https://commonmark.org/">Markdown</a> files into a static website / book which can be published online. It was created to help me write documentation with minimum fuss while presenting it in an easy-to-consume manner.</p>
<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>
</span><spanstyle="color:#d3d0c8;"></span><spanstyle="color:#6699cc;">Prints</span><spanstyle="color:#d3d0c8;"> version information
</span><spanstyle="color:#d3d0c8;">
</span><spanstyle="color:#d3d0c8;">FLAGS:
</span><spanstyle="color:#d3d0c8;"> -h, --help
</span><spanstyle="color:#d3d0c8;"> Prints help information
</span><spanstyle="color:#d3d0c8;">
</span><spanstyle="color:#d3d0c8;"> -V, --version
</span><spanstyle="color:#d3d0c8;"> Prints version information
</span><spanstyle="color:#6699cc;">SUBCOMMANDS:
</span><spanstyle="color:#d3d0c8;"></span><spanstyle="color:#6699cc;">build</span><spanstyle="color:#d3d0c8;"> build the book
</span><spanstyle="color:#d3d0c8;"></span><spanstyle="color:#66cccc;">help</span><spanstyle="color:#d3d0c8;"> Prints this message or the help of the given subcommand(s)
</span><spanstyle="color:#d3d0c8;"></span><spanstyle="color:#6699cc;">init</span><spanstyle="color:#d3d0c8;"> initialize a mkbook directory tree
</span><spanstyle="color:#d3d0c8;"></span><spanstyle="color:#6699cc;">-h,</span><spanstyle="color:#f2777a;"> --help</span><spanstyle="color:#d3d0c8;"> Prints help information
</span><spanstyle="color:#d3d0c8;"></span><spanstyle="color:#6699cc;">-V,</span><spanstyle="color:#f2777a;"> --version</span><spanstyle="color:#d3d0c8;"> Prints version information
</span><spanstyle="color:#d3d0c8;">
</span><spanstyle="color:#d3d0c8;">SUBCOMMANDS:
</span><spanstyle="color:#d3d0c8;"> build build the book
</span><spanstyle="color:#d3d0c8;"> help Prints this message or the help of the given subcommand(s)
</span><spanstyle="color:#d3d0c8;"> init initialize a mkbook directory tree
</span><spanstyle="color:#6699cc;">OPTIONS:
</span><spanstyle="color:#d3d0c8;"></span><spanstyle="color:#6699cc;">-d,</span><spanstyle="color:#f2777a;"> --directory </span><spanstyle="color:#d3d0c8;"><directory> an optional directory to initialize into </span><spanstyle="color:#cc99cc;">[</span><spanstyle="color:#d3d0c8;">default: src</span><spanstyle="color:#cc99cc;">]
</span></pre>
<p>Currently, only the <code>build</code> subcommand does anything (it builds your book!), but this functionality is still WIP:</p>
<p>The build command is the primary command for <em>mkbook</em>, and is responsible for taking the <code>.md</code> files and building the resulting website.</p>
</span><spanstyle="color:#d3d0c8;"> -h, --help Prints help information
</span><spanstyle="color:#d3d0c8;"> -V, --version Prints version information
</span><spanstyle="color:#6699cc;">FLAGS:
</span><spanstyle="color:#d3d0c8;"></span><spanstyle="color:#6699cc;">-h,</span><spanstyle="color:#f2777a;"> --help</span><spanstyle="color:#d3d0c8;"> Prints help information
</span><spanstyle="color:#d3d0c8;"></span><spanstyle="color:#6699cc;">-V,</span><spanstyle="color:#f2777a;"> --version</span><spanstyle="color:#d3d0c8;"> Prints version information
</span><spanstyle="color:#d3d0c8;">
</span><spanstyle="color:#d3d0c8;">OPTIONS:
</span><spanstyle="color:#d3d0c8;"> -i, --in <in> an optional directory to take the book sources from [default: src]
</span><spanstyle="color:#d3d0c8;"> -o, --out <out> an optional directory to render the contents into [default: book]
</span><spanstyle="color:#6699cc;">OPTIONS:
</span><spanstyle="color:#d3d0c8;"></span><spanstyle="color:#6699cc;">-i,</span><spanstyle="color:#f2777a;"> --in </span><spanstyle="color:#d3d0c8;"><in> an optional directory to take the book sources from </span><spanstyle="color:#cc99cc;">[</span><spanstyle="color:#d3d0c8;">default: src</span><spanstyle="color:#cc99cc;">]
</span><spanstyle="color:#d3d0c8;"></span><spanstyle="color:#6699cc;">-o,</span><spanstyle="color:#f2777a;"> --out </span><spanstyle="color:#d3d0c8;"><out> an optional directory to render the contents into </span><spanstyle="color:#cc99cc;">[</span><spanstyle="color:#d3d0c8;">default: book</span><spanstyle="color:#cc99cc;">]
<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> nominally utilizes <ahref="https://commonmark.org/">CommonMark</a> with some <ahref="https://github.github.com/gfm/">GFM</a> extensions through the use of the <ahref="https://crates.io/crates/comrak">comrak</a> crate. In using <em>comrak</em>, a specific set of options are used, which are listed here:</p>
<p><em>mkbook</em> nominally utilizes <ahref="https://commonmark.org/">CommonMark</a> with some <ahref="https://github.github.com/gfm/">GFM</a> extensions through the use of the <ahref="https://crates.io/crates/comrak">comrak</a> crate. In using <em>comrak</em>, a specific set of options are used, which are listed here:</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>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> relies pretty extensively on <ahref="https://daringfireball.net/projects/markdown/">Markdown</a> for its ease of use. If you’re not familiar with <em>Markdown</em>, it is a simple markup language that is design to be easy to read and write in plain text, and then (relatively) easy for a computer to convert into other formats such as HTML or LaTeX.</p>
<p><em>mkbook</em> relies pretty extensively on <ahref="https://daringfireball.net/projects/markdown/">Markdown</a> for its ease of use. If you’re not familiar with <em>Markdown</em>, it is a simple markup language that is design to be easy to read and write in plain text, and then (relatively) easy for a computer to convert into other formats such as HTML or LaTeX.</p>
<p>The above paragraph looks like this:</p>
<prestyle="background-color:#2d2d2d;">
<spanstyle="font-style:italic;color:#cc99cc;">_mkbook_</span><spanstyle="color:#d3d0c8;"> relies pretty extensively on
<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>Each <code>.md</code> file can optionally contain a header with metadata describing the document. If the header isn’t present, default values will be used which may look ugly.</p>
<p>To insert a header into a <code>.md</code> file, insert three dashes (<code>---</code>), followed by a new-line, followed by the front matter contents, followed by a newline, then another three dashes and a new-line. The metadata is in the <ahref="https://github.com/toml-lang/toml">TOML</a> format, so for example the front-matter (and first line) for this file looks like:</p>
<p>Each <code>.md</code> file can optionally contain a header with metadata describing the document. If the header isn’t present, or if any keys are missing, default values will be used.</p>
<p>To insert a header into a <code>.md</code> file, insert three dashes (<code>---</code>), followed by a new-line, followed by the front matter contents, followed by a newline, then another three dashes and a new-line. The metadata is in the <ahref="https://github.com/toml-lang/toml">TOML</a> format, so for example the front-matter (and first line) for a file could look like this:</p>
</span><spanstyle="color:#d3d0c8;">Each </span><spanstyle="color:#99cc99;">`.md`</span><spanstyle="color:#d3d0c8;"> file can optionally contain a header with metadata describing the document. If the header isn't present, default values will be used which may look ugly.
</span><spanstyle="color:#6699cc;"># Front Matter
</span><spanstyle="color:#d3d0c8;">
</span><spanstyle="color:#d3d0c8;">Each </span><spanstyle="color:#99cc99;">`.md`</span><spanstyle="color:#d3d0c8;"> file can optionally contain a header with metadata describing the document. If the header isn't present, or if any keys are missing, default values will be used.
<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> follows a fairly simple directory structure for now, with a <code>mkbook.toml</code> file declaring the book’s metadata, and <code>.md</code> files defining each chapter of the book.</p>
<p><em>mkbook</em> generally requires a <code>mkbook.toml</code> file to reside in your source directory. This file is responsible for defining the metadata associated with your book:</p>
<p><em>mkbook</em> follows a fairly simple directory structure for now, with a <code>README.md</code> file declaring the book’s metadata, and <code>.md</code> files defining each chapter of the book.</p>
<p><em>mkbook</em> generally requires a <code>README.md</code> file to reside in your source directory. This file is responsible for defining the metadata associated with your book:</p>
<ul>
<li>The book’s title (<code>title</code>)</li>
<li>The book’s author (<code>author</code>)</li>
<li>The publication date (<code>pubdate</code>)</li>
<li>The canonical URL for the book (<code>url</code>)</li>
<li>A markdown-formatted description of the book (<code>description</code>)</li>
<li>A markdown-formatted description of the book</li>
</ul>
<p>If the <code>mkbook.toml</code> file or any of the entries are missing, default values will be used.</p>
<p>If the <code>README.md</code> file or any of the entries are missing, default values will be used. The <code>README.md</code> file should be formatted as any other page, with the <code>title</code>, <code>author</code>, <code>pubdate</code>, and <code>url</code> specified in the frontmatter, and the book description the <em>Markdown</em> contents of the <code>README.md</code> file.</p>
</span><spanstyle="color:#99cc99;">_mkbook_ is my simpler alternative to [mdbook](https://crates.io/crates/mdbook) 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.
</span><spanstyle="color:#99cc99;">
</span><spanstyle="color:#99cc99;">This tool aims to work somewhat similarly to _mdbook_, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.
</span><spanstyle="font-style:italic;color:#cc99cc;">_mkbook_</span><spanstyle="color:#d3d0c8;"> is my simpler alternative to </span><spanstyle="color:#f99157;">[mdbook](https://crates.io/crates/mdbook)
</span><spanstyle="color:#d3d0c8;">which is a great tool, but for which I really dislike some of the decisions they
</span><spanstyle="color:#d3d0c8;">took, such as relying on javascript for highlighting and navigation, and
</span><spanstyle="color:#d3d0c8;">including a lot of bells and whistles such as javascript-based search.
</span><spanstyle="color:#d3d0c8;">
</span><spanstyle="color:#d3d0c8;">This tool aims to work somewhat similarly to </span><spanstyle="font-style:italic;color:#cc99cc;">_mdbook_</span><spanstyle="color:#d3d0c8;">, but is generally intended
</span><spanstyle="color:#d3d0c8;">to be a more minimal alternative that is customized more towards my needs and
</span><spanstyle="color:#d3d0c8;">desires than anything else.
<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><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>There isn’t any way to customize the templates nor the CSS yet, though I will investigate this if the need arises. This is because both the templates and CSS are currently compiled at compile-time instead of run-time.</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> generates a completely static, javascript-free website from a series of Markdown files. All of the layout and styling is controlled purely by hand-crafted CSS specific to this book’s purpose.</p>
<h1><ahref="#how-it-works"aria-hidden="true"class="anchor"id="headerhow-it-works"></a>How it Works</h1>
<p><em>mkbook</em> generates a completely static, javascript-free website from a series of Markdown files. All of the layout and styling is controlled purely by hand-crafted CSS specific to this book’s purpose.</p>
<p><em>mkbook</em> currently bundles two assets which get written into the book directory: <code>favicon.ico</code>, and <code>icons.svg</code>. <code>favicon.ico</code> is the <ahref="https://fontawesome.com/icons/book?style=solid">Font Awesome 5 book icon</a>, and <code>icons.svg</code> contains 3 <ahref="https://fontawesome.com/">Font Awesome 5</a> arrow icons: <ahref="https://fontawesome.com/icons/arrow-left?style=solid">arrow-left</a>, <ahref="https://fontawesome.com/icons/arrow-right?style=solid">arrow-right</a>, and <ahref="https://fontawesome.com/icons/arrow-up?style=solid">arrow-up</a> which are used for navigation. These files are compiled into the <em>mkbook</em> binary using the <ahref="https://doc.rust-lang.org/std/macro.include_bytes.html"><code>include_bytes!</code> macro</a>, and written to the output folder on each build.</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
4 years ago