From bfdc237e9c306b603fb1b550d49bcda980afec3a Mon Sep 17 00:00:00 2001 From: Kenton Hamaluik Date: Fri, 29 Nov 2019 14:44:33 -0700 Subject: [PATCH] updated docs, changed chapter index.md to README.md --- .../02-markdown/02-syntax-highlighting.md | 2 +- docs-src/02-markdown/README.md | 17 ++++++++++ docs-src/02-markdown/index.md | 5 --- docs-src/04-structure.md | 11 +++++-- docs-src/06-how-it-works.md | 9 ++++- docs/01-introduction/index.html | 2 +- docs/02-markdown/01-commonmark.html | 2 +- docs/02-markdown/02-syntax-highlighting.html | 4 +-- docs/02-markdown/index.html | 13 ++++++-- docs/03-frontmatter/index.html | 2 +- docs/04-structure/index.html | 12 ++++--- docs/05-customization/index.html | 2 +- docs/06-how-it-works/index.html | 11 +++++-- docs/index.html | 4 +-- docs/style.css | 2 +- src/main.rs | 4 +-- style/base.scss | 33 ++----------------- style/layout.scss | 13 +++----- style/toc.scss | 8 +---- 19 files changed, 81 insertions(+), 75 deletions(-) create mode 100644 docs-src/02-markdown/README.md delete mode 100644 docs-src/02-markdown/index.md diff --git a/docs-src/02-markdown/02-syntax-highlighting.md b/docs-src/02-markdown/02-syntax-highlighting.md index 836c0b5..9388de4 100644 --- a/docs-src/02-markdown/02-syntax-highlighting.md +++ b/docs-src/02-markdown/02-syntax-highlighting.md @@ -6,7 +6,7 @@ title = "Syntax Highlighting" GFM syntax highlighting is also available by using fenced code tags with a label denoting the language, as such: -~~~md +~~~ ```c++ #include diff --git a/docs-src/02-markdown/README.md b/docs-src/02-markdown/README.md new file mode 100644 index 0000000..8097415 --- /dev/null +++ b/docs-src/02-markdown/README.md @@ -0,0 +1,17 @@ +--- +title = "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: + +```md +_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. +``` + +_Markdown_ by itself isn't quite enough for most purposes, so _mkbook_ actually uses the _CommonMark_ spec with some additional extensions to make life easier. diff --git a/docs-src/02-markdown/index.md b/docs-src/02-markdown/index.md deleted file mode 100644 index 48e8abb..0000000 --- a/docs-src/02-markdown/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title = "Markdown" ---- - -_mkbook_ relies pretty extensively on [Markdown](https://daringfireball.net/projects/markdown/) for its ease of use. diff --git a/docs-src/04-structure.md b/docs-src/04-structure.md index cc4c7fa..f0168a1 100644 --- a/docs-src/04-structure.md +++ b/docs-src/04-structure.md @@ -59,15 +59,20 @@ 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: +_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/ ├── mkbook.toml ├── 00-foreword.md ├── 01-introduction.md -├── 02-my-first-chapter.md -└── etc... +└── 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. diff --git a/docs-src/06-how-it-works.md b/docs-src/06-how-it-works.md index 1aaf646..04fba63 100644 --- a/docs-src/06-how-it-works.md +++ b/docs-src/06-how-it-works.md @@ -22,4 +22,11 @@ Markdown is formatted usiing [comrak](https://crates.io/crates/comrak) with some ## Syntax Highlighting -Code is syntax-highlighted using [syntect](https://crates.io/crates/syntect) with the default langauges and the `base16-eighties` colour scheme. +Code is syntax-highlighted using [syntect](https://crates.io/crates/syntect) with the default langauges and the `base16-eighties` colour scheme. Some additional languages above the base list supported by _syntect_ have been aded: + +* `haxe` +* `hxml` +* `sass` +* `scss` +* `toml` + diff --git a/docs/01-introduction/index.html b/docs/01-introduction/index.html index 284c004..898c516 100644 --- a/docs/01-introduction/index.html +++ b/docs/01-introduction/index.html @@ -14,7 +14,7 @@ <p>This tool aims to work somewhat similarly to <em>mdbook</em>, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.</p> " /> - +