|
|
<!DOCTYPE html>
|
|
|
<html>
|
|
|
<head>
|
|
|
<meta charset="utf-8">
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
|
<title>The mkbook Book | Structure</title>
|
|
|
<link rel="stylesheet" href="style.css" type="text/css" media="all" />
|
|
|
<link rel="shortcut icon" href="favicon.ico" />
|
|
|
<meta property="og:title" content="The mkbook Book" />
|
|
|
<meta property="og:site_name" content="The mkbook Book" />
|
|
|
<meta property="og:type" content="book" />
|
|
|
<meta property="og:url" content="https://hamaluik.github.io/mkbook//04-structure.html" />
|
|
|
|
|
|
<meta property="book:author" content="Kenton Hamaluik" />
|
|
|
<meta property="book:release_date" content="2019-12-20T03:39:13.420786946+00:00" />
|
|
|
|
|
|
</head>
|
|
|
<body>
|
|
|
<nav class="big">
|
|
|
<header>
|
|
|
<h1><a href="index.html">The mkbook Book</a></h1>
|
|
|
<h2>by Kenton Hamaluik</h2>
|
|
|
</header>
|
|
|
<ol>
|
|
|
|
|
|
<li>
|
|
|
<a href="01-command-line.html">Command-line Interface</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li>
|
|
|
<a href="02-markdown/index.html">Markdown</a>
|
|
|
|
|
|
<ol>
|
|
|
|
|
|
<li><a href="02-markdown/01-commonmark.html">CommonMark</a></li>
|
|
|
|
|
|
<li><a href="02-markdown/02-syntax-highlighting.html">Syntax Highlighting</a></li>
|
|
|
|
|
|
<li><a href="02-markdown/03-plantuml-diagrams.html">PlantUML Diagrams</a></li>
|
|
|
|
|
|
<li><a href="02-markdown/04-katex-formulas.html">KaTeX (Math) Formulas</a></li>
|
|
|
|
|
|
<li><a href="02-markdown/05-images.html">Images</a></li>
|
|
|
|
|
|
<li><a href="02-markdown/06-tables.html">Tables</a></li>
|
|
|
|
|
|
<li><a href="02-markdown/07-task-lists.html">Task Lists</a></li>
|
|
|
|
|
|
<li><a href="02-markdown/08-links.html">Links</a></li>
|
|
|
|
|
|
</ol>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li>
|
|
|
<a href="03-frontmatter.html">Front Matter</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li>
|
|
|
<a href="04-structure.html" class = "current">Structure</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li>
|
|
|
<a href="05-customization.html">Customization</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li>
|
|
|
<a href="06-how-it-works.html">How it Works</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li>
|
|
|
<a href="07-latex-output.html">LaTeX Output</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ol>
|
|
|
</nav>
|
|
|
<nav class="small">
|
|
|
<span>
|
|
|
<a href="index.html" alt="Table of Contents">
|
|
|
<span class="icon">
|
|
|
<svg class="icon-list-ol">
|
|
|
<use xlink:href="icons.svg#icon-list-ol">
|
|
|
</svg>
|
|
|
</span>
|
|
|
</a>
|
|
|
|
|
|
|
|
|
<a href="03-frontmatter.html" alt="Front Matter">
|
|
|
<span class="icon">
|
|
|
|
|
|
<svg class="icon-arrow-left">
|
|
|
<use xlink:href="icons.svg#icon-arrow-left">
|
|
|
</svg>
|
|
|
|
|
|
</span>
|
|
|
</a>
|
|
|
|
|
|
</span>
|
|
|
<span class="title">Structure</span>
|
|
|
<span>
|
|
|
<span class="placeholder"></span>
|
|
|
|
|
|
|
|
|
<a href="05-customization.html" alt="Customization">
|
|
|
<span class="icon">
|
|
|
<svg class="icon-arrow-right">
|
|
|
<use xlink:href="icons.svg#icon-arrow-right">
|
|
|
</svg>
|
|
|
</span>
|
|
|
</a>
|
|
|
|
|
|
</span>
|
|
|
</nav>
|
|
|
<article>
|
|
|
<h1 class="title">Structure</h1>
|
|
|
<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>
|
|
|
<h1><a href="#readmemd" aria-hidden="true" class="anchor" id="headerreadmemd"></a>README.md</h1>
|
|
|
<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</li>
|
|
|
</ul>
|
|
|
<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>
|
|
|
<h2><a href="#sample" aria-hidden="true" class="anchor" id="headersample"></a>Sample</h2>
|
|
|
<pre style="background-color:#2d2d2d;">
|
|
|
<span style="background-color:#515151;color:#d3d0c8;">---
|
|
|
</span><span style="color:#d3d0c8;">title = "The mkbook Book"
|
|
|
</span><span style="color:#d3d0c8;">author = "Kenton Hamaluik"
|
|
|
</span><span style="color:#d3d0c8;">url = "https://hamaluik.github.io/mkbook/"
|
|
|
</span><span style="color:#6699cc;">---
|
|
|
</span><span style="color:#d3d0c8;">
|
|
|
</span><span style="font-style:italic;color:#cc99cc;">_mkbook_</span><span style="color:#d3d0c8;"> is my simpler alternative to </span><span style="color:#f99157;">[mdbook](https://crates.io/crates/mdbook)
|
|
|
</span><span style="color:#d3d0c8;">which is a great tool, but for which I really dislike some of the decisions they
|
|
|
</span><span style="color:#d3d0c8;">took, such as relying on javascript for highlighting and navigation, and
|
|
|
</span><span style="color:#d3d0c8;">including a lot of bells and whistles such as javascript-based search.
|
|
|
</span><span style="color:#d3d0c8;">
|
|
|
</span><span style="color:#d3d0c8;">This tool aims to work somewhat similarly to </span><span style="font-style:italic;color:#cc99cc;">_mdbook_</span><span style="color:#d3d0c8;">, but is generally intended
|
|
|
</span><span style="color:#d3d0c8;">to be a more minimal alternative that is customized more towards my needs and
|
|
|
</span><span style="color:#d3d0c8;">desires than anything else.
|
|
|
</span></pre>
|
|
|
<h2><a href="#default-values" aria-hidden="true" class="anchor" id="headerdefault-values"></a>Default Values</h2>
|
|
|
<dl><dt>
|
|
|
<p><code>title</code></p>
|
|
|
</dt>
|
|
|
<dd>
|
|
|
<p>“My Cool Book”</p>
|
|
|
</dd>
|
|
|
<dt>
|
|
|
<p><code>author</code></p>
|
|
|
</dt>
|
|
|
<dd>
|
|
|
<p>“Anonymous”</p>
|
|
|
</dd>
|
|
|
<dt>
|
|
|
<p><code>pubdate</code></p>
|
|
|
</dt>
|
|
|
<dd>
|
|
|
<p>The date the book was built from the command line, in UTC time</p>
|
|
|
</dd>
|
|
|
<dt>
|
|
|
<p><code>url</code></p>
|
|
|
</dt>
|
|
|
<dd>
|
|
|
<p>“”</p>
|
|
|
</dd>
|
|
|
<dt>
|
|
|
<p><code>description</code></p>
|
|
|
</dt>
|
|
|
<dd>
|
|
|
<p>“”</p>
|
|
|
</dd>
|
|
|
</dl>
|
|
|
<h1><a href="#assets" aria-hidden="true" class="anchor" id="headerassets"></a>Assets</h1>
|
|
|
<p>Any files in the <code>src</code> directory which are not included in <code>.gitignore</code> and do not end in the extension <code>.md</code> 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:</p>
|
|
|
<pre style="background-color:#2d2d2d;">
|
|
|
<span style="color:#f99157;">![chapter-six](book-chapter-six-5834.jpg </span><span style="color:#d3d0c8;">"</span><span style="color:#f2777a;">Photo by Kaboompics.com from Pexels</span><span style="color:#d3d0c8;">"</span><span style="color:#f99157;">)
|
|
|
</span></pre>
|
|
|
<figure><img src="book-chapter-six-5834.jpg" alt="chapter-six" title="Photo by Kaboompics.com from Pexels"><figcaption>Photo by Kaboompics.com from Pexels</figcaption></figure>
|
|
|
<h1><a href="#documents" aria-hidden="true" class="anchor" id="headerdocuments"></a>Documents</h1>
|
|
|
<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 <a href="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>
|
|
|
<pre style="background-color:#2d2d2d;">
|
|
|
<span style="color:#d3d0c8;">src/
|
|
|
</span><span style="color:#d3d0c8;">├── README.md
|
|
|
</span><span style="color:#d3d0c8;">├── 00-foreword.md
|
|
|
</span><span style="color:#d3d0c8;">├── 01-introduction.md
|
|
|
</span><span style="color:#d3d0c8;">├── my-picture.jpg
|
|
|
</span><span style="color:#d3d0c8;">└── 02-my-first-chapter
|
|
|
</span><span style="color:#d3d0c8;"> ├── README.md
|
|
|
</span><span style="color:#d3d0c8;"> ├── 01-my-first-section.md
|
|
|
</span><span style="color:#d3d0c8;"> ├── 02-my-second-section.md
|
|
|
</span><span style="color:#d3d0c8;"> └── etc...
|
|
|
</span></pre>
|
|
|
<p>An index and navigation will be automatically generated from these files, taking the information for each file from it’s front-matter.</p>
|
|
|
|
|
|
|
|
|
|
|
|
<div class="next-chapter">
|
|
|
<a href="05-customization.html">
|
|
|
<span>Next chapter: “Customization”</span>
|
|
|
<span class="icon">
|
|
|
<svg class="icon-arrow-right">
|
|
|
<use xlink:href="icons.svg#icon-arrow-right">
|
|
|
</svg>
|
|
|
</span>
|
|
|
</a>
|
|
|
</div>
|
|
|
|
|
|
<footer><p>© 2019 Kenton Hamaluik</p></footer>
|
|
|
</article>
|
|
|
|
|
|
</body>
|
|
|
</html> |