Skip to content

Commit 4f583df

Browse files
committed
Update documentation, Closes #80
1 parent 0a0a968 commit 4f583df

File tree

8 files changed

+116
-37
lines changed

8 files changed

+116
-37
lines changed

book-example/src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
- [Theme](format/theme/theme.md)
1313
- [index.hbs](format/theme/index-hbs.md)
1414
- [Syntax highlighting](format/theme/syntax-highlighting.md)
15+
- [MathJax Support](format/mathjax.md)
1516
- [Rust Library](lib/lib.md)
1617
-----------
1718
[Contributors](misc/contributors.md)

book-example/src/cli/cli-tool.md

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,26 @@ Let's focus on the command line tool capabilities first.
55

66
## Install
77

8-
At the moment, the only way to install mdBook is by downloading the source code from Github and building it yourself. Fortunately
9-
this is made very easy with Cargo.
8+
### Pre-requisite
109

11-
If you haven't already, you should begin by installing [Rust](https://www.rust-lang.org/install.html) and [Git](https://git-scm.com/downloads)
10+
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.
1211

13-
Open your terminal and navigate to the directory of you choice. We need to clone the git repository and then build it with Cargo.
12+
### Install Crates.io version
13+
14+
Installing mdBook is relatively easy if you already have Rust and Cargo installed. You just have to type this snippet in your terminal:
15+
16+
```bash
17+
cargo install mdbook
18+
```
19+
20+
This will fetch the source code from [Crates.io](https://crates.io/) and compile it. You will have to add Cargo's `bin` directory to your `PATH`.
21+
22+
Run `mdbook help` in your terminal to verify if it works. Congratulations, you have installed mdBook!
23+
24+
25+
### Install Git version
26+
27+
The **[git version](https://github.com/azerupi/mdBook)** contains all the latest bug-fixes and features, that will be released in the next version on **Crates.io**, if you can't wait until the next release. You can build the git version yourself. Open your terminal and navigate to the directory of you choice. We need to clone the git repository and then build it with Cargo.
1428

1529
```bash
1630
git clone --depth=1 https://github.com/azerupi/mdBook.git

book-example/src/cli/init.md

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,31 @@
11
# The init command
2+
There is some minimal boilerplate that is the same for every new book. It's for this purpose that mdBook includes an `init` command.
23

34
The `init` command is used like this:
45

56
```bash
67
mdbook init
78
```
89

9-
It will create a couple of files and directories in the working directory so that you can
10-
spend more time writing your book and less setting it up.
11-
12-
The files set up for you are the following:
13-
14-
```text
10+
When using the `init` command for the first time, a couple of files will be set up for you:
11+
```bash
1512
book-test/
1613
├── book
1714
└── src
1815
├── chapter_1.md
1916
└── SUMMARY.md
2017
```
2118

22-
The `src` directory is were you write your book in markdown. It contains all the source files,
19+
- The `src` directory is were you write your book in markdown. It contains all the source files,
2320
configuration files, etc.
2421

25-
The `book` directory is where your book is rendered. All the output is ready to be uploaded
26-
to a server to be seen by the internet.
22+
- The `book` directory is where your book is rendered. All the output is ready to be uploaded
23+
to a server to be seen by your audience.
2724

28-
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).
25+
- 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).
2926

30-
When a `SUMMARY.md` file already exists, the `init` command will generate the files according to the paths used in the `SUMMARY.md`
27+
#### Tip & Trick: Hidden Feature
28+
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.
3129

3230
#### Specify a directory
3331

book-example/src/cli/test.md

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,18 @@
11
# The test command
22

3-
It’s nice to be able to ensure that examples in documentation are current.
4-
mdBook supports a ‘test’ command, which will use Rustdoc to test out examples:
3+
When writing a book, you sometimes need to automate some tests. For example, [The Rust Programming Book](https://doc.rust-lang.org/stable/book/) uses a lot of code examples that could get outdated.
4+
Therefore it is very important for them to be able to automatically test these code examples.
55

6+
mdBook supports a `test` command that will run all available tests in mdBook. At the moment, only one test is available:
7+
*"Test Rust code examples using Rustdoc"*, but I hope this will be expanded in the future to include more tests like:
8+
9+
- checking for broken links
10+
- checking for unused files
11+
- ...
12+
13+
In the future I would like the user to be able to enable / disable test from the `book.json` configuration file and support custom tests.
14+
15+
**How to use it:**
616
```bash
717
$ mdbook test
818
[*]: Testing file: "/mdBook/book-example/src/README.md”

book-example/src/cli/watch.md

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# The watch command
22

3-
The watch command is useful when you want your book to be rendered on every file change.
4-
You could issue `mdbook build` everytime you change a file. But using `mdbook watch` once will watch your files and will trigger a build whenever you modify a file.
3+
The `watch` command is useful when you want your book to be rendered on every file change.
4+
You could repeatedly issue `mdbook build` every time a file is changed. But using `mdbook watch` once will watch your files and will trigger a build automatically whenever you modify a file.
55

66
#### Specify a directory
77

@@ -11,3 +11,8 @@ current working directory.
1111
```bash
1212
mdbook watch path/to/book
1313
```
14+
15+
16+
-----
17+
18+
***note:*** *the `watch` command has not gotten a lot of testing yet, there could be some rough edges. If you discover a problem, please report it [on Github](https://github.com/azerupi/mdBook/issues)*

book-example/src/format/mathjax.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# MathJax Support
2+
3+
mdBook supports math equations through [MathJax](https://www.mathjax.org/).
4+
5+
**However the normal method for indication math equations with `$$` does not work (yet?).**
6+
7+
To indicate an inline equation \\( \int x = \frac{x^2}{2} \\) use
8+
```
9+
\\( \int x = \frac{x^2}{2} \\)
10+
```
11+
12+
To indicate a block equation
13+
14+
\\[ \mu = \frac{1}{N} \sum_{i=0} x_i \\]
15+
16+
17+
use
18+
19+
```
20+
\\[ \mu = \frac{1}{N} \sum_{i=0} x_i \\]
21+
```

book-example/src/format/theme/syntax-highlighting.md

Lines changed: 40 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,29 +5,56 @@ For syntax highlighting I use [Highlight.js](https://highlightjs.org) with a cus
55
Automatic language detection has been turned off, so you will probably want to
66
specify the programming language you use like this
77

8-
<pre class="language-markdown"><code class="language-markdown">```rust
8+
<pre><code class="language-markdown">```rust
99
fn main() {
1010
// Some code
1111
}
1212
```</code></pre>
1313

14-
## Improve default theme
15-
16-
If you think the default theme doesn't look quite right for a specific language, or could be improved.
17-
Feel free to [submit a new issue](https://github.com/azerupi/mdBook/issues) explaining what you have in mind and I will take a look at it.
18-
19-
You could also create a pull-request with the proposed improvements.
20-
21-
Overall the theme should be light and sober, without to many flashy colors.
22-
23-
2414
## Custom theme
25-
Like the rest of the theme, the files used for syntax highlighting can be overwritten with your own.
15+
Like the rest of the theme, the files used for syntax highlighting can be overridden with your own.
2616

27-
- ***highlight.js*** normally you shouldn't have to overwrite this file. But if you need to, you can.
17+
- ***highlight.js*** normally you shouldn't have to overwrite this file, unless you want to use a more recent version.
2818
- ***highlight.css*** theme used by highlight.js for syntax highlighting.
2919

3020
If you want to use another theme for `highlight.js` download it from their website, or make it yourself,
3121
rename it to `highlight.css` and put it in `src/theme` (or the equivalent if you changed your source folder)
3222

3323
Now your theme will be used instead of the default theme.
24+
25+
## Hiding code lines
26+
27+
There is a feature in mdBook that let's you hide code lines by prepending them with a `#`.
28+
29+
30+
```bash
31+
#fn main() {
32+
let x = 5;
33+
let y = 6;
34+
35+
println!("{}", x + y);
36+
#}
37+
```
38+
39+
Will render as
40+
41+
```rust
42+
#fn main() {
43+
let x = 5;
44+
let y = 7;
45+
46+
println!("{}", x + y);
47+
#}
48+
```
49+
50+
**At the moment, this only works for code examples that are annotated with `rust`. Because it would collide with semantics of some programming languages. In the future, we want to make this configurable through the `book.json` so that everyone can benefit from it.**
51+
52+
53+
## Improve default theme
54+
55+
If you think the default theme doesn't look quite right for a specific language, or could be improved.
56+
Feel free to [submit a new issue](https://github.com/azerupi/mdBook/issues) explaining what you have in mind and I will take a look at it.
57+
58+
You could also create a pull-request with the proposed improvements.
59+
60+
Overall the theme should be light and sober, without to many flashy colors.
Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,21 @@
11
# Theme
22

3-
The default renderer uses a [handlebars](http://handlebarsjs.com/) template to render your markdown files in and comes with a default theme
3+
The default renderer uses a [handlebars](http://handlebarsjs.com/) template to render your markdown files and comes with a default theme
44
included in the mdBook binary.
55

6-
But the theme is totally customizable, you can replace every file from the theme by your own by adding a
7-
`theme` directory in your source folder. Create a new file with the name of the file you want to overwrite
6+
The theme is totally customizable, you can selectively replace every file from the theme by your own by adding a
7+
`theme` directory in your source folder. Create a new file with the name of the file you want to override
88
and now that file will be used instead of the default file.
99

10-
Here are the files you can overwrite:
10+
Here are the files you can override:
1111

1212
- ***index.hbs*** is the handlebars template.
1313
- ***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.
1414
- ***book.js*** is mostly used to add client side functionality, like hiding / un-hiding the sidebar, changing the theme, ...
1515
- ***highlight.js*** is the JavaScript that is used to highlight code snippets, you should not need to modify this.
1616
- ***highlight.css*** is the theme used for the code highlighting
1717

18-
***Note:*** *When you overwrite 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`.*
18+
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,
19+
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.
20+
21+
**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.

0 commit comments

Comments
 (0)