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 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
``` ```
@ -52,8 +52,8 @@ fn main() {
> **Note:** The `RenderContext` contains a `version` field. This lets backends > **Note:** The `RenderContext` contains a `version` field. This lets backends
figure out whether they are compatible with the version of `mdbook` it's being 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 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 It is recommended that backends use the [`semver`] crate to inspect this field
and emit a warning if there may be a compatibility issue. 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 Now we've got the basics running, we want to actually use it. First, install the
program. program.
``` ```shell
$ cargo install $ cargo install
``` ```
Then `cd` to the particular book you'd like to count the words of and update its Then `cd` to the particular book you'd like to count the words of and update its
`book.toml` file. `book.toml` file.
```diff ```diff
[book] [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 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. 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 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. 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 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
@ -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 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 (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]` 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 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 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 + let cfg: WordcountConfig = ctx.config
+ .get_deserialized("output.wordcount") + .get_deserialized("output.wordcount")
+ .unwrap_or_default(); + .unwrap_or_default();
for item in ctx.book.iter() { for item in ctx.book.iter() {
if let BookItem::Chapter(ref ch) = *item { if let BookItem::Chapter(ref ch) = *item {
+ if cfg.ignores.contains(&ch.name) { + if cfg.ignores.contains(&ch.name) {
+ continue; + continue;
+ } + }
+ +
let num_words = count_words(ch); let num_words = count_words(ch);
println!("{}: {}", ch.name, num_words); println!("{}: {}", ch.name, num_words);
} }
@ -239,17 +239,17 @@ in [`RenderContext`].
- use std::io; - use std::io;
use mdbook::renderer::RenderContext; use mdbook::renderer::RenderContext;
use mdbook::book::{BookItem, Chapter}; use mdbook::book::{BookItem, Chapter};
fn main() { fn main() {
... ...
+ let _ = fs::create_dir_all(&ctx.destination); + let _ = fs::create_dir_all(&ctx.destination);
+ let mut f = File::create(ctx.destination.join("wordcounts.txt")).unwrap(); + let mut f = File::create(ctx.destination.join("wordcounts.txt")).unwrap();
+ +
for item in ctx.book.iter() { for item in ctx.book.iter() {
if let BookItem::Chapter(ref ch) = *item { if let BookItem::Chapter(ref ch) = *item {
... ...
let num_words = count_words(ch); let num_words = count_words(ch);
println!("{}: {}", ch.name, num_words); println!("{}: {}", ch.name, num_words);
+ writeln!(f, "{}: {}", ch.name, num_words).unwrap(); + writeln!(f, "{}: {}", ch.name, num_words).unwrap();
@ -276,11 +276,11 @@ like this:
fn main() { fn main() {
... ...
for item in ctx.book.iter() { for item in ctx.book.iter() {
if let BookItem::Chapter(ref ch) = *item { if let BookItem::Chapter(ref ch) = *item {
... ...
let num_words = count_words(ch); let num_words = count_words(ch);
println!("{}: {}", ch.name, num_words); println!("{}: {}", ch.name, num_words);
writeln!(f, "{}: {}", ch.name, num_words).unwrap(); writeln!(f, "{}: {}", ch.name, num_words).unwrap();
@ -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
... ...

53
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"]
@ -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 If you have the same, and/or other preprocessors declared via their table
of configuration, they will run instead. 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. `index` will run.
- Setting `use-default-preprocessors = false` will disable these - Setting `use-default-preprocessors = false` will disable these
default preprocessors from running. 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. `use-default-preprocessors` that `links` it will run.
## Configuring Preprocessors ## Configuring Preprocessors
@ -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.
@ -146,10 +146,12 @@ The following configuration options are available:
- **theme:** mdBook comes with a default theme and all the resource files needed - **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 for it. But if this option is set, mdBook will selectively overwrite the theme
files with the ones found in the specified folder. 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`. '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
@ -241,13 +242,13 @@ copy-js = true
### Custom Renderers ### Custom Renderers
A custom renderer can be enabled by adding a `[output.foo]` table to your A custom renderer can be enabled by adding a `[output.foo]` table to your
`book.toml`. Similar to [preprocessors](#configuring-preprocessors) this will `book.toml`. Similar to [preprocessors](#configuring-preprocessors) this will
instruct `mdbook` to pass a representation of the book to `mdbook-foo` for instruct `mdbook` to pass a representation of the book to `mdbook-foo` for
rendering. rendering.
Custom renderers will have access to all configuration within their table 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. manually specified with the `command` field.
## Environment Variables ## 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 > 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
> ``` > ```
The latter case may be useful in situations where `mdbook` is invoked from a 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 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 ### 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]