actions
/
mdBook
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Some documentation fixes. (#925)

This commit is contained in:
Eric Huss 2019-05-18 15:05:57 -07:00 committed by Dylan DPC
parent ec8e63145c
commit fc565df86b
4 changed files with 85 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
book-example/src/for_developers/backends.md
View File

@ -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
... ...

37
book-example/src/format/config.md
View File

@ -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
> ``` > ```

72
book-example/src/format/theme/index-hbs.md
View File

@ -45,51 +45,55 @@ at your disposal.
### 1. toc ### 1. toc
The toc helper is used like this The toc helper is used like this
```handlebars ```handlebars
{{#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">
<li><a href="link/to/file.html">Some chapter</a></li> <li><a href="link/to/file.html">Some chapter</a></li>
<li> <li>
<ul class="section"> <ul class="section">
<li><a href="link/to/other_file.html">Some other Chapter</a></li> <li><a href="link/to/other_file.html">Some other Chapter</a></li>
</ul> </ul>
</li> </li>
</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>
var chapters = {{chapters}}; var chapters = {{chapters}};
// Processing here // Processing here
</script> </script>
``` ```
### 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
```handlebars ```handlebars
{{#previous}} {{#previous}}
<a href="{{link}}" class="nav-chapters previous"> <a href="{{link}}" class="nav-chapters previous">
<i class="fa fa-angle-left"></i> <i class="fa fa-angle-left"></i>
</a> </a>
{{/previous}} {{/previous}}
``` ```
The inner html will only be rendered if the previous / next chapter exists. The inner html will only be rendered if the previous / next chapter exists.
Of course the inner html can be changed to your liking. Of course the inner html can be changed to your liking.
------ ------

4
src/config.rs
View File

@ -592,9 +592,9 @@ mod tests {
editable = true editable = true
editor = "ace" editor = "ace"
[preprocess.first] [preprocessor.first]
[preprocess.second] [preprocessor.second]
"#; "#;
#[test] #[test]