From f8f79cf30a65e6718021ac21340f97b528f88c67 Mon Sep 17 00:00:00 2001 From: Kenton Hamaluik Date: Fri, 29 Nov 2019 15:38:48 -0700 Subject: [PATCH] changed mkbook.toml to README.md, updated book to reflect changes --- assets/README.default.md | 6 ++ assets/mkbook.default.toml | 6 -- docs-src/01-introduction.md | 32 +++++++- docs-src/02-markdown/01-commonmark.md | 4 +- docs-src/02-markdown/README.md | 2 + docs-src/03-frontmatter.md | 25 +++++- docs-src/04-structure.md | 32 ++++---- docs-src/05-customization.md | 4 +- docs-src/06-how-it-works.md | 2 + docs-src/{mkbook.toml => README.md} | 5 +- docs/01-introduction/index.html | 82 ++++++++++++-------- docs/02-markdown/01-commonmark.html | 15 ++-- docs/02-markdown/02-syntax-highlighting.html | 10 +-- docs/02-markdown/index.html | 15 ++-- docs/03-frontmatter/index.html | 39 +++++++--- docs/04-structure/index.html | 45 ++++++----- docs/05-customization/index.html | 11 ++- docs/06-how-it-works/index.html | 11 ++- docs/index.html | 6 +- src/main.rs | 68 ++++++++-------- src/models.rs | 1 - src/models/book.rs | 46 ----------- src/models/chapter.rs | 1 - src/models/frontmatter.rs | 48 +++++++++++- templates/index.html | 8 +- templates/page.html | 22 +++--- 26 files changed, 318 insertions(+), 228 deletions(-) create mode 100644 assets/README.default.md delete mode 100644 assets/mkbook.default.toml rename docs-src/{mkbook.toml => README.md} (96%) delete mode 100644 src/models/book.rs diff --git a/assets/README.default.md b/assets/README.default.md new file mode 100644 index 0000000..32eaf2d --- /dev/null +++ b/assets/README.default.md @@ -0,0 +1,6 @@ +--- +title = "My Cool Book" +author = "Anonymous" +--- + +A **short** but sweet description of _My Cool Book_. \ No newline at end of file diff --git a/assets/mkbook.default.toml b/assets/mkbook.default.toml deleted file mode 100644 index 15227c5..0000000 --- a/assets/mkbook.default.toml +++ /dev/null @@ -1,6 +0,0 @@ -title = "My Cool Book" -author = "Anonymous" -url = "" -description = """ -A **short** but sweet description of _My Cool Book_. -""" diff --git a/docs-src/01-introduction.md b/docs-src/01-introduction.md index 3e599a4..e462677 100644 --- a/docs-src/01-introduction.md +++ b/docs-src/01-introduction.md @@ -2,17 +2,21 @@ title = "Introduction" --- +# Introduction + _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. 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. +## Command-line Interface + _mkbook_ may be installed using _Cargo_ (`cargo install --force --path .` in the _mkbook_ repo directory), and after that it presents a command-line interface: -``` +```sh $ mkbook -mkbook 0.1.0 +mkbook 0.2.0 Kenton Hamaluik @@ -33,9 +37,31 @@ SUBCOMMANDS: init initialize a mkbook directory tree ``` -Currently, only the `build` subcommand does anything (it builds your book!), but this functionality is still WIP: +### The Init Command + +The init command is a tool to help you get started, and will create an initial `README.md` file and a stub of your first chapter. +```sh +$ mkbook init --help +mkbook-init +initialize a mkbook directory tree + +USAGE: + mkbook init [OPTIONS] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +OPTIONS: + -d, --directory an optional directory to initialize into [default: src] ``` + +### The Build Command + +The build command is the primary command for _mkbook_, and is responsible for taking the `.md` files and building the resulting website. + +```sh $ mkbook build --help mkbook-build build the book diff --git a/docs-src/02-markdown/01-commonmark.md b/docs-src/02-markdown/01-commonmark.md index eeb114f..527a318 100644 --- a/docs-src/02-markdown/01-commonmark.md +++ b/docs-src/02-markdown/01-commonmark.md @@ -1,7 +1,9 @@ --- -title = "Commonmark" +title = "CommonMark" --- +# CommonMark + _mkbook_ nominally utilizes [CommonMark](https://commonmark.org/) with some [GFM](https://github.github.com/gfm/) extensions through the use of the [comrak](https://crates.io/crates/comrak) crate. In using _comrak_, a specific set of options are used, which are listed here: ```rust diff --git a/docs-src/02-markdown/README.md b/docs-src/02-markdown/README.md index 8097415..792cda0 100644 --- a/docs-src/02-markdown/README.md +++ b/docs-src/02-markdown/README.md @@ -2,6 +2,8 @@ title = "Markdown" --- +# Markdown + _mkbook_ relies pretty extensively on [Markdown](https://daringfireball.net/projects/markdown/) for its ease of use. If you're not familiar with _Markdown_, it is a simple markup language that is design to be easy to read and write in plain text, and then (relatively) easy for a computer to convert into other formats such as HTML or LaTeX. The above paragraph looks like this: diff --git a/docs-src/03-frontmatter.md b/docs-src/03-frontmatter.md index 41455de..6d10733 100644 --- a/docs-src/03-frontmatter.md +++ b/docs-src/03-frontmatter.md @@ -2,16 +2,22 @@ title = "Front Matter" --- -Each `.md` file can optionally contain a header with metadata describing the document. If the header isn't present, default values will be used which may look ugly. +# Front Matter -To insert a header into a `.md` file, insert three dashes (`---`), followed by a new-line, followed by the front matter contents, followed by a newline, then another three dashes and a new-line. The metadata is in the [TOML](https://github.com/toml-lang/toml) format, so for example the front-matter (and first line) for this file looks like: +Each `.md` file can optionally contain a header with metadata describing the document. If the header isn't present, or if any keys are missing, default values will be used. + +To insert a header into a `.md` file, insert three dashes (`---`), followed by a new-line, followed by the front matter contents, followed by a newline, then another three dashes and a new-line. The metadata is in the [TOML](https://github.com/toml-lang/toml) format, so for example the front-matter (and first line) for a file could look like this: ```md --- title = "Front Matter" +author = "Kenton Hamaluik" +pubdate = 2019-11-29T15:22:00-07:00 --- -Each `.md` file can optionally contain a header with metadata describing the document. If the header isn't present, default values will be used which may look ugly. +# Front Matter + +Each `.md` file can optionally contain a header with metadata describing the document. If the header isn't present, or if any keys are missing, default values will be used. ``` ## Supported Keys @@ -20,5 +26,16 @@ The list of supported keys is subject to change, but for now it is as follows: title -: A human-readable title for the document +: A human-readable title for the document (defaults to the filename) + +author + +: The author (or authors) who wrote the chapter (defaults to "Anonymous") + +pubdate + +: The [RFC 3339](http://tools.ietf.org/html/rfc3339) timestamp of when the chapter was published (defaults to the time at build) + +url +: The relative URL of the file, defaults to the generated route (you probably shouldn't set this one) diff --git a/docs-src/04-structure.md b/docs-src/04-structure.md index f0168a1..0114d78 100644 --- a/docs-src/04-structure.md +++ b/docs-src/04-structure.md @@ -2,31 +2,39 @@ title = "Structure" --- -_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. +# Structure -## `mkbook.toml` +_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. -_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: +## `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 (`description`) +* A markdown-formatted description of the book -If the `mkbook.toml` file or any of the entries are missing, default values will be used. +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 -```toml +```md +--- 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. -""" +_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 @@ -53,9 +61,7 @@ This tool aims to work somewhat similarly to _mdbook_, but is generally intended ## Assets -```rust -unimplemented!() -``` +The current version of _mkbook_ doesn't copy any assets into your book—it only parses `.md` files and generates `.html` files. So if you want to include images or other assets, you're on your own. Support for assets is planned for the next minor release. ## Documents diff --git a/docs-src/05-customization.md b/docs-src/05-customization.md index 2418e6d..efe53ed 100644 --- a/docs-src/05-customization.md +++ b/docs-src/05-customization.md @@ -2,4 +2,6 @@ title = "Customization" --- -There isn't any way to customize the templates nor the CSS yet, though I will investigate this if the need arises. \ No newline at end of file +# Customization + +There isn't any way to customize the templates nor the CSS yet, though I will investigate this if the need arises. This is because both the templates and CSS are currently compiled at compile-time instead of run-time. diff --git a/docs-src/06-how-it-works.md b/docs-src/06-how-it-works.md index 04fba63..9b01a7f 100644 --- a/docs-src/06-how-it-works.md +++ b/docs-src/06-how-it-works.md @@ -2,6 +2,8 @@ title = "How it Works" --- +# How it Works + _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 diff --git a/docs-src/mkbook.toml b/docs-src/README.md similarity index 96% rename from docs-src/mkbook.toml rename to docs-src/README.md index c12461d..656b577 100644 --- a/docs-src/mkbook.toml +++ b/docs-src/README.md @@ -1,8 +1,9 @@ +--- 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. -""" \ No newline at end of file diff --git a/docs/01-introduction/index.html b/docs/01-introduction/index.html index 898c516..49f79e6 100644 --- a/docs/01-introduction/index.html +++ b/docs/01-introduction/index.html @@ -10,11 +10,9 @@ - + - +
-

mkbook is my simpler alternative to 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.

+

Introduction

+

mkbook is my simpler alternative to 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.

If you’re not familiar with mdbook, mkbook is a tool to convert a collection of Markdown 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.

+

Command-line Interface

mkbook may be installed using Cargo (cargo install --force --path . in the mkbook repo directory), and after that it presents a command-line interface:

-$ mkbook
-mkbook 0.1.0
-Kenton Hamaluik <kenton@hamaluik.ca>
+$ mkbook
+mkbook 0.2.0
+Kenton Hamaluik <kenton@hamaluik.ca>
+
+
+USAGE:
+    mkbook [SUBCOMMAND]
 
+FLAGS:
+    -h, --help       
+            Prints help information
 
-USAGE:
-    mkbook [SUBCOMMAND]
+    -V, --version    
+            Prints version information
 
-FLAGS:
-    -h, --help       
-            Prints help information
 
-    -V, --version    
-            Prints version information
+SUBCOMMANDS:
+    build    build the book
+    help     Prints this message or the help of the given subcommand(s)
+    init     initialize a mkbook directory tree
+
+

The Init Command

+

The init command is a tool to help you get started, and will create an initial README.md file and a stub of your first chapter.

+
+$ mkbook init --help
+mkbook-init 
+initialize a mkbook directory tree
+
+USAGE:
+    mkbook init [OPTIONS]
 
+FLAGS:
+    -h, --help       Prints help information
+    -V, --version    Prints version information
 
-SUBCOMMANDS:
-    build    build the book
-    help     Prints this message or the help of the given subcommand(s)
-    init     initialize a mkbook directory tree
+OPTIONS:
+    -d, --directory <directory>    an optional directory to initialize into [default: src]
-

Currently, only the build subcommand does anything (it builds your book!), but this functionality is still WIP:

+

The Build Command

+

The build command is the primary command for mkbook, and is responsible for taking the .md files and building the resulting website.

-$ mkbook build --help
-mkbook-build 
-build the book
+$ mkbook build --help
+mkbook-build 
+build the book
 
-USAGE:
-    mkbook build [OPTIONS]
+USAGE:
+    mkbook build [OPTIONS]
 
-FLAGS:
-    -h, --help       Prints help information
-    -V, --version    Prints version information
+FLAGS:
+    -h, --help       Prints help information
+    -V, --version    Prints version information
 
-OPTIONS:
-    -i, --in <in>      an optional directory to take the book sources from [default: src]
-    -o, --out <out>    an optional directory to render the contents into [default: book]
+OPTIONS:
+    -i, --in <in>      an optional directory to take the book sources from [default: src]
+    -o, --out <out>    an optional directory to render the contents into [default: book]
diff --git a/docs/02-markdown/01-commonmark.html b/docs/02-markdown/01-commonmark.html index 94e7ae1..dc01bdc 100644 --- a/docs/02-markdown/01-commonmark.html +++ b/docs/02-markdown/01-commonmark.html @@ -3,18 +3,16 @@ - The mkbook Book | Commonmark + The mkbook Book | CommonMark - + - +
-

mkbook nominally utilizes CommonMark with some GFM extensions through the use of the comrak crate. In using comrak, a specific set of options are used, which are listed here:

+

CommonMark

+

mkbook nominally utilizes CommonMark with some GFM extensions through the use of the comrak crate. In using comrak, a specific set of options are used, which are listed here:

 let options: ComrakOptions = ComrakOptions {
     hardbreaks: false,
diff --git a/docs/02-markdown/02-syntax-highlighting.html b/docs/02-markdown/02-syntax-highlighting.html
index e223dd8..6730084 100644
--- a/docs/02-markdown/02-syntax-highlighting.html
+++ b/docs/02-markdown/02-syntax-highlighting.html
@@ -10,11 +10,9 @@
         
         
         
-        
+        
         
-        
+