diff --git a/docs-src/01-introduction.md b/docs-src/01-introduction.md index 024a532..3e599a4 100644 --- a/docs-src/01-introduction.md +++ b/docs-src/01-introduction.md @@ -6,6 +6,8 @@ _mkbook_ is my simpler alternative to [_mdbook_](https://crates.io/crates/mdbook 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. + _mkbook_ may be installed using _Cargo_ (`cargo install --force --path .` in the _mkbook_ repo directory), and after that it presents a command-line interface: ``` diff --git a/docs-src/02-markdown.md b/docs-src/02-markdown.md index 2353eca..104dc6c 100644 --- a/docs-src/02-markdown.md +++ b/docs-src/02-markdown.md @@ -44,3 +44,111 @@ Mostly, know that the following extensions are enabled: More details in second paragraph. ``` + +## Syntax Highlight + +GFM syntax highlighting is also available by using fenced code tags with a label denoting the language, as such: + +~~~md +```c++ +#include + +int main() { + std::cout << "Hello, world!" << std::endl; + return 0; +} +``` +~~~ + +which results in: + +```c++ +#include + +int main() { + std::cout << "Hello, world!" << std::endl; + return 0; +} +``` + +To denote the language you can either use one the language's extensions as the label, or the full name of the language (which is **not** case-sensitive). + +The list of supported languages is currently as follows: + +| Language Name | Supported Tags / Extensions | +|:-|:-| +| ASP | `asa` | +| ActionScript | `as` | +| AppleScript | `applescript`, `script editor` | +| Batch File | `bat`, `cmd` | +| BibTeX | `bib` | +| Bourne Again Shell (bash) | `sh`, `bash`, `zsh`, `fish`, `.bash_aliases`, `.bash_completions`, `.bash_functions`, `.bash_login`, `.bash_logout`, `.bash_profile`, `.bash_variables`, `.bashrc`, `.profile`, `.textmate_init` | +| C | `c`, `h` | +| C# | `cs`, `csx` | +| C++ | `cpp`, `cc`, `cp`, `cxx`, `c++`, `C`, `h`, `hh`, `hpp`, `hxx`, `h++`, `inl`, `ipp` | +| CSS | `css`, `css.erb`, `css.liquid` | +| Cargo Build Results | | +| Clojure | `clj` | +| D | `d`, `di` | +| Diff | `diff`, `patch` | +| Erlang | `erl`, `hrl`, `Emakefile`, `emakefile` | +| Go | `go` | +| Graphviz (DOT) | `dot`, `DOT`, `gv` | +| Groovy | `groovy`, `gvy`, `gradle` | +| HTML (ASP) | `asp` | +| HTML (Erlang) | `yaws` | +| HTML (Rails) | `rails`, `rhtml`, `erb`, `html.erb` | +| HTML (Tcl) | `adp` | +| HTML | `html`, `htm`, `shtml`, `xhtml`, `inc`, `tmpl`, `tpl` | +| Haskell | `hs` | +| JSON | `json`, `sublime-settings`, `sublime-menu`, `sublime-keymap`, `sublime-mousemap`, `sublime-theme`, `sublime-build`, `sublime-project`, `sublime-completions`, `sublime-commands`, `sublime-macro`, `sublime-color-scheme` | +| Java Properties | `properties` | +| Java Server Page (JSP) | `jsp` | +| Java | `java`, `bsh` | +| JavaDoc | | +| JavaScript (Rails) | `js.erb` | +| JavaScript | `js`, `htc` | +| LaTeX Log | | +| LaTeX | `tex`, `ltx` | +| Lisp | `lisp`, `cl`, `clisp`, `l`, `mud`, `el`, `scm`, `ss`, `lsp`, `fasl` | +| Literate Haskell | `lhs` | +| Lua | `lua` | +| MATLAB | `matlab` | +| Make Output | | +| Makefile | `make`, `GNUmakefile`, `makefile`, `Makefile`, `OCamlMakefile`, `mak`, `mk` | +| Markdown | `md`, `mdown`, `markdown`, `markdn` | +| MultiMarkdown | | +| NAnt Build File | `build` | +| OCaml | `ml`, `mli` | +| OCamllex | `mll` | +| OCamlyacc | `mly` | +| Objective-C | `m`, `h` | +| Objective-C++ | `mm`, `M`, `h` | +| PHP Source | | +| PHP | `php`, `php3`, `php4`, `php5`, `php7`, `phps`, `phpt`, `phtml` | +| Pascal | `pas`, `p`, `dpr` | +| Perl | `pl`, `pm`, `pod`, `t`, `PL` | +| Plain Text | `txt` | +| Python | `py`, `py3`, `pyw`, `pyi`, `pyx`, `pyx.in`, `pxd`, `pxd.in`, `pxi`, `pxi.in`, `rpy`, `cpy`, `SConstruct`, `Sconstruct`, `sconstruct`, `SConscript`, `gyp`, `gypi`, `Snakefile`, `wscript` | +| R Console | | +| R | `R`, `r`, `s`, `S`, `Rprofile` | +| Rd (R Documentation) | `rd` | +| Regular Expression | `re` | +| Regular Expressions (Javascript) | | +| Regular Expressions (Python) | | +| Ruby Haml | `haml`, `sass` | +| Ruby on Rails | `rxml`, `builder` | +| Ruby | `rb`, `Appfile`, `Appraisals`, `Berksfile`, `Brewfile`, `capfile`, `cgi`, `Cheffile`, `config.ru`, `Deliverfile`, `Fastfile`, `fcgi`, `Gemfile`, `gemspec`, `Guardfile`, `irbrc`, `jbuilder`, `podspec`, `prawn`, `rabl`, `rake`, `Rakefile`, `Rantfile`, `rbx`, `rjs`, `ruby.rail`, `Scanfile`, `simplecov`, `Snapfile`, `thor`, `Thorfile`, `Vagrantfile` | +| Rust | `rs` | +| SQL (Rails) | `erbsql`, `sql.erb` | +| SQL | `sql`, `ddl`, `dml` | +| Scala | `scala`, `sbt` | +| Shell-Unix-Generic | | +| Tcl | `tcl` | +| TeX | `sty`, `cls` | +| Textile | `textile` | +| XML | `xml`, `xsd`, `xslt`, `tld`, `dtml`, `rss`, `opml`, `svg` | +| YAML | `yaml`, `yml`, `sublime-syntax` | +| camlp4 | | +| commands-builtin-shell-bash | | +| reStructuredText | `rst`, `rest` | diff --git a/docs-src/04-structure.md b/docs-src/04-structure.md index da34a6d..cc4c7fa 100644 --- a/docs-src/04-structure.md +++ b/docs-src/04-structure.md @@ -2,7 +2,54 @@ title = "Structure" --- -_mkbook_ currently only supports two types of assets to use in rendering: assets (images, etc), and documents (markdown files). +_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. + +## `mkbook.toml` + +_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: + +* 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`) + +If the `mkbook.toml` file or any of the entries are missing, default values will be used. + +### Sample + +```toml +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. +""" +``` + +### Default Values + +`title` + +: "My Cool Book" + +`author` + +: "Anonymous" + +`pubdate` + +: The date the book was built from the command line, in UTC time + +`url` + +: "" + +`description` + +: "" ## Assets @@ -16,6 +63,7 @@ For now, _mkbook_ only works on a flat list of markdown files, with the intent o ``` src/ +├── mkbook.toml ├── 00-foreword.md ├── 01-introduction.md ├── 02-my-first-chapter.md diff --git a/docs-src/05-customization.md b/docs-src/05-customization.md new file mode 100644 index 0000000..2418e6d --- /dev/null +++ b/docs-src/05-customization.md @@ -0,0 +1,5 @@ +--- +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 diff --git a/docs-src/06-how-it-works.md b/docs-src/06-how-it-works.md new file mode 100644 index 0000000..1aaf646 --- /dev/null +++ b/docs-src/06-how-it-works.md @@ -0,0 +1,25 @@ +--- +title = "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 + +_mkbook_ currently bundles two assets which get written into the book directory: `favicon.ico`, and `icons.svg`. `favicon.ico` is the [Font Awesome 5 book icon](https://fontawesome.com/icons/book?style=solid), and `icons.svg` contains 3 [Font Awesome 5](https://fontawesome.com/) arrow icons: [arrow-left](https://fontawesome.com/icons/arrow-left?style=solid), [arrow-right](https://fontawesome.com/icons/arrow-right?style=solid), and [arrow-up](https://fontawesome.com/icons/arrow-up?style=solid) which are used for navigation. These files are compiled into the _mkbook_ binary using the [`include_bytes!` macro](https://doc.rust-lang.org/std/macro.include_bytes.html), and written to the output folder on each build. + +## Styling + +_mkbook_ utilizes [Sass](https://sass-lang.com/) to define it's styles; you can view the sources [on github](https://github.com/hamaluik/mkbook/tree/master/style). In _mkbook_'s build script, the styles are compiled from their native `.scss` format into a single, compressed `.css` file using [sass-rs](https://crates.io/crates/sass-rs). The resulting `.css` file is then bundled into the binary using the [`include_str!` macro](https://doc.rust-lang.org/std/macro.include_str.html). When a book is generated, this `.css` is written to the output folder as `style.css`, where it is included by each generated `.html` file. + +## Templates + +_mkbook_ contains two template files: one for the index, and one for each page / chapter, and uses [Askama](https://crates.io/crates/askama) to render the templates. Since the _Askama_ templates are compiled when _mkbook_ is compiled, it is not currently possible to change the templates at run time. You can view the sources for these templates [on github](https://github.com/hamaluik/mkbook/tree/master/templates). + +## Markdown Formatting + +Markdown is formatted usiing [comrak](https://crates.io/crates/comrak) with some specific options, see the [Markdown chapter](02-markdown.html) for more information. + +## Syntax Highlighting + +Code is syntax-highlighted using [syntect](https://crates.io/crates/syntect) with the default langauges and the `base16-eighties` colour scheme. diff --git a/docs/01-introduction.html b/docs/01-introduction.html index f1bbaae..37f5936 100644 --- a/docs/01-introduction.html +++ b/docs/01-introduction.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> " /> - +