Structure

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.

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

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

---
title = "The mkbook Book"
author = "Kenton Hamaluik"
url = "https://hamaluik.github.io/mkbook/"
---

_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

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:

![chapter-six](book-chapter-six-5834.jpg "Photo by Kaboompics.com from Pexels")

chapter-six — Photo by Kaboompics.com from Pexels

Documents

mkbook 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 .md extension are completely ignored. Each .md 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 README.md file, which will become the root of the chapter, with all .md files in the sub-directory becoming sections in the chapter. The title in the README.md file’s frontmatter will be used as the name of the chapter.

The order of the book is based on the alphabetical order of the file names (actually it’s based on Rust’s implementation of PartialOrd for str). Thus, it is recommended to lay out your book chapters with manual numbering of the file names, as such:

src/
├── README.md
├── 00-foreword.md
├── 01-introduction.md
├── my-picture.jpg
└── 02-my-first-chapter
    ├── README.md
    ├── 01-my-first-section.md
    ├── 02-my-second-section.md
    └── etc...

An index and navigation will be automatically generated from these files, taking the information for each file from it’s front-matter.

Next chapter: “Customization”