@ -6,6 +6,8 @@ _mkbook_ is my simpler alternative to [_mdbook_](https://crates.io/crates/mdbook
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.
_mkbook_ may be installed using _Cargo_ (`cargo install --force --path .` in the _mkbook_ repo directory), and after that it presents a command-line interface:
@ -44,3 +44,111 @@ Mostly, know that the following extensions are enabled:
More details in second paragraph.
```
## Syntax Highlight
GFM syntax highlighting is also available by using fenced code tags with a label denoting the language, as such:
~~~md
```c++
#include<stdio>
int main() {
std::cout << "Hello, world!" <<std::endl;
return 0;
}
```
~~~
which results in:
```c++
#include<stdio>
int main() {
std::cout << "Hello, world!" <<std::endl;
return 0;
}
```
To denote the language you can either use one the language's extensions as the label, or the full name of the language (which is **not** case-sensitive).
The list of supported languages is currently as follows:
_mkbook_ currently only supports two types of assets to use in rendering: assets (images, etc), and documents (markdown files).
_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.
## `mkbook.toml`
_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:
* 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`)
If the `mkbook.toml` file or any of the entries are missing, default values will be used.
### Sample
```toml
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.
"""
```
### Default Values
`title`
: "My Cool Book"
`author`
: "Anonymous"
`pubdate`
: The date the book was built from the command line, in UTC time
`url`
: ""
`description`
: ""
## Assets
@ -16,6 +63,7 @@ For now, _mkbook_ only works on a flat list of markdown files, with the intent o
_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.
## Assets
_mkbook_ currently bundles two assets which get written into the book directory: `favicon.ico`, and `icons.svg`. `favicon.ico` is the [Font Awesome 5 book icon](https://fontawesome.com/icons/book?style=solid), and `icons.svg` contains 3 [Font Awesome 5](https://fontawesome.com/) arrow icons: [arrow-left](https://fontawesome.com/icons/arrow-left?style=solid), [arrow-right](https://fontawesome.com/icons/arrow-right?style=solid), and [arrow-up](https://fontawesome.com/icons/arrow-up?style=solid) which are used for navigation. These files are compiled into the _mkbook_ binary using the [`include_bytes!` macro](https://doc.rust-lang.org/std/macro.include_bytes.html), and written to the output folder on each build.
## Styling
_mkbook_ utilizes [Sass](https://sass-lang.com/) to define it's styles; you can view the sources [on github](https://github.com/hamaluik/mkbook/tree/master/style). In _mkbook_'s build script, the styles are compiled from their native `.scss` format into a single, compressed `.css` file using [sass-rs](https://crates.io/crates/sass-rs). The resulting `.css` file is then bundled into the binary using the [`include_str!` macro](https://doc.rust-lang.org/std/macro.include_str.html). When a book is generated, this `.css` is written to the output folder as `style.css`, where it is included by each generated `.html` file.
## Templates
_mkbook_ contains two template files: one for the index, and one for each page / chapter, and uses [Askama](https://crates.io/crates/askama) to render the templates. Since the _Askama_ templates are compiled when _mkbook_ is compiled, it is not currently possible to change the templates at run time. You can view the sources for these templates [on github](https://github.com/hamaluik/mkbook/tree/master/templates).
## Markdown Formatting
Markdown is formatted usiing [comrak](https://crates.io/crates/comrak) with some specific options, see the [Markdown chapter](02-markdown.html) for more information.
## Syntax Highlighting
Code is syntax-highlighted using [syntect](https://crates.io/crates/syntect) with the default langauges and the `base16-eighties` colour scheme.
<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>
<li><ahref="06-how-it-works.html">How it Works</a></li>
</ol>
</nav>
<navclass="small">
@ -60,6 +64,7 @@
<article>
<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>
<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>To denote the language you can either use one the language’s extensions as the label, or the full name of the language (which is <strong>not</strong> case-sensitive).</p>
<p>The list of supported languages is currently as follows:</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> currently only supports two types of assets to use in rendering: assets (images, etc), and documents (markdown files).</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>
<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>
</ul>
<p>If the <code>mkbook.toml</code> file or any of the entries are missing, default values will be used.</p>
</span><spanstyle="color:#d3d0c8;">_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:#d3d0c8;">
</span><spanstyle="color:#d3d0c8;">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>For now, <em>mkbook</em> only works on a flat list of markdown files, with the intent of each markdown file being its own chapter. Subdirectories and files that don’t end in a <code>.md</code> extension are completely ignored. 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>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>
<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><em>mkbook</em> utilizes <ahref="https://sass-lang.com/">Sass</a> to define it’s styles; you can view the sources <ahref="https://github.com/hamaluik/mkbook/tree/master/style">on github</a>. In <em>mkbook</em>’s build script, the styles are compiled from their native <code>.scss</code> format into a single, compressed <code>.css</code> file using <ahref="https://crates.io/crates/sass-rs">sass-rs</a>. The resulting <code>.css</code> file is then bundled into the binary using the <ahref="https://doc.rust-lang.org/std/macro.include_str.html"><code>include_str!</code> macro</a>. When a book is generated, this <code>.css</code> is written to the output folder as <code>style.css</code>, where it is included by each generated <code>.html</code> file.</p>
<p><em>mkbook</em> contains two template files: one for the index, and one for each page / chapter, and uses <ahref="https://crates.io/crates/askama">Askama</a> to render the templates. Since the <em>Askama</em> templates are compiled when <em>mkbook</em> is compiled, it is not currently possible to change the templates at run time. You can view the sources for these templates <ahref="https://github.com/hamaluik/mkbook/tree/master/templates">on github</a>.</p>
<p>Markdown is formatted usiing <ahref="https://crates.io/crates/comrak">comrak</a> with some specific options, see the <ahref="02-markdown.html">Markdown chapter</a> for more information.</p>
<p>Code is syntax-highlighted using <ahref="https://crates.io/crates/syntect">syntect</a> with the default langauges and the <code>base16-eighties</code> colour scheme.</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