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> " /> - +