# 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")

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/
    ├── mkbook.toml
    ├── 00-foreword.md
    ├── 01-introduction.md
    ├── my-picture.jpg
    └── 02-my-first-chapter
        ├── index.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”