diff --git a/README.md b/README.md index d63ab44..f074f64 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # 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, etc. +**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 _mkbook_, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else. +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. Still very WIP, but it can convert `.md` files into fancy-looking `.html` files, demo it by building the `mkbook` book by running: `cargo run -- build -i docs-src -o docs` and then serving the `docs` directory. Alternatively, view these generated docs [here](https://hamaluik.github.io/mkbook/01-introduction.html). diff --git a/docs-src/01-introduction.md b/docs-src/01-introduction.md index d956632..024a532 100644 --- a/docs-src/01-introduction.md +++ b/docs-src/01-introduction.md @@ -2,3 +2,50 @@ title = "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. + +_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 + + +USAGE: + mkbook [SUBCOMMAND] + +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 +``` + +Currently, only the `build` subcommand does anything (it builds your book!), but this functionality is still WIP: + +``` +$ mkbook build --help +mkbook-build +build the book + +USAGE: + mkbook build [OPTIONS] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +OPTIONS: + -i, --in an optional directory to take the book sources from [default: src] + -o, --out an optional directory to render the contents into [default: book] +``` diff --git a/docs-src/02-markdown.md b/docs-src/02-markdown.md index f0ed0f3..2353eca 100644 --- a/docs-src/02-markdown.md +++ b/docs-src/02-markdown.md @@ -2,3 +2,45 @@ title = "Markdown" --- +_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 +let options: ComrakOptions = ComrakOptions { + hardbreaks: false, + smart: true, + github_pre_lang: false, + default_info_string: None, + unsafe_: true, + ext_strikethrough: true, + ext_tagfilter: false, + ext_table: true, + ext_autolink: true, + ext_tasklist: true, + ext_superscript: true, + ext_header_ids: Some("header".to_owned()), + ext_footnotes: true, + ext_description_lists: true, + ..ComrakOptions::default() +}; +``` + +Mostly, know that the following extensions are enabled: + +* [Strikethrough](https://github.github.com/gfm/#strikethrough-extension-) +* [Tables](https://github.github.com/gfm/#tables-extension-) +* [Autolinks](https://github.github.com/gfm/#autolinks-extension-) +* [Task Lists](https://github.github.com/gfm/#task-list-items-extension-) +* Superscripts (`e = mc^2^.` → `e = mc2.`) +* [Footnotes](https://kramdown.gettalong.org/syntax.html#footnotes) +* Description Lists: + ```md + First term + + : Details for the **first term** + + Second term + + : Details for the **second term** + + More details in second paragraph. + ``` diff --git a/docs-src/03-frontmatter.md b/docs-src/03-frontmatter.md index 6b13927..41455de 100644 --- a/docs-src/03-frontmatter.md +++ b/docs-src/03-frontmatter.md @@ -2,8 +2,6 @@ title = "Front Matter" --- -# 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. 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: @@ -13,8 +11,6 @@ To insert a header into a `.md` file, insert three dashes (`---`), followed by a title = "Front Matter" --- -# 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. ``` diff --git a/docs-src/04-structure.md b/docs-src/04-structure.md index 25e4fbb..da34a6d 100644 --- a/docs-src/04-structure.md +++ b/docs-src/04-structure.md @@ -2,3 +2,24 @@ title = "Structure" --- +_mkbook_ currently only supports two types of assets to use in rendering: assets (images, etc), and documents (markdown files). + +## Assets + +```rust +unimplemented!() +``` + +## Documents + +For now, _mkbook_ only works on a flat list of markdown files, with the intent of each markdown file being its own chapter. Subdirectories and files that don't end in a `.md` extension are completely ignored. 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/ +├── 00-foreword.md +├── 01-introduction.md +├── 02-my-first-chapter.md +└── etc... +``` + +An index and navigation will be automatically generated from these files, taking the information for each file from it's front-matter. diff --git a/docs/01-introduction.html b/docs/01-introduction.html index 12939a7..e170080 100644 --- a/docs/01-introduction.html +++ b/docs/01-introduction.html @@ -36,6 +36,48 @@ -
+

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.

+

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>
+
+
+USAGE:
+    mkbook [SUBCOMMAND]
+
+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
+
+

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

+
+$ mkbook build --help
+mkbook-build 
+build the book
+
+USAGE:
+    mkbook build [OPTIONS]
+
+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]
+
+
\ No newline at end of file diff --git a/docs/02-markdown.html b/docs/02-markdown.html index a3dc513..dcd7d82 100644 --- a/docs/02-markdown.html +++ b/docs/02-markdown.html @@ -42,6 +42,48 @@ -
+

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,
+    smart: true,
+    github_pre_lang: false,
+    default_info_string: None,
+    unsafe_: true,
+    ext_strikethrough: true,
+    ext_tagfilter: false,
+    ext_table: true,
+    ext_autolink: true,
+    ext_tasklist: true,
+    ext_superscript: true,
+    ext_header_ids: Some("header".to_owned()),
+    ext_footnotes: true,
+    ext_description_lists: true,
+    ..ComrakOptions::default()
+};
+
+

Mostly, know that the following extensions are enabled:

+
    +
  • Strikethrough
    • +
  • Tables
    • +
  • Autolinks
    • +
  • Task Lists
    • +
  • Superscripts (e = mc^2^. → e = mc<sup>2</sup>.)
    • +
  • Footnotes
    • +
  • Description Lists: +
    +First term
+
+: Details for the **first term**
+
+Second term
+
+: Details for the **second term**
+
+    More details in second paragraph.
+
    +
    • +
+
\ No newline at end of file diff --git a/docs/03-frontmatter.html b/docs/03-frontmatter.html index 0721a56..ac82828 100644 --- a/docs/03-frontmatter.html +++ b/docs/03-frontmatter.html @@ -42,16 +42,13 @@ -

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.

+

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.

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 format, so for example the front-matter (and first line) for this file looks like:

 ---
 title = "Front Matter"
 ---
 
-# 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.

Supported Keys

diff --git a/docs/04-structure.html b/docs/04-structure.html index fb53eac..c9be18f 100644 --- a/docs/04-structure.html +++ b/docs/04-structure.html @@ -36,6 +36,21 @@ -
+

mkbook currently only supports two types of assets to use in rendering: assets (images, etc), and documents (markdown files).

+

Assets

+
+unimplemented!()
+
+

Documents

+

For now, mkbook only works on a flat list of markdown files, with the intent of each markdown file being its own chapter. Subdirectories and files that don’t end in a .md extension are completely ignored. 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/
+├── 00-foreword.md
+├── 01-introduction.md
+├── 02-my-first-chapter.md
+└── etc...
+
+

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

+
\ No newline at end of file diff --git a/docs/style.css b/docs/style.css index 32bb058..ea96046 100644 --- a/docs/style.css +++ b/docs/style.css @@ -1 +1 @@ -@import url("https://fonts.googleapis.com/css?family=Crimson+Pro|Poppins:700|Source+Code+Pro&display=swap");body{margin:0;line-height:1.5;font-size:14pt;color:#222222;background:#eeeeee;padding:0;font-family:"Crimson Pro","Georgia",Georgia,"Times New Roman",Times,serif}h1,h2,h3{margin-top:0;line-height:1.2;font-family:"Poppins","Franklin Gothic Medium","Arial Narrow",Arial,sans-serif}a{color:#222222;text-decoration:underline}a:hover{color:#8a2888;text-decoration:none}figure{display:block;text-align:center;overflow-x:auto}figure img,figure video{max-width:100%}figure figcaption{display:block;font-size:0.75em;text-align:center}code{margin:0 2px;padding:0 2px;border:1px solid #4c566a;border-radius:3px;word-break:break-all;font-family:"Source Code Pro","Courier New",Courier,monospace;font-size:0.75em}pre{overflow-x:auto;font-family:"Source Code Pro","Courier New",Courier,monospace;padding:0}dl{display:grid;grid-template-columns:auto 1fr}dl dt{font-weight:700;margin:0;padding:0.5em;border-right:1px solid #dddddd}dl dd{margin:0;padding:0.5em}dl dt p,dl dd p{margin:0}html,body{width:100%;min-height:100vh}body{display:grid;grid-template-columns:auto 1fr;grid-template-rows:1fr;justify-items:stretch;align-items:stretch}body nav.big{background:#2c2c38;padding:1em;display:flex;flex-direction:column}body nav.big a{width:100%;font-size:1.5em;text-decoration:none;font-family:"Poppins","Franklin Gothic Medium","Arial Narrow",Arial,sans-serif;margin:0 0 0.25em 0;color:#5babd1}body nav.big a:hover{color:#cf5ccd}body nav.big a.current{color:#cf5ccd}body nav.big a.current:hover{color:#fefefe}body nav.small{display:none;width:100%;align-items:center;justify-content:space-between;background:#2c2c38;padding:0}body nav.small>*{margin:0.5em}body nav.small a{text-decoration:none;font-family:"Poppins","Franklin Gothic Medium","Arial Narrow",Arial,sans-serif;color:#5babd1}body nav.small a:hover{color:#cf5ccd}body nav.small span.title{text-decoration:none;font-family:"Poppins","Franklin Gothic Medium","Arial Narrow",Arial,sans-serif;color:#fefefe}body nav.small span.placeholder{width:1em;height:1em}body article{padding:1em 2em 0 2em;max-width:38em;min-width:0;min-height:0}body article>*{max-width:100%}@media screen and (max-width: 768px){body{grid-template-columns:1fr;grid-template-rows:auto 1fr}body nav.big{display:none}body nav.small{display:flex}body article{padding:1em 0.5em 0 0.5em}}span.icon{display:flex;align-items:center}[class^="icon-"],[class*=" icon-"]{display:inline-block;width:1em;height:1em;stroke-width:0;stroke:currentColor;fill:currentColor}.icon-arrow-left{width:0.875em}.icon-arrow-right{width:0.875em}@media (prefers-color-scheme: dark){body{background-color:#222222;color:#eeeeee}a{color:#eeeeee}a:hover{color:#5babd1}nav{background:#18181d}img{filter:grayscale(30%)}}@media print{body{background:#ffffff;color:#000000}a{color:#000000;text-decoration:underline}h2,h3{break-after:avoid-page}figure{break-inside:avoid}p{orphans:2;widows:2}*{overflow:hidden}nav{display:none}body{display:block}} +@import url("https://fonts.googleapis.com/css?family=Crimson+Pro|Poppins:700|Source+Code+Pro&display=swap");body{margin:0;line-height:1.5;font-size:14pt;color:#222222;background:#eeeeee;padding:0;font-family:"Crimson Pro","Georgia",Georgia,"Times New Roman",Times,serif}h1,h2,h3{margin-top:0;line-height:1.2;font-family:"Poppins","Franklin Gothic Medium","Arial Narrow",Arial,sans-serif}a{color:#222222;text-decoration:underline}a:hover{color:#8a2888;text-decoration:none}figure{display:block;text-align:center;overflow-x:auto}figure img,figure video{max-width:100%}figure figcaption{display:block;font-size:0.75em;text-align:center}code{margin:0 2px;padding:0 2px;border:1px solid #4c566a;border-radius:3px;word-break:break-all;font-family:"Source Code Pro","Courier New",Courier,monospace;font-size:0.75em}pre{overflow-x:auto;font-family:"Source Code Pro","Courier New",Courier,monospace;padding:0.5em}dl{display:grid;grid-template-columns:auto 1fr}dl dt{font-weight:700;margin:0;padding:0.5em;border-right:1px solid #dddddd}dl dd{margin:0;padding:0.5em}dl dt p,dl dd p{margin:0}html,body{width:100%;min-height:100vh}body{display:grid;grid-template-columns:auto 1fr;grid-template-rows:1fr;justify-items:stretch;align-items:stretch}body nav.big{background:#2c2c38;padding:1em;display:flex;flex-direction:column}body nav.big a{width:100%;font-size:1.5em;text-decoration:none;font-family:"Poppins","Franklin Gothic Medium","Arial Narrow",Arial,sans-serif;margin:0 0 0.25em 0;color:#5babd1}body nav.big a:hover{color:#cf5ccd}body nav.big a.current{color:#cf5ccd}body nav.big a.current:hover{color:#fefefe}body nav.small{display:none;width:100%;align-items:center;justify-content:space-between;background:#2c2c38;padding:0}body nav.small>*{margin:0.5em}body nav.small a{text-decoration:none;font-family:"Poppins","Franklin Gothic Medium","Arial Narrow",Arial,sans-serif;color:#5babd1}body nav.small a:hover{color:#cf5ccd}body nav.small span.title{text-decoration:none;font-family:"Poppins","Franklin Gothic Medium","Arial Narrow",Arial,sans-serif;color:#fefefe}body nav.small span.placeholder{width:1em;height:1em}body article{padding:1em 2em 0 2em;max-width:38em;min-width:0;min-height:0}body article>*{max-width:100%}@media screen and (max-width: 768px){body{grid-template-columns:1fr;grid-template-rows:auto 1fr}body nav.big{display:none}body nav.small{display:flex}body article{padding:1em 0.5em 0 0.5em}}span.icon{display:flex;align-items:center}[class^="icon-"],[class*=" icon-"]{display:inline-block;width:1em;height:1em;stroke-width:0;stroke:currentColor;fill:currentColor}.icon-arrow-left{width:0.875em}.icon-arrow-right{width:0.875em}@media (prefers-color-scheme: dark){body{background-color:#222222;color:#eeeeee}a{color:#eeeeee}a:hover{color:#5babd1}nav{background:#18181d}img{filter:grayscale(30%)}dl dt{border-right:1px solid #333333}}@media print{body{background:#ffffff;color:#000000}a{color:#000000;text-decoration:underline}h2,h3{break-after:avoid-page}figure{break-inside:avoid}p{orphans:2;widows:2}*{overflow:hidden}nav{display:none}body{display:block}} diff --git a/src/main.rs b/src/main.rs index 789c8e0..0ec60b9 100644 --- a/src/main.rs +++ b/src/main.rs @@ -73,7 +73,7 @@ fn format_markdown(src: &str) -> Result> { let options: ComrakOptions = ComrakOptions { hardbreaks: false, smart: true, - github_pre_lang: true, + github_pre_lang: false, default_info_string: None, unsafe_: true, ext_strikethrough: true, diff --git a/style/base.scss b/style/base.scss index 213f98c..b7cfc69 100644 --- a/style/base.scss +++ b/style/base.scss @@ -56,7 +56,7 @@ code { pre { overflow-x: auto; font-family: $font-mono; - padding: 0; + padding: 0.5em; } dl { diff --git a/style/darktheme.scss b/style/darktheme.scss index b38461f..c843f4b 100644 --- a/style/darktheme.scss +++ b/style/darktheme.scss @@ -19,4 +19,10 @@ img { filter: grayscale(30%); } + + dl { + dt { + border-right: 1px solid #333333; + } + } }