mirror of https://github.com/hamaluik/mkbook
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
91 lines
3.4 KiB
Markdown
91 lines
3.4 KiB
Markdown
---
|
|
title = "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
|
|
|
|
```md
|
|
---
|
|
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:
|
|
|
|
```md
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
# 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](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html#impl-PartialOrd%3Cstr%3E)). 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.
|