MdBook CLI usage

This page explains the most important mdBook command line arguments. For a full list, see chapter Command Line Tool of the documentation.

Installation

See the mdBook README on GitHub.

Editing locally

While editing locally, you can use a browser as a live preview of your rendered Markdown. In the root folder of the book, run

mdbook serve

Open the address http://localhost:3000 in a browser, as indicated in the output.

Alternatively, this command opens the browser automatically:

mdbook serve --open

Whenever you save edits to the book's files, the browser view will refresh.

Markdown introduction

This chapter gives a brief overview of the Markdown syntax for beginners. For details and a full list of syntax elements, see the Markdown Guide.

Basic syntax

Headings of different level

# Heading 1 / Title

## Heading 2

### Heading 3

#### ...

Emphasis

Links

A [link](http://example.com) example.

A link example.

Further formatting options are block quotes, numbered an bulleted lists, inclusion of images, etc. See the Markdown Guide.

Code blocks

Markdown supports inline code and code blocks with syntax highlighting.

Inine code must be surrounded with back-ticks. e.g. `variable_name` gives variable_name.

Code must be surrounded by triple backticks (```). A language for syntax highlighting can be given immediately after the opening backtick sequence:

```java
class Main {
    public static void main(String[] args) {

    }
}
```

Renders as:

class Main {
    public static void main(String[] args) {

    }
}

For math formulas in LaTeX syntax, see chapter MdBook features.

Tables

Tables are not supported by all Markdown dialects, but can be used with mdBook.

| Column 1 | Column 2 |
|----------|----------|
| A        | B        |
| C        | D        |

MdBook features

This chapter briefly describes some notable features of mdBook. For a full list, see the mdBook documentation.

Table of content / navigation

mdBook supports numbered and unnumbered chapters as well as sub-chapters in the navigation at the left. Details are explained in chapter SUMMARY.md of the documentation.

Math formulas

mdBook requires to explicitly enable LaTeX math support in the book.toml config file through

[output.html]
mathjax-support = true

Inline equations must be enclosed in \\(...\\): \(E = m c^2\).

Math blocks use \\[ and \\] as delimiters:

\\[
\sum_{i = m}^n a_i = a_m + a_{m+1} + a_{m+2} +\cdots+ a_{n-1} + a_n
\\]

Gives:

\[ \sum_{i = m}^n a_i = a_m + a_{m+1} + a_{m+2} +\cdots+ a_{n-1} + a_n \]

Unfortunately, this syntax is not supported by GitLab, so there will be no proper preview in the Web IDE.

Include code from files

mdBook supports including code from files, even only specific lines. For details, see section mdBook-specific features in the documentation

Other features

• Search functionality at the top of the book
• Books can be styled using custom CSS files