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

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

@ -24,9 +24,9 @@ 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
dependency.
```
```shell
$ cargo new --bin mdbook-wordcount
$ cd mdbook-wordcount
$ cd mdbook-wordcount
$ cargo add mdbook
```
@ -52,8 +52,8 @@ fn main() {
> **Note:** The `RenderContext` contains a `version` field. This lets backends
figure out whether they are compatible with the version of `mdbook` it's being
called by. This `version` comes directly from the corresponding field in
`mdbook`'s `Cargo.toml`.
`mdbook`'s `Cargo.toml`.
It is recommended that backends use the [`semver`] crate to inspect this field
and emit a warning if there may be a compatibility issue.
@ -92,12 +92,12 @@ fn count_words(ch: &Chapter) -> usize {
Now we've got the basics running, we want to actually use it. First, install the
program.
```
```shell
$ cargo install
```
Then `cd` to the particular book you'd like to count the words of and update its
`book.toml` file.
`book.toml` file.
```diff
[book]
@ -112,7 +112,7 @@ Then `cd` to the particular book you'd like to count the words of and update its
When it loads a book into memory, `mdbook` will inspect your `book.toml` file to
try and figure out which backends to use by looking for all `output.*` tables.
If none are provided it'll fall back to using the default HTML renderer.
If none are provided it'll fall back to using the default HTML renderer.
Notably, this means if you want to add your own custom backend you'll also need
to make sure to add the HTML backend, even if its table just stays empty.
@ -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
Work*.
```
```shell
$ mdbook build
...
2018-01-16 07:31:15 [INFO] (mdbook::renderer): Invoking the "mdbook-wordcount" renderer
@ -169,7 +169,7 @@ arguments or be an interpreted script), you can use the `command` field.
Now imagine you don't want to count the number of words on a particular chapter
(it might be generated text/code, etc). The canonical way to do this is via the
usual `book.toml` configuration file by adding items to your `[output.foo]`
table.
table.
The `Config` can be treated roughly as a nested hashmap which lets you call
methods like `get()` to access the config's contents, with a
@ -211,13 +211,13 @@ and then add a check to make sure we skip ignored chapters.
+ let cfg: WordcountConfig = ctx.config
+ .get_deserialized("output.wordcount")
+ .unwrap_or_default();
for item in ctx.book.iter() {
if let BookItem::Chapter(ref ch) = *item {
+ if cfg.ignores.contains(&ch.name) {
+ continue;
+ }
+
+
let num_words = count_words(ch);
println!("{}: {}", ch.name, num_words);
}
@ -239,17 +239,17 @@ in [`RenderContext`].
- use std::io;
use mdbook::renderer::RenderContext;
use mdbook::book::{BookItem, Chapter};
fn main() {
...
+ let _ = fs::create_dir_all(&ctx.destination);
+ let mut f = File::create(ctx.destination.join("wordcounts.txt")).unwrap();
+
+
for item in ctx.book.iter() {
if let BookItem::Chapter(ref ch) = *item {
...
let num_words = count_words(ch);
println!("{}: {}", ch.name, num_words);
+ writeln!(f, "{}: {}", ch.name, num_words).unwrap();
@ -276,11 +276,11 @@ like this:
fn main() {
...
for item in ctx.book.iter() {
if let BookItem::Chapter(ref ch) = *item {
...
let num_words = count_words(ch);
println!("{}: {}", ch.name, num_words);
writeln!(f, "{}: {}", ch.name, num_words).unwrap();
@ -303,7 +303,7 @@ like this:
Now, if we reinstall the backend and build a book,
```
```shell
$ cargo install --force
$ mdbook build /path/to/book
...

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

@ -14,9 +14,9 @@ description = "The example book covers examples."
build-dir = "my-example-book"
create-missing = false
[preprocess.index]
[preprocessor.index]
[preprocess.links]
[preprocessor.links]
[output.html]
additional-css = ["custom.css"]
@ -68,11 +68,11 @@ This controls the build process of your book.
If you have the same, and/or other preprocessors declared via their table
of configuration, they will run instead.
- For clarity, with no preprocessor configuration, the default `links` and
- For clarity, with no preprocessor configuration, the default `links` and
`index` will run.
- Setting `use-default-preprocessors = false` will disable these
default preprocessors from running.
- Adding `[preprocessor.links]`, for example, will ensure, regardless of
- Adding `[preprocessor.links]`, for example, will ensure, regardless of
`use-default-preprocessors` that `links` it will run.
## Configuring Preprocessors
@ -92,9 +92,9 @@ The following preprocessors are available and included by default:
build-dir = "build"
create-missing = false
[preprocess.links]
[preprocessor.links]
[preprocess.index]
[preprocessor.index]
```
### Custom Preprocessor Configuration
@ -105,8 +105,8 @@ configuration to the preprocessor by adding key-value pairs to the table.
For example
```
[preprocess.links]
```toml
[preprocessor.links]
# set the renderers this preprocessor will run for
renderers = ["html"]
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
binding the two together.
```
```toml
[preprocessor.mathjax]
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
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
be overridden by adding a `command` field.
@ -146,10 +146,12 @@ The following configuration options are available:
- **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.
- **default-theme:** The theme color scheme to select by default in the
- **default-theme:** The theme color scheme to select by default in the
'Change Theme' dropdown. Defaults to `light`.
- **curly-quotes:** Convert straight quotes to curly quotes, except for those
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
it by simply specifying your ID in the configuration file.
- **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.
- **search:** A subtable for configuring the in-browser search functionality.
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.
- **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`.
Available configuration options for the `[output.html.playpen]` table:
@ -209,25 +211,24 @@ title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."
[build]
build-dir = "book"
create-missing = true
preprocess = ["links", "index"]
[output.html]
theme = "my-theme"
default-theme = "light"
curly-quotes = true
mathjax-support = false
google-analytics = "123456"
additional-css = ["custom.css", "custom2.css"]
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]
editor = "./path/to/editor"
editable = false
copy-js = true
[output.html.search]
enable = true
searcher = "./path/to/searcher"
limit-results = 30
teaser-word-count = 30
use-boolean-and = true
@ -241,13 +242,13 @@ copy-js = true
### Custom Renderers
A custom renderer can be enabled by adding a `[output.foo]` table to your
`book.toml`. Similar to [preprocessors](#configuring-preprocessors) this will
instruct `mdbook` to pass a representation of the book to `mdbook-foo` for
A custom renderer can be enabled by adding a `[output.foo]` table to your
`book.toml`. Similar to [preprocessors](#configuring-preprocessors) this will
instruct `mdbook` to pass a representation of the book to `mdbook-foo` for
rendering.
Custom renderers will have access to all configuration within their table
(i.e. anything under `[output.foo]`), and the command to be invoked can be
(i.e. anything under `[output.foo]`), and the command to be invoked can be
manually specified with the `command` field.
## Environment Variables
@ -280,11 +281,11 @@ book's title without needing to touch your `book.toml`.
> This means, if you so desired, you could override all book metadata when
> building the book with something like
>
> ```text
> ```shell
> $ export MDBOOK_BOOK="{'title': 'My Awesome Book', authors: ['Michael-F-Bryan']}"
> $ mdbook build
> ```
The latter case may be useful in situations where `mdbook` is invoked from a
script or CI, where it sometimes isn't possible to update the `book.toml` before
building.
building.

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

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