update documentation in book-example
This commit is contained in:
Gambhiro
parent
0bebd9e07f
commit
0a5efcc704
|
|
@ -32,6 +32,7 @@ class book::Chapter {
|
|||
dest_path: Option<PathBuf>,
|
||||
|
||||
pub translation_links: Option<Vec<TranslationLink>>,
|
||||
pub translation_id: Option<String>,
|
||||
pub authors: Option<Vec<Author>>,
|
||||
pub translators: Option<Vec<Author>>,
|
||||
pub description: Option<String>,
|
||||
|
|
@ -72,10 +73,10 @@ class Author {
|
|||
}
|
||||
|
||||
class Language {
|
||||
name: String,
|
||||
code: String,
|
||||
pub code: String,
|
||||
pub name: Option<String>,
|
||||
|
||||
new(name, code)
|
||||
new(code)
|
||||
}
|
||||
|
||||
class Publisher {
|
||||
|
|
@ -112,7 +113,7 @@ enum TocItem {
|
|||
}
|
||||
|
||||
class Renderer {
|
||||
build(&self, project_root: &PathBuf),
|
||||
build(&self, project_root: &PathBuf, dest_base: &Option<PathBuf>),
|
||||
render(&self, book_project: &MDBook),
|
||||
}
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 87 KiB After Width: | Height: | Size: 93 KiB |
|
|
@ -7,12 +7,13 @@
|
|||
- [watch](cli/watch.md)
|
||||
- [serve](cli/serve.md)
|
||||
- [test](cli/test.md)
|
||||
- [Files and Folders](folders/folders.md)
|
||||
- [Format](format/format.md)
|
||||
- [SUMMARY.md](format/summary.md)
|
||||
- [Configuration](format/config.md)
|
||||
- [Theme](format/theme/theme.md)
|
||||
- [index.hbs](format/theme/index-hbs.md)
|
||||
- [Syntax highlighting](format/theme/syntax-highlighting.md)
|
||||
- [Template](format/template/template.md)
|
||||
- [page.hbs](format/template/page-hbs.md)
|
||||
- [Syntax highlighting](format/template/syntax-highlighting.md)
|
||||
- [MathJax Support](format/mathjax.md)
|
||||
- [Rust code specific features](format/rust.md)
|
||||
- [Rust Library](lib/lib.md)
|
||||
|
|
|
|||
|
|
@ -3,11 +3,60 @@
|
|||
mdBook can be used either as a command line tool or a [Rust crate](https://crates.io/crates/mdbook).
|
||||
Let's focus on the command line tool capabilities first.
|
||||
|
||||
## Overview
|
||||
|
||||
Install with `cargo install mdbook`.
|
||||
|
||||
Create a folder and invoke `init`:
|
||||
|
||||
```bash
|
||||
mkdir thebook
|
||||
cd ./thebook
|
||||
mdbook init
|
||||
```
|
||||
|
||||
`init` will create files for a basic book:
|
||||
|
||||
```
|
||||
thebook
|
||||
├── book.toml
|
||||
└── src
|
||||
├── SUMMARY.md
|
||||
├── first-chapter.md
|
||||
├── glossary.md
|
||||
└── introduction.md
|
||||
```
|
||||
|
||||
`mdbook build` will generate the HTML in the `book/` folder.
|
||||
|
||||
If your book has images or other static assets, put them in an `assets/` folder
|
||||
and they will be copied to `book/` when building. Folders which begin with an
|
||||
underscore (e.g. `assets/_graphviz/`) will be excluded.
|
||||
|
||||
For further command options, invoke `mdbook help`:
|
||||
|
||||
```
|
||||
USAGE:
|
||||
mdbook <SUBCOMMAND>
|
||||
|
||||
FLAGS:
|
||||
-h, --help Prints help information
|
||||
-V, --version Prints version information
|
||||
|
||||
SUBCOMMANDS:
|
||||
build Build the book from the markdown files
|
||||
help Prints this message or the help of the given subcommand(s)
|
||||
init Create boilerplate structure and files in the directory
|
||||
serve Serve the book at http://localhost:3000. Rebuild and reload on change.
|
||||
test Test that code samples compile
|
||||
watch Watch the files for changes
|
||||
```
|
||||
|
||||
## Install
|
||||
|
||||
### Pre-requisite
|
||||
|
||||
mdBook is written in **[Rust](https://www.rust-lang.org/)** and therefore needs to be compiled with **Cargo**, because we don't yet offer ready-to-go binaries. If you haven't already installed Rust, please go ahead and [install it](https://www.rust-lang.org/downloads.html) now.
|
||||
mdBook is written in **[Rust](https://www.rust-lang.org/)** and therefore needs to be compiled with **Cargo**, because we don't yet offer ready-to-go binaries. If you haven't already installed Rust, please go ahead and [install it](https://www.rust-lang.org/en-US/install.html) now.
|
||||
|
||||
### Install Crates.io version
|
||||
|
||||
|
|
@ -29,7 +78,7 @@ The **[git version](https://github.com/azerupi/mdBook)** contains all the latest
|
|||
```bash
|
||||
git clone --depth=1 https://github.com/azerupi/mdBook.git
|
||||
cd mdBook
|
||||
cargo build --release
|
||||
cargo install --force
|
||||
```
|
||||
|
||||
The executable `mdbook` will be in the `./target/release` folder, this should be added to the path.
|
||||
The executable `mdbook` will be copied to `~/.cargo/bin` which should be added to the path.
|
||||
|
|
|
|||
|
|
@ -1,31 +1,38 @@
|
|||
# The init command
|
||||
|
||||
There is some minimal boilerplate that is the same for every new book. It's for this purpose that mdBook includes an `init` command.
|
||||
|
||||
The `init` command is used like this:
|
||||
Use this in an empty folder that you intend to use for your book.
|
||||
|
||||
Create a folder and invoke `init`:
|
||||
|
||||
```bash
|
||||
mkdir thebook
|
||||
cd ./thebook
|
||||
mdbook init
|
||||
```
|
||||
|
||||
When using the `init` command for the first time, a couple of files will be set up for you:
|
||||
```bash
|
||||
book-test/
|
||||
├── book
|
||||
|
||||
```
|
||||
thebook
|
||||
├── book.toml
|
||||
└── src
|
||||
├── chapter_1.md
|
||||
└── SUMMARY.md
|
||||
├── SUMMARY.md
|
||||
├── first-chapter.md
|
||||
├── glossary.md
|
||||
└── introduction.md
|
||||
```
|
||||
|
||||
- The `src` directory is were you write your book in markdown. It contains all the source files,
|
||||
configuration files, etc.
|
||||
In brief, `book.toml` has the book's general details and configuration, `src/` contains the chapters and `SUMMARY.md` defines the order of chapters as a Table of Contents.
|
||||
|
||||
- The `book` directory is where your book is rendered. All the output is ready to be uploaded
|
||||
to a server to be seen by your audience.
|
||||
`mdbook build` will generate the HTML format in the `book/` folder. This can be read locally in a brower or uploaded to be served as a static site.
|
||||
|
||||
- The `SUMMARY.md` file is the most important file, it's the skeleton of your book and is discussed in more detail in another [chapter](format/summary.html).
|
||||
See [Files and Folders](folders/folders.html) for more details on the conventions.
|
||||
|
||||
#### Tip & Trick: Hidden Feature
|
||||
When a `SUMMARY.md` file already exists, the `init` command will first parse it and generate the missing files according to the paths used in the `SUMMARY.md`. This allows you to think and create the whole structure of your book and then let mdBook generate it for you.
|
||||
#### Tip & Trick: Outline Creation
|
||||
|
||||
Chapters files in the `SUMMARY.md` will be created if they don't exist. This allows you to outline the structure of the book and let mdBook create the files an folders as described.
|
||||
|
||||
#### Specify a directory
|
||||
|
||||
|
|
@ -36,10 +43,10 @@ by appending a path to the command:
|
|||
mdbook init path/to/book
|
||||
```
|
||||
|
||||
## --theme
|
||||
## --copy-assets
|
||||
|
||||
When you use the `--theme` argument, the default theme will be copied into a directory
|
||||
called `theme` in your source directory so that you can modify it.
|
||||
When you use the `--copy-assets` argument, the default template with its static
|
||||
assets will be copied to the `assets/` folder. When a local template is found,
|
||||
it will be used instead of the default. Modifying the template and static assets
|
||||
this way allows customisation.
|
||||
|
||||
The theme is selectively overwritten, this means that if you don't want to overwrite a
|
||||
specific file, just delete it and the default file will be used.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,219 @@
|
|||
# Files and Folders
|
||||
|
||||
Let's take this example book, which has a custom page template and static assets
|
||||
(e.g. css, images, etc.):
|
||||
|
||||
```
|
||||
thebook
|
||||
├── assets
|
||||
│ ├── _html-template
|
||||
│ │ └── _layouts
|
||||
│ │ └── page.hbs
|
||||
│ ├── _sass
|
||||
│ │ └── main.sass
|
||||
│ ├── css
|
||||
│ │ ├── custom.css
|
||||
│ │ └── main.css
|
||||
│ └── img
|
||||
│ └── diagram.png
|
||||
├── book
|
||||
│ ├── css
|
||||
│ │ ├── custom.css
|
||||
│ │ └── main.css
|
||||
│ ├── img
|
||||
│ │ └── diagram.png
|
||||
│ ├── first-chapter.html
|
||||
│ ├── glossary.html
|
||||
│ ├── index.html
|
||||
│ └── print.html
|
||||
├── src
|
||||
│ ├── SUMMARY.md
|
||||
│ ├── first-chapter.md
|
||||
│ ├── glossary.md
|
||||
│ └── introduction.md
|
||||
└── book.toml
|
||||
```
|
||||
|
||||
`book.toml` describes the general details of the book such as `title` and
|
||||
`author`.
|
||||
|
||||
The `src/` folder is were you write your book in Markdown.
|
||||
|
||||
`src/SUMMARY.md` contains a list of the chapters as a Table of Contents, the
|
||||
format is discussed in more detail in another [chapter](format/summary.html).
|
||||
|
||||
`book/` is the default output folder where your book is rendered. This can be
|
||||
opened locally in a browser or uploaded to be served as a static site.
|
||||
|
||||
### Chapters
|
||||
|
||||
Chapters are Markdown files. Specific data can be given in a TOML header between
|
||||
`+++` lines:
|
||||
|
||||
```
|
||||
+++
|
||||
title = "The Library of Babel"
|
||||
author = "Jorge Luis Borges"
|
||||
translator = "James E. Irby"
|
||||
+++
|
||||
|
||||
# Babel
|
||||
|
||||
The universe (which others call the Library) is composed of an indefinite and
|
||||
perhaps infinite number of hexagonal galleries, with vast air shafts between,
|
||||
surrounded by very low railings. From any of the hexagons one can see,
|
||||
interminably, the upper and lower floors.
|
||||
```
|
||||
|
||||
### assets
|
||||
|
||||
Local assets are optional. If not present, mdBook will use its default templates
|
||||
and copy its default CSS to the output folder.
|
||||
|
||||
If an `assets/` folder is present, its contents will be copied to the output
|
||||
folder instead of using the defaults. Folders which begin with an underscore
|
||||
will be excluded. I.e. `assets/css/` will be copied, but not `assets/_sass/`.
|
||||
|
||||
Chapter pages are rendered either with the default template, or with
|
||||
`assets/_html-template/_layouts/page.hbs` if present, which is a Handlebars
|
||||
template.
|
||||
|
||||
Note that you can get a copy of the default template files by calling `mdbook
|
||||
init --copy-assets`.
|
||||
|
||||
#### custom.css
|
||||
|
||||
If a `custom.css` file is found, the page template's `{{customcss}}` helper will
|
||||
place a `<link>` to it in the html `<head>`.
|
||||
|
||||
This allows you to add small tweaks without copying and maintaining the
|
||||
template's whole CSS.
|
||||
|
||||
The following paths are checked:
|
||||
|
||||
- `assets/css/custom.css`
|
||||
- `assets/stylesheets/custom.css`
|
||||
- `assets/custom.css`
|
||||
|
||||
## Multiple Languages
|
||||
|
||||
### book.toml
|
||||
|
||||
Declare the translations as separate blocks as in the example below.
|
||||
|
||||
The main language is recognized as the first given in the TOML. Otherwise it has
|
||||
to be marked with `is_main_book = true`.
|
||||
|
||||
The language code will always be the translation key, the language name can be
|
||||
set optionally.
|
||||
|
||||
```
|
||||
[[translations.en]]
|
||||
title = "Alice's Adventures in Wonderland"
|
||||
author = "Lewis Carroll"
|
||||
|
||||
[[translations.fr]]
|
||||
title = "Alice au pays des merveilles"
|
||||
author = "Lewis Carroll"
|
||||
language_name = "Français"
|
||||
|
||||
[[translations.hu]]
|
||||
title = "Alice Csodaországban"
|
||||
author = "Lewis Carroll"
|
||||
```
|
||||
|
||||
### Folders
|
||||
|
||||
Put each translation in a sub-folder in `src/` with the translation key as the
|
||||
sub-folder. Each translation should include a `SUMMARY.md`.
|
||||
|
||||
The chapter file names can be translated if you wish the output URLs to reflect
|
||||
the translation's language.
|
||||
|
||||
```
|
||||
wonderland/
|
||||
├── book.toml
|
||||
├── assets
|
||||
│ └── images
|
||||
│ └── Rabbit.png
|
||||
└── src
|
||||
├── en
|
||||
│ ├── SUMMARY.md
|
||||
│ └── rabbit-hole.md
|
||||
├── fr
|
||||
│ ├── SUMMARY.md
|
||||
│ └── terrier.md
|
||||
└── hu
|
||||
├── SUMMARY.md
|
||||
└── nyuszi.md
|
||||
```
|
||||
|
||||
### Translation cross-linking
|
||||
|
||||
There are some mechanisms for automatic chapter-to-chapter linking between translations, or manual linking can be defined.
|
||||
|
||||
They will appear as:
|
||||
|
||||
- links to the top-level index pages of the translations are displayed above the
|
||||
TOC in the sidebar
|
||||
- chapter translations are displayed in the title bar when the application can
|
||||
find a translation, otherwise it displays a grayed-out text of the language
|
||||
code
|
||||
|
||||
Translations are identified step by step this way:
|
||||
|
||||
- taking the manual links if given in the TOML header
|
||||
- finding a match by a specific `translation_id` string given in the TOML header
|
||||
- finding a match by the chapter file's path and name
|
||||
- finding a match by section number, if the TOC is structurally the same.
|
||||
|
||||
Probably you want automatic cross-linking, which would happen if either you use
|
||||
the same chapter file paths across translations, or at least you don't change
|
||||
the number of sections and sub-sections in the TOC.
|
||||
|
||||
Otherwise, you can use a translation ID string when file names and the TOC
|
||||
structure are different:
|
||||
|
||||
In one of the translations:
|
||||
|
||||
```
|
||||
+++
|
||||
translation_id = "caucus race"
|
||||
+++
|
||||
|
||||
# A Caucus-Race and a Long Tale
|
||||
|
||||
|
||||
```
|
||||
|
||||
And in the other:
|
||||
|
||||
```
|
||||
+++
|
||||
translation_id = "caucus race"
|
||||
+++
|
||||
|
||||
# Körbecsukó meg az egér hosszú tarka farka
|
||||
|
||||
|
||||
```
|
||||
|
||||
Or else, you can define the links manually. Note, that this will break when the
|
||||
target translation's chapter file name changes.
|
||||
|
||||
```
|
||||
+++
|
||||
[[translation_links]]
|
||||
code = "fr"
|
||||
link = "fr/terrier.html"
|
||||
|
||||
[[translation_links]]
|
||||
code = "hu"
|
||||
link = "hu/nyuszi.html"
|
||||
+++
|
||||
|
||||
# Down The Rabbit-Hole
|
||||
|
||||
|
||||
```
|
||||
|
||||
|
|
@ -21,8 +21,7 @@ parent directory of the source directory.
|
|||
- **title:** The title of the book.
|
||||
- **author:** The author of the book.
|
||||
- **description:** The description, which is added as meta in the html head of each page.
|
||||
- **src:** The path to the book's source files (chapters in Markdown, SUMMARY.md, etc.). Defaults to `root/src`.
|
||||
- **dest:** The path to the directory where you want your book to be rendered. Defaults to `root/book`.
|
||||
- **theme_path:** The path to a custom theme directory. Defaults to `root/theme`.
|
||||
- **src_base:** The path to the book's source files (chapters in Markdown, SUMMARY.md, etc.). Defaults to `src/`.
|
||||
- **dest_base:** The path to the directory where you want your book to be rendered. Defaults to `book/`.
|
||||
|
||||
***note:*** *the supported configurable parameters are scarce at the moment, but more will be added in the future*
|
||||
|
|
|
|||
|
|
@ -5,4 +5,4 @@ In this section you will learn how to:
|
|||
- Structure your book correctly
|
||||
- Format your `SUMMARY.md` file
|
||||
- Configure your book using `book.toml`
|
||||
- Customize your theme
|
||||
- Customize your template
|
||||
|
|
|
|||
|
|
@ -7,26 +7,55 @@ Without this file, there is no book.
|
|||
Even though `SUMMARY.md` is a markdown file, the formatting is very strict to
|
||||
allow for easy parsing. Let's see how you should format your `SUMMARY.md` file.
|
||||
|
||||
Markdown elements that are not listed below, are unsupported in this file and
|
||||
will be ignored at best or result in an error.
|
||||
|
||||
A simple `SUMMARY.md` might look like this:
|
||||
|
||||
```markdown
|
||||
# Title
|
||||
|
||||
[Introduction](introduction.md)
|
||||
|
||||
- [First Chapter](first-chapter.md)
|
||||
- [Second Chapter]()
|
||||
|
||||
[Glossary](glossary.md)
|
||||
```
|
||||
|
||||
#### Allowed elements
|
||||
|
||||
1. ***Title*** It's common practice to begin with a title, generally
|
||||
<code class="language-markdown"># Summary</code>.
|
||||
But it is not mandatory, the parser just ignores it. So you can too
|
||||
if you feel like it.
|
||||
***Title***
|
||||
|
||||
2. ***Prefix Chapter*** Before the main numbered chapters you can add a couple of elements that will not be numbered. This is useful for
|
||||
forewords, introductions, etc. There are however some constraints. You can not nest prefix chapters, they should all be on the root level. And you can not add prefix chapters once you have added numbered chapters.
|
||||
```markdown
|
||||
[Title of prefix element](relative/path/to/markdown.md)
|
||||
```
|
||||
It's common practice to begin with a title, generally <code
|
||||
class="language-markdown"># Summary</code>. But it is not mandatory, the parser
|
||||
just ignores it. So you can too if you feel like it.
|
||||
|
||||
3. ***Numbered Chapter*** Numbered chapters are the main content of the book, they will be numbered and can be nested,
|
||||
resulting in a nice hierarchy (chapters, sub-chapters, etc.)
|
||||
```markdown
|
||||
- [Title of the Chapter](relative/path/to/markdown.md)
|
||||
```
|
||||
You can either use `-` or `*` to indicate a numbered chapter.
|
||||
***Frontmatter Chapters***
|
||||
|
||||
4. ***Suffix Chapter*** After the numbered chapters you can add a couple of non-numbered chapters. They are the same as prefix chapters but come after the numbered chapters instead of before.
|
||||
Before the main numbered chapters you can add a couple of elements that will not
|
||||
be numbered. This is useful for forewords, introductions, etc.
|
||||
|
||||
There are however some constraints. You can not nest unnunmbered chapters, they
|
||||
should all be on the root level. And you can not add unnunmbered chapters once
|
||||
you have added numbered chapters.
|
||||
|
||||
```markdown
|
||||
[Title of prefix element](relative/path/to/markdown.md)
|
||||
```
|
||||
|
||||
***Mainmatter Chapters***
|
||||
|
||||
Numbered chapters are the main content of the book, they will be numbered and
|
||||
can be nested, resulting in a nice hierarchy (chapters, sub-chapters, etc.)
|
||||
|
||||
```markdown
|
||||
- [Title of the Chapter](relative/path/to/markdown.md)
|
||||
```
|
||||
|
||||
You can either use `-` or `*` to indicate a numbered chapter.
|
||||
|
||||
***Backmatter Chapters***
|
||||
|
||||
After the numbered chapters you can add unnumbered chapters.
|
||||
|
||||
All other elements are unsupported and will be ignored at best or result in an error.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,105 @@
|
|||
# page.hbs
|
||||
|
||||
`page.hbs` is the handlebars template that is used to render the book.
|
||||
The markdown files are processed to html and then injected in that template.
|
||||
|
||||
If you want to change the layout or style of your book, chances are that you will
|
||||
have to modify this template a little bit. Here is what you need to know.
|
||||
|
||||
## Data
|
||||
|
||||
A lot of data is exposed to the handlebars template with the "context".
|
||||
In the handlebars template you can access this information by using
|
||||
|
||||
```handlebars
|
||||
{{name_of_property}}
|
||||
```
|
||||
|
||||
Here is a list of the properties that are exposed:
|
||||
|
||||
- ***language*** Language of the book in the form `en`. To use in <code class="language-html">\<html lang="{{ language }}"></code> for example. This is `en` by default, or the language key of the translation as given in `book.toml`.
|
||||
- ***title*** Title of the book, as specified in `book.toml`
|
||||
- ***page_title*** A page title that includes the chapter title, used for the `<title>` tag
|
||||
- ***path*** Relative path to the original markdown file from the source directory
|
||||
- ***content*** This is the rendered markdown.
|
||||
- ***path_to_root*** This is a path containing exclusively `../`'s that points to the root of the book from the current file.
|
||||
|
||||
A `<base>` tag is inserted in the template which uses `{{path_to_root}}` to
|
||||
maintain correct paths to relative links.
|
||||
|
||||
- ***chapters*** Is an array of dictionaries of the form
|
||||
```json
|
||||
{"section": "1.2.1", "name": "name of this chapter", "path": "dir/markdown.md"}
|
||||
```
|
||||
containing all the chapters of the book. It is used for example to construct the table of contents (sidebar).
|
||||
|
||||
## Handlebars Helpers
|
||||
|
||||
In addition to the properties you can access, there are some handlebars helpers at your disposal.
|
||||
|
||||
### toc
|
||||
|
||||
The toc helper is used like this
|
||||
|
||||
```handlebars
|
||||
{{#toc}}{{/toc}}
|
||||
```
|
||||
|
||||
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>
|
||||
```
|
||||
|
||||
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>
|
||||
```
|
||||
|
||||
### previous / next
|
||||
|
||||
The previous and next helpers expose a `link` and `name` property to the previous and next chapters.
|
||||
|
||||
They are used like this
|
||||
|
||||
```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.
|
||||
|
||||
### translation_indexes
|
||||
|
||||
Adds links to the index page of each translation.
|
||||
|
||||
### translation_links
|
||||
|
||||
Adds chapter-to-chapter links between translations.
|
||||
|
||||
### customcss
|
||||
|
||||
If a `custom.css` file is found, it adds a `<link>` tag to it.
|
||||
|
||||
------
|
||||
|
||||
*If you would like me to expose other properties or helpers, please [create a new issue](https://github.com/azerupi/mdBook/issues)
|
||||
and I will consider it.*
|
||||
|
|
@ -12,15 +12,12 @@ fn main() {
|
|||
```</code></pre>
|
||||
|
||||
## Custom theme
|
||||
Like the rest of the theme, the files used for syntax highlighting can be overridden with your own.
|
||||
|
||||
- ***highlight.js*** normally you shouldn't have to overwrite this file, unless you want to use a more recent version.
|
||||
- ***highlight.css*** theme used by highlight.js for syntax highlighting.
|
||||
To customise its CSS, call `mdbook init --copy-assets` to get the default static assets including the stylus files. Edit these and regenerate `book.css`:
|
||||
|
||||
If you want to use another theme for `highlight.js` download it from their website, or make it yourself,
|
||||
rename it to `highlight.css` and put it in `src/theme` (or the equivalent if you changed your source folder)
|
||||
|
||||
Now your theme will be used instead of the default theme.
|
||||
```
|
||||
stylus book.styl -o ../css/book.css --use nib
|
||||
```
|
||||
|
||||
## Hiding code lines
|
||||
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
# Template
|
||||
|
||||
The default renderer uses a [handlebars](http://handlebarsjs.com/) template to
|
||||
render your markdown files and comes with a default theme included in the mdBook
|
||||
binary.
|
||||
|
||||
If you wish to customise this, call `mdbook init --copy-assets` to get a copy of
|
||||
the default template and its assets.
|
||||
|
||||
The page template to render the HTML pages is expected at `assets/_html-template/_layouts/page.hbs`.
|
||||
|
||||
Everything else can be changed, since it only depends on the paths you write in `page.hbs`.
|
||||
|
||||
The stylesheets are compiled with [stylus](http://stylus-lang.com/). To use
|
||||
this, install both `stylus` and the `nib` helpers:
|
||||
|
||||
`npm install stylus nib -g`
|
||||
|
||||
|
|
@ -1,91 +0,0 @@
|
|||
# index.hbs
|
||||
|
||||
`index.hbs` is the handlebars template that is used to render the book.
|
||||
The markdown files are processed to html and then injected in that template.
|
||||
|
||||
If you want to change the layout or style of your book, chances are that you will
|
||||
have to modify this template a little bit. Here is what you need to know.
|
||||
|
||||
## Data
|
||||
|
||||
A lot of data is exposed to the handlebars template with the "context".
|
||||
In the handlebars template you can access this information by using
|
||||
|
||||
```handlebars
|
||||
{{name_of_property}}
|
||||
```
|
||||
|
||||
Here is a list of the properties that are exposed:
|
||||
|
||||
- ***language*** Language of the book in the form `en`. To use in <code class="language-html">\<html lang="{{ language }}"></code> for example.
|
||||
At the moment it is hardcoded.
|
||||
- ***title*** Title of the book, as specified in `book.toml`
|
||||
- ***path*** Relative path to the original markdown file from the source directory
|
||||
|
||||
- ***chapter_title*** Title of the current chapter, as listed in `SUMMARY.md`
|
||||
- ***content*** This is the rendered markdown.
|
||||
- ***path_to_root*** This is a path containing exclusively `../`'s that points to the root of the book from the current file.
|
||||
Since the original directory structure is maintained, it is useful to prepend relative links with this `path_to_root`.
|
||||
|
||||
- ***chapters*** Is an array of dictionaries of the form
|
||||
```json
|
||||
{"section": "1.2.1", "name": "name of this chapter", "path": "dir/markdown.md"}
|
||||
```
|
||||
containing all the chapters of the book. It is used for example to construct the table of contents (sidebar).
|
||||
|
||||
## Handlebars Helpers
|
||||
|
||||
In addition to the properties you can access, there are some handlebars helpers at your disposal.
|
||||
|
||||
1. ### toc
|
||||
|
||||
The toc helper is used like this
|
||||
|
||||
```handlebars
|
||||
{{#toc}}{{/toc}}
|
||||
```
|
||||
|
||||
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>
|
||||
```
|
||||
|
||||
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>
|
||||
```
|
||||
|
||||
2. ### previous / next
|
||||
|
||||
The previous and next helpers expose a `link` and `name` property to the previous and next chapters.
|
||||
|
||||
They are used like this
|
||||
|
||||
```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.
|
||||
|
||||
------
|
||||
|
||||
*If you would like me to expose other properties or helpers, please [create a new issue](https://github.com/azerupi/mdBook/issues)
|
||||
and I will consider it.*
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
# Theme
|
||||
|
||||
The default renderer uses a [handlebars](http://handlebarsjs.com/) template to render your markdown files and comes with a default theme
|
||||
included in the mdBook binary.
|
||||
|
||||
The theme is totally customizable, you can selectively replace every file from the theme by your own by adding a
|
||||
`theme` directory in your source folder. Create a new file with the name of the file you want to override
|
||||
and now that file will be used instead of the default file.
|
||||
|
||||
Here are the files you can override:
|
||||
|
||||
- ***index.hbs*** is the handlebars template.
|
||||
- ***book.css*** is the style used in the output. If you want to change the design of your book, this is probably the file you want to modify. Sometimes in conjunction with `index.hbs` when you want to radically change the layout.
|
||||
- ***book.js*** is mostly used to add client side functionality, like hiding / un-hiding the sidebar, changing the theme, ...
|
||||
- ***highlight.js*** is the JavaScript that is used to highlight code snippets, you should not need to modify this.
|
||||
- ***highlight.css*** is the theme used for the code highlighting
|
||||
- ***favicon.png*** the favicon that will be used
|
||||
|
||||
Generally, when you want to tweak the theme, you don't need to override all the files. If you only need changes in the stylesheet,
|
||||
there is no point in overriding all the other files. Because custom files take precedence over built-in ones, they will not get updated with new fixes / features.
|
||||
|
||||
**Note:** When you override a file, it is possible that you break some functionality. Therefore I recommend to use the file from the default theme as template and only add / modify what you need. You can copy the default theme into your source directory automatically by using `mdbook init --theme` just remove the files you don't want to override.
|
||||
|
|
@ -7,15 +7,13 @@ integrate it in current projects. Here is a short example:
|
|||
extern crate mdbook;
|
||||
|
||||
use mdbook::MDBook;
|
||||
use std::path::Path;
|
||||
use mdbook::renderer::HtmlHandlebars;
|
||||
use std::path::PathBuf;
|
||||
|
||||
fn main() {
|
||||
let mut book = MDBook::new(Path::new("my-book")) // Path to root
|
||||
.set_src(Path::new("src")) // Path from root to source directory
|
||||
.set_dest(Path::new("book")) // Path from root to output directory
|
||||
.read_config(); // Parse book.toml or book.json file for configuration
|
||||
|
||||
book.build().unwrap(); // Render the book
|
||||
let path = PathBuf::from("my-book"); // Path to the book project's root
|
||||
let renderer = HtmlHandlebars::new();
|
||||
try!(renderer.build(&path, &None)); // Build the book
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -122,7 +122,7 @@ fn confirm() -> bool {
|
|||
/// It creates some boilerplate files and directories to get you started with your book.
|
||||
///
|
||||
/// ```text
|
||||
/// thebook/
|
||||
/// thebook
|
||||
/// ├── book.toml
|
||||
/// └── src
|
||||
/// ├── SUMMARY.md
|
||||
|
|
|
|||
Loading…
Reference in New Issue