Some documentation fixes. (#925)
This commit is contained in:
parent
ec8e63145c
commit
fc565df86b
|
@ -24,7 +24,7 @@ no reason why it couldn't be accomplished using something like Python or Ruby.
|
||||||
First you'll want to create a new binary program and add `mdbook` as a
|
First you'll want to create a new binary program and add `mdbook` as a
|
||||||
dependency.
|
dependency.
|
||||||
|
|
||||||
```
|
```shell
|
||||||
$ cargo new --bin mdbook-wordcount
|
$ cargo new --bin mdbook-wordcount
|
||||||
$ cd mdbook-wordcount
|
$ cd mdbook-wordcount
|
||||||
$ cargo add mdbook
|
$ cargo add mdbook
|
||||||
|
@ -92,7 +92,7 @@ fn count_words(ch: &Chapter) -> usize {
|
||||||
Now we've got the basics running, we want to actually use it. First, install the
|
Now we've got the basics running, we want to actually use it. First, install the
|
||||||
program.
|
program.
|
||||||
|
|
||||||
```
|
```shell
|
||||||
$ cargo install
|
$ cargo install
|
||||||
```
|
```
|
||||||
|
|
||||||
|
@ -120,7 +120,7 @@ to make sure to add the HTML backend, even if its table just stays empty.
|
||||||
Now you just need to build your book like normal, and everything should *Just
|
Now you just need to build your book like normal, and everything should *Just
|
||||||
Work*.
|
Work*.
|
||||||
|
|
||||||
```
|
```shell
|
||||||
$ mdbook build
|
$ mdbook build
|
||||||
...
|
...
|
||||||
2018-01-16 07:31:15 [INFO] (mdbook::renderer): Invoking the "mdbook-wordcount" renderer
|
2018-01-16 07:31:15 [INFO] (mdbook::renderer): Invoking the "mdbook-wordcount" renderer
|
||||||
|
@ -303,7 +303,7 @@ like this:
|
||||||
|
|
||||||
Now, if we reinstall the backend and build a book,
|
Now, if we reinstall the backend and build a book,
|
||||||
|
|
||||||
```
|
```shell
|
||||||
$ cargo install --force
|
$ cargo install --force
|
||||||
$ mdbook build /path/to/book
|
$ mdbook build /path/to/book
|
||||||
...
|
...
|
||||||
|
|
|
@ -14,9 +14,9 @@ description = "The example book covers examples."
|
||||||
build-dir = "my-example-book"
|
build-dir = "my-example-book"
|
||||||
create-missing = false
|
create-missing = false
|
||||||
|
|
||||||
[preprocess.index]
|
[preprocessor.index]
|
||||||
|
|
||||||
[preprocess.links]
|
[preprocessor.links]
|
||||||
|
|
||||||
[output.html]
|
[output.html]
|
||||||
additional-css = ["custom.css"]
|
additional-css = ["custom.css"]
|
||||||
|
@ -92,9 +92,9 @@ The following preprocessors are available and included by default:
|
||||||
build-dir = "build"
|
build-dir = "build"
|
||||||
create-missing = false
|
create-missing = false
|
||||||
|
|
||||||
[preprocess.links]
|
[preprocessor.links]
|
||||||
|
|
||||||
[preprocess.index]
|
[preprocessor.index]
|
||||||
```
|
```
|
||||||
|
|
||||||
### Custom Preprocessor Configuration
|
### Custom Preprocessor Configuration
|
||||||
|
@ -105,8 +105,8 @@ configuration to the preprocessor by adding key-value pairs to the table.
|
||||||
|
|
||||||
For example
|
For example
|
||||||
|
|
||||||
```
|
```toml
|
||||||
[preprocess.links]
|
[preprocessor.links]
|
||||||
# set the renderers this preprocessor will run for
|
# set the renderers this preprocessor will run for
|
||||||
renderers = ["html"]
|
renderers = ["html"]
|
||||||
some_extra_feature = true
|
some_extra_feature = true
|
||||||
|
@ -117,7 +117,7 @@ some_extra_feature = true
|
||||||
You can explicitly specify that a preprocessor should run for a renderer by
|
You can explicitly specify that a preprocessor should run for a renderer by
|
||||||
binding the two together.
|
binding the two together.
|
||||||
|
|
||||||
```
|
```toml
|
||||||
[preprocessor.mathjax]
|
[preprocessor.mathjax]
|
||||||
renderers = ["html"] # mathjax only makes sense with the HTML renderer
|
renderers = ["html"] # mathjax only makes sense with the HTML renderer
|
||||||
```
|
```
|
||||||
|
@ -125,7 +125,7 @@ renderers = ["html"] # mathjax only makes sense with the HTML renderer
|
||||||
### Provide Your Own Command
|
### Provide Your Own Command
|
||||||
|
|
||||||
By default when you add a `[preprocessor.foo]` table to your `book.toml` file,
|
By default when you add a `[preprocessor.foo]` table to your `book.toml` file,
|
||||||
`mdbook` will try to invoke the `mdbook-foo` executa`ble. If you want to use a
|
`mdbook` will try to invoke the `mdbook-foo` executable. If you want to use a
|
||||||
different program name or pass in command-line arguments, this behaviour can
|
different program name or pass in command-line arguments, this behaviour can
|
||||||
be overridden by adding a `command` field.
|
be overridden by adding a `command` field.
|
||||||
|
|
||||||
|
@ -150,6 +150,8 @@ The following configuration options are available:
|
||||||
'Change Theme' dropdown. Defaults to `light`.
|
'Change Theme' dropdown. Defaults to `light`.
|
||||||
- **curly-quotes:** Convert straight quotes to curly quotes, except for those
|
- **curly-quotes:** Convert straight quotes to curly quotes, except for those
|
||||||
that occur in code blocks and code spans. Defaults to `false`.
|
that occur in code blocks and code spans. Defaults to `false`.
|
||||||
|
- **mathjax-support:** Adds support for [MathJax](mathjax.md). Defaults to
|
||||||
|
`false`.
|
||||||
- **google-analytics:** If you use Google Analytics, this option lets you enable
|
- **google-analytics:** If you use Google Analytics, this option lets you enable
|
||||||
it by simply specifying your ID in the configuration file.
|
it by simply specifying your ID in the configuration file.
|
||||||
- **additional-css:** If you need to slightly change the appearance of your book
|
- **additional-css:** If you need to slightly change the appearance of your book
|
||||||
|
@ -165,9 +167,9 @@ The following configuration options are available:
|
||||||
- **playpen:** A subtable for configuring various playpen settings.
|
- **playpen:** A subtable for configuring various playpen settings.
|
||||||
- **search:** A subtable for configuring the in-browser search functionality.
|
- **search:** A subtable for configuring the in-browser search functionality.
|
||||||
mdBook must be compiled with the `search` feature enabled (on by default).
|
mdBook must be compiled with the `search` feature enabled (on by default).
|
||||||
- **git_repository_url:** A url to the git repository for the book. If provided
|
- **git-repository-url:** A url to the git repository for the book. If provided
|
||||||
an icon link will be output in the menu bar of the book.
|
an icon link will be output in the menu bar of the book.
|
||||||
- **git_repository_icon:** The FontAwesome icon class to use for the git
|
- **git-repository-icon:** The FontAwesome icon class to use for the git
|
||||||
repository link. Defaults to `fa-github`.
|
repository link. Defaults to `fa-github`.
|
||||||
|
|
||||||
Available configuration options for the `[output.html.playpen]` table:
|
Available configuration options for the `[output.html.playpen]` table:
|
||||||
|
@ -209,25 +211,24 @@ title = "Example book"
|
||||||
authors = ["John Doe", "Jane Doe"]
|
authors = ["John Doe", "Jane Doe"]
|
||||||
description = "The example book covers examples."
|
description = "The example book covers examples."
|
||||||
|
|
||||||
[build]
|
|
||||||
build-dir = "book"
|
|
||||||
create-missing = true
|
|
||||||
preprocess = ["links", "index"]
|
|
||||||
|
|
||||||
[output.html]
|
[output.html]
|
||||||
theme = "my-theme"
|
theme = "my-theme"
|
||||||
|
default-theme = "light"
|
||||||
curly-quotes = true
|
curly-quotes = true
|
||||||
|
mathjax-support = false
|
||||||
google-analytics = "123456"
|
google-analytics = "123456"
|
||||||
additional-css = ["custom.css", "custom2.css"]
|
additional-css = ["custom.css", "custom2.css"]
|
||||||
additional-js = ["custom.js"]
|
additional-js = ["custom.js"]
|
||||||
|
no-section-label = false
|
||||||
|
git-repository-url = "https://github.com/rust-lang-nursery/mdBook"
|
||||||
|
git-repository-icon = "fa-github"
|
||||||
|
|
||||||
[output.html.playpen]
|
[output.html.playpen]
|
||||||
editor = "./path/to/editor"
|
|
||||||
editable = false
|
editable = false
|
||||||
|
copy-js = true
|
||||||
|
|
||||||
[output.html.search]
|
[output.html.search]
|
||||||
enable = true
|
enable = true
|
||||||
searcher = "./path/to/searcher"
|
|
||||||
limit-results = 30
|
limit-results = 30
|
||||||
teaser-word-count = 30
|
teaser-word-count = 30
|
||||||
use-boolean-and = true
|
use-boolean-and = true
|
||||||
|
@ -280,7 +281,7 @@ book's title without needing to touch your `book.toml`.
|
||||||
> This means, if you so desired, you could override all book metadata when
|
> This means, if you so desired, you could override all book metadata when
|
||||||
> building the book with something like
|
> building the book with something like
|
||||||
>
|
>
|
||||||
> ```text
|
> ```shell
|
||||||
> $ export MDBOOK_BOOK="{'title': 'My Awesome Book', authors: ['Michael-F-Bryan']}"
|
> $ export MDBOOK_BOOK="{'title': 'My Awesome Book', authors: ['Michael-F-Bryan']}"
|
||||||
> $ mdbook build
|
> $ mdbook build
|
||||||
> ```
|
> ```
|
||||||
|
|
|
@ -51,7 +51,8 @@ at your disposal.
|
||||||
{{#toc}}{{/toc}}
|
{{#toc}}{{/toc}}
|
||||||
```
|
```
|
||||||
|
|
||||||
and outputs something that looks like this, depending on the structure of your book
|
and outputs something that looks like this, depending on the structure of your
|
||||||
|
book
|
||||||
|
|
||||||
```html
|
```html
|
||||||
<ul class="chapter">
|
<ul class="chapter">
|
||||||
|
@ -64,8 +65,10 @@ at your disposal.
|
||||||
</ul>
|
</ul>
|
||||||
```
|
```
|
||||||
|
|
||||||
If you would like to make a toc with another structure, you have access to the chapters property containing all the data.
|
If you would like to make a toc with another structure, you have access to the
|
||||||
The only limitation at the moment is that you would have to do it with JavaScript instead of with a handlebars helper.
|
chapters property containing all the data. The only limitation at the moment
|
||||||
|
is that you would have to do it with JavaScript instead of with a handlebars
|
||||||
|
helper.
|
||||||
|
|
||||||
```html
|
```html
|
||||||
<script>
|
<script>
|
||||||
|
@ -76,7 +79,8 @@ at your disposal.
|
||||||
|
|
||||||
### 2. previous / next
|
### 2. previous / next
|
||||||
|
|
||||||
The previous and next helpers expose a `link` and `name` property to the previous and next chapters.
|
The previous and next helpers expose a `link` and `name` property to the
|
||||||
|
previous and next chapters.
|
||||||
|
|
||||||
They are used like this
|
They are used like this
|
||||||
|
|
||||||
|
|
|
@ -592,9 +592,9 @@ mod tests {
|
||||||
editable = true
|
editable = true
|
||||||
editor = "ace"
|
editor = "ace"
|
||||||
|
|
||||||
[preprocess.first]
|
[preprocessor.first]
|
||||||
|
|
||||||
[preprocess.second]
|
[preprocessor.second]
|
||||||
"#;
|
"#;
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
|
|
Loading…
Reference in New Issue