From 1b01c775e78f183a288cfdd86c2e4f02ca8c4ab3 Mon Sep 17 00:00:00 2001 From: Mathieu David Date: Thu, 10 Aug 2017 17:30:03 +0200 Subject: [PATCH 1/3] Improve wording of documentation --- book-example/src/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book-example/src/README.md b/book-example/src/README.md index 14957951fb..86b3dda7ff 100644 --- a/book-example/src/README.md +++ b/book-example/src/README.md @@ -2,7 +2,7 @@ **mdBook** is a command line tool and Rust crate to create books using Markdown files. It's very similar to Gitbook but written in [Rust](http://www.rust-lang.org). -What you are reading serves as an example of the output of mdBook and at the same time as high-level docs. +What you are reading serves as an example of the output of mdBook and at the same time as a high-level documentation. mdBook is free and open source, you can find the source code on [Github](https://github.com/azerupi/mdBook). Issues and feature requests can be posted on the [Github Issue tracker](https://github.com/azerupi/mdBook/issues). From 6eb7455d1d93376306104b490b444f907ecbc574 Mon Sep 17 00:00:00 2001 From: Mathieu David Date: Thu, 10 Aug 2017 17:39:28 +0200 Subject: [PATCH 2/3] Add documentation about additional-js --- book-example/src/format/config.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/book-example/src/format/config.md b/book-example/src/format/config.md index 39aabb67d8..463c430d25 100644 --- a/book-example/src/format/config.md +++ b/book-example/src/format/config.md @@ -2,7 +2,8 @@ You can configure the parameters for your book in the ***book.toml*** file. -**Note:** JSON configuration files were previously supported but have been deprecated in favor of +>**Note:** +JSON configuration files were previously supported but have been deprecated in favor of the TOML configuration file. If you are still using JSON we strongly encourage you to migrate to the TOML configuration because JSON support will be removed in the future. @@ -63,12 +64,13 @@ source = "my-src" # the source files will be found in `root/my-src` instead of The HTML renderer has a couple of options aswell. All the options for the renderer need to be specified under the TOML table `[output.html]`. The following configuration options are available: -- **destination:** By default, the HTML book will be rendered in the `root/book` directory, but this option lets you specify another +- **`destination`:** By default, the HTML book will be rendered in the `root/book` directory, but this option lets you specify another destination fodler. -- **theme:** mdBook comes with a default theme and all the resource files needed for it. But if this option is set, mdBook will selectively overwrite the theme files with the ones found in the specified folder. -- **curly-quotes:** Convert straight quotes to curly quotes, except for those that occur in code blocks and code spans. Defaults to `false`. -- **google-analytics:** If you use Google Analytics, this option lets you enable it by simply specifying your ID in the configuration file. -- **additional-css:** If you need to slightly change the appearance of your book without overwriting the whole style, you can specify a set of stylesheets that will be loaded after the default ones where you can surgically change the style. +- **`theme`:** mdBook comes with a default theme and all the resource files needed for it. But if this option is set, mdBook will selectively overwrite the theme files with the ones found in the specified folder. +- **`curly-quotes`:** Convert straight quotes to curly quotes, except for those that occur in code blocks and code spans. Defaults to `false`. +- **`google-analytics`:** If you use Google Analytics, this option lets you enable it by simply specifying your ID in the configuration file. +- **`additional-css`:** If you need to slightly change the appearance of your book without overwriting the whole style, you can specify a set of stylesheets that will be loaded after the default ones where you can surgically change the style. +- **`additional-js`:** If you need to add some behaviour to your book without removing the current behaviour, you can specify a set of javascript files that will be loaded alongside the default one. **book.toml** ```toml @@ -82,5 +84,6 @@ theme = "my-theme" curly-quotes = true google-analytics = "123456" additional-css = ["custom.css", "custom2.css"] +additional-js = ["custom.js"] ``` From f756aa5623e87eb4dccac6a7d19b6ec298baf7e7 Mon Sep 17 00:00:00 2001 From: Mathieu David Date: Thu, 10 Aug 2017 18:11:26 +0200 Subject: [PATCH 3/3] Update documentation for mathjax --- book-example/book.toml | 3 +++ book-example/src/format/mathjax.md | 22 ++++++++++++++++------ 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/book-example/book.toml b/book-example/book.toml index cac456db2c..4dbc659cc2 100644 --- a/book-example/book.toml +++ b/book-example/book.toml @@ -1,3 +1,6 @@ title = "mdBook Documentation" description = "Create book from markdown files. Like Gitbook but implemented in Rust" author = "Mathieu David" + +[output.html] +mathjax-support = true \ No newline at end of file diff --git a/book-example/src/format/mathjax.md b/book-example/src/format/mathjax.md index cc6a0b73dd..5011ca3fe2 100644 --- a/book-example/src/format/mathjax.md +++ b/book-example/src/format/mathjax.md @@ -1,20 +1,30 @@ # MathJax Support -mdBook supports math equations through [MathJax](https://www.mathjax.org/). +mdBook has optional support for math equations through [MathJax](https://www.mathjax.org/). -**However the normal method for indication math equations with `$$` does not work (yet?).** +To enable MathJax, you need to add the `mathjax-support` key to your `book.toml` under the `output.html` section. -To indicate an inline equation \\( \int x = \frac{x^2}{2} \\) use +```toml +[output.html] +mathjax-support = true ``` -\\( \int x = \frac{x^2}{2} \\) + +>**Note:** +The usual delimiters MathJax uses are not yet supported. You can't currently use `$$ ... $$` as delimiters and the `\[ ... \]` delimiters need an extra backslash to work. Hopefully this limitation will be lifted soon. + +### Inline equations +Inline equations are delimited by `\\[` and `\\]`. So for example, to render the following inline equation \\( \int x dx = \frac{x^2}{2} + C \\) you would write the following: +``` +\\( \int x dx = \frac{x^2}{2} + C \\) ``` -To indicate a block equation +### Block equations +Block equations are delimited by `\\[` and `\\]`. To render the following equation \\[ \mu = \frac{1}{N} \sum_{i=0} x_i \\] -use +you would write: ```bash \\[ \mu = \frac{1}{N} \sum_{i=0} x_i \\]