mirror of
https://github.com/rust-lang/mdBook
synced 2024-12-12 05:42:35 +00:00
Update documentation
This commit is contained in:
Eric Huss
parent
f3e5fce6bf
commit
f2fba30786
22 changed files with 820 additions and 606 deletions
|
|
@ -127,4 +127,4 @@ The following are instructions for updating [highlight.js](https://highlightjs.o
|
|||
1. Compare the language list that it spits out to the one in [`syntax-highlighting.md`](https://github.com/camelid/mdBook/blob/master/guide/src/format/theme/syntax-highlighting.md). If any are missing, add them to the list and rebuild (and update these docs). If any are added to the common set, add them to `syntax-highlighting.md`.
|
||||
1. Copy `build/highlight.min.js` to mdbook's directory [`highlight.js`](https://github.com/rust-lang/mdBook/blob/master/src/theme/highlight.js).
|
||||
1. Be sure to check the highlight.js [CHANGES](https://github.com/highlightjs/highlight.js/blob/main/CHANGES.md) for any breaking changes. Breaking changes that would affect users will need to wait until the next major release.
|
||||
1. Build mdbook with the new file and build some books with the new version and compare the output with a variety of languages to see if anything changes. (TODO: It would be nice to have a demo file in the repo to help with this.)
|
||||
1. Build mdbook with the new file and build some books with the new version and compare the output with a variety of languages to see if anything changes. The [test_book](https://github.com/rust-lang/mdBook/tree/master/test_book) contains a chapter with many languages to examine.
|
||||
|
|
|
|||
224
README.md
224
README.md
|
|
@ -6,233 +6,15 @@
|
|||
|
||||
mdBook is a utility to create modern online books from Markdown files.
|
||||
|
||||
Check out the **[User Guide]** for a list of features and installation and usage information.
|
||||
The User Guide also serves as a demonstration to showcase what a book looks like.
|
||||
|
||||
## What does it look like?
|
||||
|
||||
The [User Guide] for mdBook has been written in Markdown and is using mdBook to
|
||||
generate the online book-like website you can read. The documentation uses the
|
||||
latest version on GitHub and showcases the available features.
|
||||
|
||||
## Installation
|
||||
|
||||
There are multiple ways to install mdBook.
|
||||
|
||||
1. **Binaries**
|
||||
|
||||
Binaries are available for download [here][releases]. Make sure to put the
|
||||
path to the binary into your `PATH`.
|
||||
|
||||
2. **From Crates.io**
|
||||
|
||||
This requires at least [Rust] 1.46 and Cargo to be installed. Once you have installed
|
||||
Rust, type the following in the terminal:
|
||||
|
||||
```
|
||||
cargo install mdbook
|
||||
```
|
||||
|
||||
This will download and compile mdBook for you, the only thing left to do is
|
||||
to add the Cargo bin directory to your `PATH`.
|
||||
|
||||
**Note for automatic deployment**
|
||||
|
||||
If you are using a script to do automatic deployments, we recommend that
|
||||
you specify a semver version range for mdBook when you install it through
|
||||
your script!
|
||||
|
||||
This will constrain the server to install the latest **non-breaking**
|
||||
version of mdBook and will prevent your books from failing to build because
|
||||
we released a new version.
|
||||
|
||||
You can also disable default features to speed up compile time.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
cargo install mdbook --no-default-features --vers "^0.4.0"
|
||||
```
|
||||
|
||||
3. **From Git**
|
||||
|
||||
The version published to crates.io will ever so slightly be behind the
|
||||
version hosted here on GitHub. If you need the latest version you can build
|
||||
the git version of mdBook yourself. Cargo makes this ***super easy***!
|
||||
|
||||
```
|
||||
cargo install --git https://github.com/rust-lang/mdBook.git mdbook
|
||||
```
|
||||
|
||||
Again, make sure to add the Cargo bin directory to your `PATH`.
|
||||
|
||||
4. **For Contributions**
|
||||
|
||||
If you want to contribute to mdBook you will have to clone the repository on
|
||||
your local machine:
|
||||
|
||||
```
|
||||
git clone https://github.com/rust-lang/mdBook.git
|
||||
```
|
||||
|
||||
`cd` into `mdBook/` and run
|
||||
|
||||
```
|
||||
cargo build
|
||||
```
|
||||
|
||||
The resulting binary can be found in `mdBook/target/debug/` under the name
|
||||
`mdBook` or `mdBook.exe`.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
mdBook is primarily used as a command line tool, even though it exposes
|
||||
all its functionality as a Rust crate for integration in other projects.
|
||||
|
||||
Here are the main commands you will want to run. For a more exhaustive
|
||||
explanation, check out the [User Guide].
|
||||
|
||||
- `mdbook init <directory>`
|
||||
|
||||
The init command will create a directory with the minimal boilerplate to
|
||||
start with. If the `<directory>` parameter is omitted, the current
|
||||
directory will be used.
|
||||
|
||||
```
|
||||
book-test/
|
||||
├── book
|
||||
└── src
|
||||
├── chapter_1.md
|
||||
└── SUMMARY.md
|
||||
```
|
||||
|
||||
`book` and `src` are both directories. `src` contains the markdown files
|
||||
that will be used to render the output to the `book` directory.
|
||||
|
||||
Please, take a look at the [CLI docs] for more information and some neat tricks.
|
||||
|
||||
- `mdbook build`
|
||||
|
||||
This is the command you will run to render your book, it reads the
|
||||
`SUMMARY.md` file to understand the structure of your book, takes the
|
||||
markdown files in the source directory as input and outputs static html
|
||||
pages that you can upload to a server.
|
||||
|
||||
- `mdbook watch`
|
||||
|
||||
When you run this command, mdbook will watch your markdown files to rebuild
|
||||
the book on every change. This avoids having to come back to the terminal
|
||||
to type `mdbook build` over and over again.
|
||||
|
||||
- `mdbook serve`
|
||||
|
||||
Does the same thing as `mdbook watch` but additionally serves the book at
|
||||
`http://localhost:3000` (port is changeable) and reloads the browser when a
|
||||
change occurs.
|
||||
|
||||
- `mdbook clean`
|
||||
|
||||
Delete directory in which generated book is located.
|
||||
|
||||
### 3rd Party Plugins
|
||||
|
||||
The way a book is loaded and rendered can be configured by the user via third
|
||||
party plugins. These plugins are just programs which will be invoked during the
|
||||
build process and are split into roughly two categories, *preprocessors* and
|
||||
*renderers*.
|
||||
|
||||
Preprocessors are used to transform a book before it is sent to a renderer.
|
||||
One example would be to replace all occurrences of
|
||||
`{{#include some_file.ext}}` with the contents of that file. Some existing
|
||||
preprocessors are:
|
||||
|
||||
- `index` - a built-in preprocessor (enabled by default) which will transform
|
||||
all `README.md` chapters to `index.md` so `foo/README.md` can be accessed via
|
||||
the url `foo/` when published to a browser
|
||||
- `links` - a built-in preprocessor (enabled by default) for expanding the
|
||||
`{{# playground}}` and `{{# include}}` helpers in a chapter.
|
||||
- [`katex`](https://github.com/lzanini/mdbook-katex) - a preprocessor rendering LaTex equations to HTML.
|
||||
|
||||
Renderers are given the final book so they can do something with it. This is
|
||||
typically used for, as the name suggests, rendering the document in a particular
|
||||
format, however there's nothing stopping a renderer from doing static analysis
|
||||
of a book in order to validate links or run tests. Some existing renderers are:
|
||||
|
||||
- `html` - the built-in renderer which will generate a HTML version of the book
|
||||
- `markdown` - the built-in renderer (disabled by default) which will run
|
||||
preprocessors then output the resulting Markdown. Useful for debugging
|
||||
preprocessors.
|
||||
- [`linkcheck`] - a backend which will check that all links are valid
|
||||
- [`epub`] - an experimental EPUB generator
|
||||
- [`man`] - a backend that generates manual pages from the book
|
||||
|
||||
> **Note for Developers:** Feel free to send us a PR if you've developed your
|
||||
> own plugin and want it mentioned here.
|
||||
|
||||
A preprocessor or renderer is enabled by installing the appropriate program and
|
||||
then mentioning it in the book's `book.toml` file.
|
||||
|
||||
```console
|
||||
$ cargo install mdbook-linkcheck
|
||||
$ edit book.toml && cat book.toml
|
||||
[book]
|
||||
title = "My Awesome Book"
|
||||
authors = ["Michael-F-Bryan"]
|
||||
|
||||
[output.html]
|
||||
|
||||
[output.linkcheck] # enable the "mdbook-linkcheck" renderer
|
||||
|
||||
$ mdbook build
|
||||
2018-10-20 13:57:51 [INFO] (mdbook::book): Book building has started
|
||||
2018-10-20 13:57:51 [INFO] (mdbook::book): Running the html backend
|
||||
2018-10-20 13:57:53 [INFO] (mdbook::book): Running the linkcheck backend
|
||||
```
|
||||
|
||||
For more information on the plugin system, consult the [User Guide].
|
||||
|
||||
### As a library
|
||||
|
||||
Aside from the command line interface, this crate can also be used as a
|
||||
library. This means that you could integrate it in an existing project, like a
|
||||
web-app for example. Since the command line interface is just a wrapper around
|
||||
the library functionality, when you use this crate as a library you have full
|
||||
access to all the functionality of the command line interface with an easy to
|
||||
use API and more!
|
||||
|
||||
See the [User Guide] and the [API docs] for more information.
|
||||
|
||||
## Contributions
|
||||
|
||||
Contributions are highly appreciated and encouraged! Don't hesitate to
|
||||
participate to discussions in the issues, propose new features and ask for
|
||||
help.
|
||||
|
||||
If you are just starting out with Rust, there are a series of issues that are
|
||||
tagged [E-Easy] and **we will gladly mentor you** so that you can successfully
|
||||
go through the process of fixing a bug or adding a new feature! Let us know if
|
||||
you need any help.
|
||||
|
||||
For more info about contributing, check out our [contribution guide] which helps
|
||||
you go through the build and contribution process!
|
||||
|
||||
There is also a [rendered version][master-docs] of the latest API docs
|
||||
available, for those hacking on `master`.
|
||||
|
||||
If you are interested in contributing to the development of mdBook, check out the [Contribution Guide].
|
||||
|
||||
## License
|
||||
|
||||
All the code in this repository is released under the ***Mozilla Public License v2.0***, for more information take a look at the [LICENSE] file.
|
||||
|
||||
|
||||
[User Guide]: https://rust-lang.github.io/mdBook/
|
||||
[API docs]: https://docs.rs/mdbook/*/mdbook/
|
||||
[E-Easy]: https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AE-Easy
|
||||
[contribution guide]: https://github.com/rust-lang/mdBook/blob/master/CONTRIBUTING.md
|
||||
[LICENSE]: https://github.com/rust-lang/mdBook/blob/master/LICENSE
|
||||
[releases]: https://github.com/rust-lang/mdBook/releases
|
||||
[Rust]: https://www.rust-lang.org/
|
||||
[CLI docs]: http://rust-lang.github.io/mdBook/cli/init.html
|
||||
[master-docs]: http://rust-lang.github.io/mdBook/
|
||||
[`linkcheck`]: https://crates.io/crates/mdbook-linkcheck
|
||||
[`epub`]: https://crates.io/crates/mdbook-epub
|
||||
[`man`]: https://crates.io/crates/mdbook-man
|
||||
|
|
|
|||
|
|
@ -1,22 +1,30 @@
|
|||
# Introduction
|
||||
|
||||
**mdBook** is a command line tool and Rust crate to create books with Markdown. The output resembles tools like Gitbook,
|
||||
and is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean,
|
||||
easily navigable and customizable presentation. mdBook is written in [Rust](https://www.rust-lang.org); its performance
|
||||
and simplicity made it ideal for use as a tool to publish directly to hosted websites such
|
||||
as [GitHub Pages](https://pages.github.com) via automation. This guide, in fact, serves as both the mdBook documentation
|
||||
and a fine example of what mdBook produces.
|
||||
**mdBook** is a command line tool to create books with Markdown.
|
||||
It is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean,
|
||||
easily navigable and customizable presentation.
|
||||
|
||||
mdBook includes built in support for both preprocessing your Markdown and alternative renderers for producing formats
|
||||
other than HTML. These facilities also enable other functionality such as
|
||||
validation. [Searching](https://crates.io/search?q=mdbook&sort=relevance) Rust's [crates.io](https://crates.io) is a
|
||||
great way to discover more extensions.
|
||||
* Lightweight [Markdown] syntax helps you focus more on your content
|
||||
* Integrated [search] support
|
||||
* Color [syntax highlighting] for code blocks for many different languages
|
||||
* [Theme] files allow customizing the formatting of the output
|
||||
* [Preprocessors] can provide extensions for custom syntax and modifying content
|
||||
* [Backends] can render the output to multiple formats
|
||||
* Written in [Rust] for speed, safety, and simplicity
|
||||
* Automated testing of [Rust code samples]
|
||||
|
||||
## API Documentation
|
||||
This guide is an example of what mdBook produces.
|
||||
mdBook is used by the Rust programming language project, and [The Rust Programming Language][trpl] book is another fine example of mdBook in action.
|
||||
|
||||
In addition to the above features, mdBook also has a Rust [API](https://docs.rs/mdbook/*/mdbook/). This allows you to
|
||||
write your own preprocessor or renderer, as well as incorporate mdBook features into other applications.
|
||||
The [For Developers](for_developers) section of this guide contains more information and some examples.
|
||||
[Markdown]: format/markdown.md
|
||||
[search]: guide/reading.md#search
|
||||
[syntax highlighting]: format/theme/syntax-highlighting.md
|
||||
[theme]: format/theme/index.html
|
||||
[preprocessors]: format/configuration/preprocessors.md
|
||||
[backends]: format/configuration/renderers.md
|
||||
[Rust]: https://www.rust-lang.org/
|
||||
[trpl]: https://doc.rust-lang.org/book/
|
||||
[Rust code samples]: cli/test.md
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,15 @@
|
|||
# Summary
|
||||
|
||||
- [Introduction](README.md)
|
||||
[Introduction](README.md)
|
||||
|
||||
# User Guide
|
||||
|
||||
- [Installation](guide/installation.md)
|
||||
- [Reading Books](guide/reading.md)
|
||||
- [Creating a Book](guide/creating.md)
|
||||
|
||||
# Reference Guide
|
||||
|
||||
- [Command Line Tool](cli/README.md)
|
||||
- [init](cli/init.md)
|
||||
- [build](cli/build.md)
|
||||
|
|
@ -8,6 +17,7 @@
|
|||
- [serve](cli/serve.md)
|
||||
- [test](cli/test.md)
|
||||
- [clean](cli/clean.md)
|
||||
- [completions](cli/completions.md)
|
||||
- [Format](format/README.md)
|
||||
- [SUMMARY.md](format/summary.md)
|
||||
- [Draft chapter]()
|
||||
|
|
|
|||
|
|
@ -1,55 +1,14 @@
|
|||
# Command Line Tool
|
||||
|
||||
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.
|
||||
The `mdbook` command-line tool is used to create and build books.
|
||||
After you have [installed](../guide/installation.md) `mdbook`, you can run the `mdbook help` command in your terminal to view the available commands.
|
||||
|
||||
## Install From Binaries
|
||||
This following sections provide in-depth information on the different commands available.
|
||||
|
||||
Precompiled binaries are provided for major platforms on a best-effort basis.
|
||||
Visit [the releases page](https://github.com/rust-lang/mdBook/releases)
|
||||
to download the appropriate version for your platform.
|
||||
|
||||
## Install From Source
|
||||
|
||||
mdBook can also be installed by compiling the source code on your local machine.
|
||||
|
||||
### Pre-requisite
|
||||
|
||||
mdBook is written in **[Rust](https://www.rust-lang.org/)** and therefore needs
|
||||
to be compiled with **Cargo**. If you haven't already installed Rust, please go
|
||||
ahead and [install it](https://www.rust-lang.org/tools/install) now.
|
||||
|
||||
### Install Crates.io version
|
||||
|
||||
Installing mdBook is relatively easy if you already have Rust and Cargo
|
||||
installed. You just have to type this snippet in your terminal:
|
||||
|
||||
```bash
|
||||
cargo install mdbook
|
||||
```
|
||||
|
||||
This will fetch the source code for the latest release from
|
||||
[Crates.io](https://crates.io/) and compile it. You will have to add Cargo's
|
||||
`bin` directory to your `PATH`.
|
||||
|
||||
Run `mdbook help` in your terminal to verify if it works. Congratulations, you
|
||||
have installed mdBook!
|
||||
|
||||
|
||||
### Install Git version
|
||||
|
||||
The **[git version](https://github.com/rust-lang/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.
|
||||
|
||||
```bash
|
||||
git clone --depth=1 https://github.com/rust-lang/mdBook.git
|
||||
cd mdBook
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
The executable `mdbook` will be in the `./target/release` folder, this should be
|
||||
added to the path.
|
||||
* [`mdbook init <directory>`](init.md) — Creates a new book with minimal boilerplate to start with.
|
||||
* [`mdbook build`](build.md) — Renders the book.
|
||||
* [`mdbook watch`](watch.md) — Rebuilds the book any time a source file changes.
|
||||
* [`mdbook serve`](serve.md) — Runs a web server to view the book, and rebuilds on changes.
|
||||
* [`mdbook test`](test.md) — Tests Rust code samples.
|
||||
* [`mdbook clean`](clean.md) — Deletes the rendered output.
|
||||
* [`mdbook completions`](completions.md) — Support for shell auto-completion.
|
||||
|
|
|
|||
16
guide/src/cli/completions.md
Normal file
16
guide/src/cli/completions.md
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
# The completions command
|
||||
|
||||
The completions command is used to generate auto-completions for some common shells.
|
||||
This means when you type `mdbook` in your shell, you can then press your shell's auto-complete key (usually the Tab key) and it may display what the valid options are, or finish partial input.
|
||||
|
||||
The completions first need to be installed for your shell:
|
||||
|
||||
```bash
|
||||
mdbook completions bash > ~/.local/share/bash-completion/completions/mdbook
|
||||
```
|
||||
|
||||
The command prints a completion script for the given shell.
|
||||
Run `mdbook completions --help` for a list of supported shells.
|
||||
|
||||
Where to place the completions depend on which shell you are using and your operating system.
|
||||
Consult your shell's documentation for more information one where to place the script.
|
||||
|
|
@ -1,154 +1,121 @@
|
|||
# Running `mdbook` in Continuous Integration
|
||||
|
||||
While the following examples use Travis CI, their principles should
|
||||
straightforwardly transfer to other continuous integration providers as well.
|
||||
There are a variety of services such as [GitHub Actions] or [GitLab CI/CD] which can be used to test and deploy your book automatically.
|
||||
|
||||
## Ensuring Your Book Builds and Tests Pass
|
||||
The following provides some general guidelines on how to configure your service to run mdBook.
|
||||
Specific recipes can be found at the [Automated Deployment] wiki page.
|
||||
|
||||
Here is a sample Travis CI `.travis.yml` configuration that ensures `mdbook
|
||||
build` and `mdbook test` run successfully. The key to fast CI turnaround times
|
||||
is caching `mdbook` installs, so that you aren't compiling `mdbook` on every CI
|
||||
run.
|
||||
[GitHub Actions]: https://docs.github.com/en/actions
|
||||
[GitLab CI/CD]: https://docs.gitlab.com/ee/ci/
|
||||
[Automated Deployment]: https://github.com/rust-lang/mdBook/wiki/Automated-Deployment
|
||||
|
||||
```yaml
|
||||
language: rust
|
||||
sudo: false
|
||||
## Installing mdBook
|
||||
|
||||
cache:
|
||||
- cargo
|
||||
There are several different strategies for installing mdBook.
|
||||
The particular method depends on your needs and preferences.
|
||||
|
||||
rust:
|
||||
- stable
|
||||
### Pre-compiled binaries
|
||||
|
||||
before_script:
|
||||
- (test -x $HOME/.cargo/bin/cargo-install-update || cargo install cargo-update)
|
||||
- (test -x $HOME/.cargo/bin/mdbook || cargo install --vers "^0.3" mdbook)
|
||||
- cargo install-update -a
|
||||
Perhaps the easiest method is to use the pre-compiled binaries found on the [GitHub Releases page][releases].
|
||||
A simple approach would be to use the popular `curl` CLI tool to download the executable:
|
||||
|
||||
script:
|
||||
- mdbook build && mdbook test # In case of custom book path: mdbook build path/to/mybook && mdbook test path/to/mybook
|
||||
```sh
|
||||
mkdir bin
|
||||
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
|
||||
bin/mdbook build
|
||||
```
|
||||
|
||||
## Deploying Your Book to GitHub Pages
|
||||
Some considerations for this approach:
|
||||
|
||||
Following these instructions will result in your book being published to GitHub
|
||||
pages after a successful CI run on your repository's `master` branch.
|
||||
* This is relatively fast, and does not necessarily require dealing with caching.
|
||||
* This does not require installing Rust.
|
||||
* Specifying a specific URL means you have to manually update your script to get a new version.
|
||||
This may be a benefit if you want to lock to a specific version.
|
||||
However, some users prefer to automatically get a newer version when they are published.
|
||||
* You are reliant on the GitHub CDN being available.
|
||||
|
||||
First, create a new GitHub "Personal Access Token" with the "public_repo"
|
||||
permissions (or "repo" for private repositories). Go to your repository's Travis
|
||||
CI settings page and add an environment variable named `GITHUB_TOKEN` that is
|
||||
marked secure and *not* shown in the logs.
|
||||
[releases]: https://github.com/rust-lang/mdBook/releases
|
||||
|
||||
Whilst still in your repository's settings page, navigate to Options and change the
|
||||
Source on GitHub pages to `gh-pages`.
|
||||
### Building from source
|
||||
|
||||
Then, append this snippet to your `.travis.yml` and update the path to the
|
||||
`book` directory:
|
||||
Building from source will require having Rust installed.
|
||||
Some services have Rust pre-installed, but if your service does not, you will need to add a step to install it.
|
||||
|
||||
```yaml
|
||||
deploy:
|
||||
provider: pages
|
||||
skip-cleanup: true
|
||||
github-token: $GITHUB_TOKEN
|
||||
local-dir: book # In case of custom book path: path/to/mybook/book
|
||||
keep-history: false
|
||||
on:
|
||||
branch: main
|
||||
After Rust is installed, `cargo install` can be used to build and install mdBook.
|
||||
We recommend using a SemVer version specifier so that you get the latest **non-breaking** version of mdBook.
|
||||
For example:
|
||||
|
||||
```sh
|
||||
cargo install mdbook --no-default-features --features search --vers "^0.4" --locked
|
||||
```
|
||||
|
||||
That's it!
|
||||
This includes several recommended options:
|
||||
|
||||
Note: Travis has a new [dplv2](https://blog.travis-ci.com/2019-08-27-deployment-tooling-dpl-v2-preview-release) configuration that is currently in beta. To use this new format, update your `.travis.yml` file to:
|
||||
* `--no-default-features` — Disables features like the HTTP server used by `mdbook serve` that is likely not needed on CI.
|
||||
This will speed up the build time significantly.
|
||||
* `--features search` — Disabling default features means you should then manually enable features that you want, such as the built-in [search] capability.
|
||||
* `--vers "^0.4"` — This will install the most recent version of the `0.4` series.
|
||||
However, versions after like `0.5.0` won't be installed, as they may break your build.
|
||||
Cargo will automatically upgrade mdBook if you have an older version already installed.
|
||||
* `--locked` — This will use the dependencies that were used when mdBook was released.
|
||||
Without `--locked`, it will use the latest version of all dependencies, which may include some fixes since the last release, but may also (rarely) cause build problems.
|
||||
|
||||
```yaml
|
||||
language: rust
|
||||
os: linux
|
||||
dist: xenial
|
||||
You will likely want to investigate caching options, as building mdBook can be somewhat slow.
|
||||
|
||||
cache:
|
||||
- cargo
|
||||
[search]: guide/reading.md#search
|
||||
|
||||
rust:
|
||||
- stable
|
||||
## Running tests
|
||||
|
||||
before_script:
|
||||
- (test -x $HOME/.cargo/bin/cargo-install-update || cargo install cargo-update)
|
||||
- (test -x $HOME/.cargo/bin/mdbook || cargo install --vers "^0.3" mdbook)
|
||||
- cargo install-update -a
|
||||
You may want to run tests using [`mdbook test`] every time you push a change or create a pull request.
|
||||
This can be used to validate Rust code examples in the book.
|
||||
|
||||
script:
|
||||
- mdbook build && mdbook test # In case of custom book path: mdbook build path/to/mybook && mdbook test path/to/mybook
|
||||
|
||||
deploy:
|
||||
provider: pages
|
||||
strategy: git
|
||||
edge: true
|
||||
cleanup: false
|
||||
github-token: $GITHUB_TOKEN
|
||||
local-dir: book # In case of custom book path: path/to/mybook/book
|
||||
keep-history: false
|
||||
on:
|
||||
branch: main
|
||||
target_branch: gh-pages
|
||||
This will require having Rust installed.
|
||||
Some services have Rust pre-installed, but if your service does not, you will need to add a step to install it.
|
||||
|
||||
Other than making sure the appropriate version of Rust is installed, there's not much more than just running `mdbook test` from the book directory.
|
||||
|
||||
You may also want to consider running other kinds of tests, like [mdbook-linkcheck] which will check for broken links.
|
||||
Or if you have your own style checks, spell checker, or any other tests it might be good to run them in CI.
|
||||
|
||||
[`mdbook test`]: cli/test.md
|
||||
[mdbook-linkcheck]: https://github.com/Michael-F-Bryan/mdbook-linkcheck#continuous-integration
|
||||
|
||||
## Deploying
|
||||
|
||||
You may want to automatically deploy your book.
|
||||
Some may want to do this with every time a change is pushed, and others may want to only deploy when a specific release is tagged.
|
||||
|
||||
You'll also need to understand the specifics on how to push a change to your web service.
|
||||
For example, [GitHub Pages] just requires committing the output onto a specific git branch.
|
||||
Other services may require using something like SSH to connect to a remote server.
|
||||
|
||||
The basic outline is that you need to run `mdbook build` to generate the output, and then transfer the files (which are in the `book` directory) to the correct location.
|
||||
|
||||
You may then want to consider if you need to invalidate any caches on your web service.
|
||||
|
||||
See the [Automated Deployment] wiki page for examples of various different services.
|
||||
|
||||
[GitHub Pages]: https://docs.github.com/en/pages
|
||||
|
||||
### 404 handling
|
||||
|
||||
mdBook automatically generates a 404 page to be used for broken links.
|
||||
The default output is a file named `404.html` at the root of the book.
|
||||
Some services like [GitHub Pages] will automatically use this page for broken links.
|
||||
For other services, you may want to consider configuring the web server to use this page as it will provide the reader navigation to get back to the book.
|
||||
|
||||
If your book is not deployed at the root of the domain, then you should set the [`output.html.site-url`] setting so that the 404 page works correctly.
|
||||
It needs to know where the book is deployed in order to load the static files (like CSS) correctly.
|
||||
For example, this guide is deployed at <https://rust-lang.github.io/mdBook/>, and the `site-url` setting is configured like this:
|
||||
|
||||
```toml
|
||||
# book.toml
|
||||
[output.html]
|
||||
site-url = "/mdBook/"
|
||||
```
|
||||
|
||||
### Deploying to GitHub Pages manually
|
||||
You can customize the look of the 404 page by creating a file named `src/404.md` in your book.
|
||||
If you want to use a different filename, you can set [`output.html.input-404`] to a different filename.
|
||||
|
||||
If your CI doesn't support GitHub pages, or you're deploying somewhere else
|
||||
with integrations such as Github Pages:
|
||||
*note: you may want to use different tmp dirs*:
|
||||
|
||||
```console
|
||||
$> git worktree add /tmp/book gh-pages
|
||||
$> mdbook build
|
||||
$> rm -rf /tmp/book/* # this won't delete the .git directory
|
||||
$> cp -rp book/* /tmp/book/
|
||||
$> cd /tmp/book
|
||||
$> git add -A
|
||||
$> git commit 'new book message'
|
||||
$> git push origin gh-pages
|
||||
$> cd -
|
||||
```
|
||||
|
||||
Or put this into a Makefile rule:
|
||||
|
||||
```makefile
|
||||
.PHONY: deploy
|
||||
deploy: book
|
||||
@echo "====> deploying to github"
|
||||
git worktree add /tmp/book gh-pages
|
||||
rm -rf /tmp/book/*
|
||||
cp -rp book/* /tmp/book/
|
||||
cd /tmp/book && \
|
||||
git add -A && \
|
||||
git commit -m "deployed on $(shell date) by ${USER}" && \
|
||||
git push origin gh-pages
|
||||
```
|
||||
|
||||
## Deploying Your Book to GitLab Pages
|
||||
Inside your repository's project root, create a file named `.gitlab-ci.yml` with the following contents:
|
||||
```yml
|
||||
stages:
|
||||
- deploy
|
||||
|
||||
pages:
|
||||
stage: deploy
|
||||
image: rust
|
||||
variables:
|
||||
CARGO_HOME: $CI_PROJECT_DIR/cargo
|
||||
before_script:
|
||||
- export PATH="$PATH:$CARGO_HOME/bin"
|
||||
- mdbook --version || cargo install mdbook
|
||||
script:
|
||||
- mdbook build -d public
|
||||
rules:
|
||||
- if: '$CI_COMMIT_REF_NAME == "master"'
|
||||
artifacts:
|
||||
paths:
|
||||
- public
|
||||
cache:
|
||||
paths:
|
||||
- $CARGO_HOME/bin
|
||||
```
|
||||
|
||||
After you commit and push this new file, GitLab CI will run and your book will be available!
|
||||
[`output.html.site-url`]: format/configuration/renderers.md#html-renderer-options
|
||||
[`output.html.input-404`]: format/configuration/renderers.md#html-renderer-options
|
||||
|
|
|
|||
|
|
@ -24,8 +24,9 @@ The process of rendering a book project goes through several steps.
|
|||
exist
|
||||
- Load the book chapters into memory
|
||||
- Discover which preprocessors/backends should be used
|
||||
2. Run the preprocessors
|
||||
3. Call each backend in turn
|
||||
2. For each backend:
|
||||
1. Run all the preprocessors.
|
||||
2. Call the backend to render the processed result.
|
||||
|
||||
|
||||
## Using `mdbook` as a Library
|
||||
|
|
|
|||
|
|
@ -5,23 +5,17 @@ rendering process. This program is passed a JSON representation of the book and
|
|||
configuration information via `stdin`. Once the backend receives this
|
||||
information it is free to do whatever it wants.
|
||||
|
||||
There are already several alternative backends on GitHub which can be used as a
|
||||
rough example of how this is accomplished in practice.
|
||||
See [Configuring Renderers](../format/configuration/renderers.md) for more information about using backends.
|
||||
|
||||
- [mdbook-linkcheck] - a simple program for verifying the book doesn't contain
|
||||
any broken links
|
||||
- [mdbook-epub] - an EPUB renderer
|
||||
- [mdbook-test] - a program to run the book's contents through [rust-skeptic] to
|
||||
verify everything compiles and runs correctly (similar to `rustdoc --test`)
|
||||
- [mdbook-man] - generate manual pages from the book
|
||||
The community has developed several backends.
|
||||
See the [Third Party Plugins] wiki page for a list of available backends.
|
||||
|
||||
## Setting Up
|
||||
|
||||
This page will step you through creating your own alternative backend in the form
|
||||
of a simple word counting program. Although it will be written in Rust, there's
|
||||
no reason why it couldn't be accomplished using something like Python or Ruby.
|
||||
|
||||
|
||||
## Setting Up
|
||||
|
||||
First you'll want to create a new binary program and add `mdbook` as a
|
||||
dependency.
|
||||
|
||||
|
|
@ -330,39 +324,6 @@ generation or a warning).
|
|||
All environment variables are passed through to the backend, allowing you to use
|
||||
the usual `RUST_LOG` to control logging verbosity.
|
||||
|
||||
## Handling missing backends
|
||||
|
||||
If you enable a backend that isn't installed, the default behavior is to throw an error:
|
||||
|
||||
```text
|
||||
The command `mdbook-wordcount` wasn't found, is the "wordcount" backend installed?
|
||||
If you want to ignore this error when the "wordcount" backend is not installed,
|
||||
set `optional = true` in the `[output.wordcount]` section of the book.toml configuration file.
|
||||
```
|
||||
|
||||
This behavior can be changed by marking the backend as optional.
|
||||
|
||||
```diff
|
||||
[book]
|
||||
title = "mdBook Documentation"
|
||||
description = "Create book from markdown files. Like Gitbook but implemented in Rust"
|
||||
authors = ["Mathieu David", "Michael-F-Bryan"]
|
||||
|
||||
[output.html]
|
||||
|
||||
[output.wordcount]
|
||||
command = "python /path/to/wordcount.py"
|
||||
+ optional = true
|
||||
```
|
||||
|
||||
This demotes the error to a warning, and it will instead look like this:
|
||||
|
||||
```text
|
||||
The command was not found, but was marked as optional.
|
||||
Command: wordcount
|
||||
```
|
||||
|
||||
|
||||
## Wrapping Up
|
||||
|
||||
Although contrived, hopefully this example was enough to show how you'd create
|
||||
|
|
@ -375,11 +336,7 @@ as a good example of how it's done in real life, so feel free to skim through
|
|||
the source code or ask questions.
|
||||
|
||||
|
||||
[mdbook-linkcheck]: https://github.com/Michael-F-Bryan/mdbook-linkcheck
|
||||
[mdbook-epub]: https://github.com/Michael-F-Bryan/mdbook-epub
|
||||
[mdbook-test]: https://github.com/Michael-F-Bryan/mdbook-test
|
||||
[mdbook-man]: https://github.com/vv9k/mdbook-man
|
||||
[rust-skeptic]: https://github.com/budziq/rust-skeptic
|
||||
[Third Party Plugins]: https://github.com/rust-lang/mdBook/wiki/Third-party-plugins
|
||||
[`RenderContext`]: https://docs.rs/mdbook/*/mdbook/renderer/struct.RenderContext.html
|
||||
[`RenderContext::from_json()`]: https://docs.rs/mdbook/*/mdbook/renderer/struct.RenderContext.html#method.from_json
|
||||
[`semver`]: https://crates.io/crates/semver
|
||||
|
|
|
|||
|
|
@ -5,35 +5,18 @@ book is loaded and before it gets rendered, allowing you to update and mutate
|
|||
the book. Possible use cases are:
|
||||
|
||||
- Creating custom helpers like `\{{#include /path/to/file.md}}`
|
||||
- Updating links so `[some chapter](some_chapter.md)` is automatically changed
|
||||
to `[some chapter](some_chapter.html)` for the HTML renderer
|
||||
- Substituting in latex-style expressions (`$$ \frac{1}{3} $$`) with their
|
||||
mathjax equivalents
|
||||
|
||||
See [Configuring Preprocessors](../format/configuration/preprocessors.md) for more information about using preprocessors.
|
||||
|
||||
## Hooking Into MDBook
|
||||
|
||||
MDBook uses a fairly simple mechanism for discovering third party plugins.
|
||||
A new table is added to `book.toml` (e.g. `preprocessor.foo` for the `foo`
|
||||
A new table is added to `book.toml` (e.g. `[preprocessor.foo]` for the `foo`
|
||||
preprocessor) and then `mdbook` will try to invoke the `mdbook-foo` program as
|
||||
part of the build process.
|
||||
|
||||
A preprocessor can be hard-coded to specify which backend(s) it should be run
|
||||
for with the `preprocessor.foo.renderer` key. For example, it doesn't make sense for
|
||||
[MathJax](../format/mathjax.md) to be used for non-HTML renderers.
|
||||
|
||||
```toml
|
||||
[book]
|
||||
title = "My Book"
|
||||
authors = ["Michael-F-Bryan"]
|
||||
|
||||
[preprocessor.foo]
|
||||
# The command can also be specified manually
|
||||
command = "python3 /path/to/foo.py"
|
||||
# Only run the `foo` preprocessor for the HTML and EPUB renderer
|
||||
renderer = ["html", "epub"]
|
||||
```
|
||||
|
||||
Once the preprocessor has been defined and the build process starts, mdBook executes the command defined in the `preprocessor.foo.command` key twice.
|
||||
The first time it runs the preprocessor to determine if it supports the given renderer.
|
||||
mdBook passes two arguments to the process: the first argument is the string `supports` and the second argument is the renderer name.
|
||||
|
|
|
|||
|
|
@ -62,6 +62,11 @@ language = "en"
|
|||
Options for the Rust language, relevant to running tests and playground
|
||||
integration.
|
||||
|
||||
```toml
|
||||
[rust]
|
||||
edition = "2015" # the default edition for code blocks
|
||||
```
|
||||
|
||||
- **edition**: Rust edition to use by default for the code snippets. Default
|
||||
is "2015". Individual code blocks can be controlled with the `edition2015`,
|
||||
`edition2018` or `edition2021` annotations, such as:
|
||||
|
|
@ -77,8 +82,16 @@ integration.
|
|||
|
||||
This controls the build process of your book.
|
||||
|
||||
```toml
|
||||
[build]
|
||||
build-dir = "book" # the directory where the output is placed
|
||||
create-missing = true # whether or not to create missing pages
|
||||
use-default-preprocessors = true # use the default preprocessors
|
||||
```
|
||||
|
||||
- **build-dir:** The directory to put the rendered book in. By default this is
|
||||
`book/` in the book's root directory.
|
||||
This can overridden with the `--dest-dir` CLI option.
|
||||
- **create-missing:** By default, any missing files specified in `SUMMARY.md`
|
||||
will be created when the book is built (i.e. `create-missing = true`). If this
|
||||
is `false` then the build process will instead exit with an error if any files
|
||||
|
|
|
|||
|
|
@ -1,51 +1,58 @@
|
|||
# Configuring Preprocessors
|
||||
|
||||
The following preprocessors are available and included by default:
|
||||
Preprocessors are extensions that can modify the raw Markdown source before it gets sent to the renderer.
|
||||
|
||||
- `links`: Expand the `{{ #playground }}`, `{{ #include }}`, and `{{ #rustdoc_include }}` handlebars
|
||||
The following preprocessors are built-in and included by default:
|
||||
|
||||
- `links`: Expands the `{{ #playground }}`, `{{ #include }}`, and `{{ #rustdoc_include }}` handlebars
|
||||
helpers in a chapter to include the contents of a file.
|
||||
See [Including files] for more.
|
||||
- `index`: Convert all chapter files named `README.md` into `index.md`. That is
|
||||
to say, all `README.md` would be rendered to an index file `index.html` in the
|
||||
rendered book.
|
||||
|
||||
The built-in preprocessors can be disabled with the [`build.use-default-preprocessors`] config option.
|
||||
|
||||
**book.toml**
|
||||
```toml
|
||||
[build]
|
||||
build-dir = "build"
|
||||
create-missing = false
|
||||
The community has developed several preprocessors.
|
||||
See the [Third Party Plugins] wiki page for a list of available preprocessors.
|
||||
|
||||
[preprocessor.links]
|
||||
For information on how to create a new preprocessor, see the [Preprocessors for Developers] chapter.
|
||||
|
||||
[preprocessor.index]
|
||||
```
|
||||
[Including files]: ../mdbook.md#including-files
|
||||
[`build.use-default-preprocessors`]: general.md#build-options
|
||||
[Third Party Plugins]: https://github.com/rust-lang/mdBook/wiki/Third-party-plugins
|
||||
[Preprocessors for Developers]: ../../for_developers/preprocessors.md
|
||||
|
||||
### Custom Preprocessor Configuration
|
||||
## Custom Preprocessor Configuration
|
||||
|
||||
Like renderers, preprocessor will need to be given its own table (e.g.
|
||||
`[preprocessor.mathjax]`). In the section, you may then pass extra
|
||||
configuration to the preprocessor by adding key-value pairs to the table.
|
||||
|
||||
For example
|
||||
Preprocessors can be added by including a `preprocessor` table in `book.toml` with the name of the preprocessor.
|
||||
For example, if you have a preprocessor called `mdbook-example`, then you can include it with:
|
||||
|
||||
```toml
|
||||
[preprocessor.links]
|
||||
# set the renderers this preprocessor will run for
|
||||
renderers = ["html"]
|
||||
some_extra_feature = true
|
||||
[preprocessor.example]
|
||||
```
|
||||
|
||||
#### Locking a Preprocessor dependency to a renderer
|
||||
With this table, mdBook will execute the `mdbook-example` preprocessor.
|
||||
|
||||
This table can include additional key-value pairs that are specific to the preprocessor.
|
||||
For example, if our example prepocessor needed some extra configuration options:
|
||||
|
||||
```toml
|
||||
[preprocessor.example]
|
||||
some-extra-feature = true
|
||||
```
|
||||
|
||||
## Locking a Preprocessor dependency to a renderer
|
||||
|
||||
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
|
||||
[preprocessor.example]
|
||||
renderers = ["html"] # example preprocessor only runs 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,
|
||||
`mdbook` will try to invoke the `mdbook-foo` executable. If you want to use a
|
||||
|
|
@ -57,7 +64,7 @@ be overridden by adding a `command` field.
|
|||
command = "python random.py"
|
||||
```
|
||||
|
||||
### Require A Certain Order
|
||||
## Require A Certain Order
|
||||
|
||||
The order in which preprocessors are run can be controlled with the `before` and `after` fields.
|
||||
For example, suppose you want your `linenos` preprocessor to process lines that may have been `{{#include}}`d; then you want it to run after the built-in `links` preprocessor, which you can require using either the `before` or `after` field:
|
||||
|
|
|
|||
|
|
@ -1,9 +1,115 @@
|
|||
# Configuring Renderers
|
||||
|
||||
### HTML renderer options
|
||||
Renderers (also called "backends") are responsible for creating the output of the book.
|
||||
|
||||
The HTML renderer has a couple of options as well. All the options for the
|
||||
renderer need to be specified under the TOML table `[output.html]`.
|
||||
The following backends are built-in:
|
||||
|
||||
* [`html`](#html-renderer-options) — This renders the book to HTML.
|
||||
This is enabled by default if no other `[output]` tables are defined in `book.toml`.
|
||||
* [`markdown`](#markdown-renderer) — This outputs the book as markdown after running the preprocessors.
|
||||
This is useful for debugging preprocessors.
|
||||
|
||||
The community has developed several backends.
|
||||
See the [Third Party Plugins] wiki page for a list of available backends.
|
||||
|
||||
For information on how to create a new backend, see the [Backends for Developers] chapter.
|
||||
|
||||
[Third Party Plugins]: https://github.com/rust-lang/mdBook/wiki/Third-party-plugins
|
||||
[Backends for Developers]: ../../for_developers/backends.md
|
||||
|
||||
## Output tables
|
||||
|
||||
Backends can be added by including a `output` table in `book.toml` with the name of the backend.
|
||||
For example, if you have a backend called `mdbook-wordcount`, then you can include it with:
|
||||
|
||||
```toml
|
||||
[output.wordcount]
|
||||
```
|
||||
|
||||
With this table, mdBook will execute the `mdbook-wordcount` backend.
|
||||
|
||||
This table can include additional key-value pairs that are specific to the backend.
|
||||
For example, if our example backend needed some extra configuration options:
|
||||
|
||||
```toml
|
||||
[output.wordcount]
|
||||
ignores = ["Example Chapter"]
|
||||
```
|
||||
|
||||
If you define any `[output]` tables, then the `html` backend is not enabled by default.
|
||||
If you want to keep the `html` backend running, then just include it in the `book.toml` file.
|
||||
For example:
|
||||
|
||||
```toml
|
||||
[book]
|
||||
title = "My Awesome Book"
|
||||
|
||||
[output.wordcount]
|
||||
|
||||
[output.html]
|
||||
```
|
||||
|
||||
If more than one `output` table is included, this changes the behavior for the layout of the output directory.
|
||||
If there is only one backend, then it places its output directly in the `book` directory (see [`build.build-dir`] to override this location).
|
||||
If there is more than one backend, then each backend is placed in a separate directory underneath `book`.
|
||||
For example, the above would have directories `book/html` and `book/wordcount`.
|
||||
|
||||
[`build.build-dir`]: general.md#build-options
|
||||
|
||||
### Custom backend commands
|
||||
|
||||
By default when you add an `[output.foo]` table to your `book.toml` file,
|
||||
`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.
|
||||
|
||||
```toml
|
||||
[output.random]
|
||||
command = "python random.py"
|
||||
```
|
||||
|
||||
### Optional backends
|
||||
|
||||
If you enable a backend that isn't installed, the default behavior is to throw an error.
|
||||
This behavior can be changed by marking the backend as optional:
|
||||
|
||||
```toml
|
||||
[output.wordcount]
|
||||
optional = true
|
||||
```
|
||||
|
||||
This demotes the error to a warning.
|
||||
|
||||
|
||||
## HTML renderer options
|
||||
|
||||
The HTML renderer has a variety of options detailed below.
|
||||
They should be specified in the `[output.html]` table of the `book.toml` file.
|
||||
|
||||
```toml
|
||||
# Example book.toml file with all output options.
|
||||
[book]
|
||||
title = "Example book"
|
||||
authors = ["John Doe", "Jane Doe"]
|
||||
description = "The example book covers examples."
|
||||
|
||||
[output.html]
|
||||
theme = "my-theme"
|
||||
default-theme = "light"
|
||||
preferred-dark-theme = "navy"
|
||||
curly-quotes = true
|
||||
mathjax-support = false
|
||||
copy-fonts = true
|
||||
additional-css = ["custom.css", "custom2.css"]
|
||||
additional-js = ["custom.js"]
|
||||
no-section-label = false
|
||||
git-repository-url = "https://github.com/rust-lang/mdBook"
|
||||
git-repository-icon = "fa-github"
|
||||
edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}"
|
||||
site-url = "/example-book/"
|
||||
cname = "myproject.rs"
|
||||
input-404 = "not-found.md"
|
||||
```
|
||||
|
||||
The following configuration options are available:
|
||||
|
||||
|
|
@ -30,34 +136,22 @@ The following configuration options are available:
|
|||
- **additional-js:** If you need to add some behaviour to your book without
|
||||
removing the current behaviour, you can specify a set of JavaScript files that
|
||||
will be loaded alongside the default one.
|
||||
- **print:** A subtable for configuration print settings. mdBook by default adds
|
||||
support for printing out the book as a single page. This is accessed using the
|
||||
print icon on the top right of the book.
|
||||
- **no-section-label:** mdBook by defaults adds section label in table of
|
||||
- **no-section-label:** mdBook by defaults adds numeric section labels in the table of
|
||||
contents column. For example, "1.", "2.1". Set this option to true to disable
|
||||
those labels. Defaults to `false`.
|
||||
- **fold:** A subtable for configuring sidebar section-folding behavior.
|
||||
- **playground:** A subtable for configuring various playground 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
|
||||
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
|
||||
repository link. Defaults to `fa-github`.
|
||||
repository link. Defaults to `fa-github` which looks like <i class="fa fa-github"></i>.
|
||||
If you are not using GitHub, another option to consider is `fa-code-fork` which looks like <i class="fa fa-code-fork"></i>.
|
||||
- **edit-url-template:** Edit url template, when provided shows a
|
||||
"Suggest an edit" button for directly jumping to editing the currently
|
||||
"Suggest an edit" button (which looks like <i class="fa fa-edit"></i>) for directly jumping to editing the currently
|
||||
viewed page. For e.g. GitHub projects set this to
|
||||
`https://github.com/<owner>/<repo>/edit/master/{path}` or for
|
||||
Bitbucket projects set it to
|
||||
`https://bitbucket.org/<owner>/<repo>/src/master/{path}?mode=edit`
|
||||
where {path} will be replaced with the full path of the file in the
|
||||
repository.
|
||||
- **redirect:** A subtable used for generating redirects when a page is moved.
|
||||
The table contains key-value pairs where the key is where the redirect file
|
||||
needs to be created, as an absolute path from the build directory, (e.g.
|
||||
`/appendices/bibliography.html`). The value can be any valid URI the
|
||||
browser should navigate to (e.g. `https://rust-lang.org/`,
|
||||
`/overview.html`, or `../bibliography.html`).
|
||||
- **input-404:** The name of the markdown file used for missing files.
|
||||
The corresponding output file will be the same, with the extension replaced with `html`.
|
||||
Defaults to `404.md`.
|
||||
|
|
@ -71,19 +165,47 @@ The following configuration options are available:
|
|||
|
||||
[custom domain]: https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site
|
||||
|
||||
Available configuration options for the `[output.html.print]` table:
|
||||
### `[output.html.print]`
|
||||
|
||||
The `[output.html.print]` table provides options for controlling the printable output.
|
||||
By default, mdBook will include an icon on the top right of the book (which looks like <i class="fa fa-print"></i>) that will print the book as a single page.
|
||||
|
||||
```toml
|
||||
[output.html.print]
|
||||
enable = true # include support for printable output
|
||||
```
|
||||
|
||||
- **enable:** Enable print support. When `false`, all print support will not be
|
||||
rendered. Defaults to `true`.
|
||||
|
||||
Available configuration options for the `[output.html.fold]` table:
|
||||
### `[output.html.fold]`
|
||||
|
||||
The `[output.html.fold]` table provides options for controlling folding of the chapter listing in the navigation sidebar.
|
||||
|
||||
```toml
|
||||
[output.html.fold]
|
||||
enable = false # whether or not to enable section folding
|
||||
level = 0 # the depth to start folding
|
||||
```
|
||||
|
||||
- **enable:** Enable section-folding. When off, all folds are open.
|
||||
Defaults to `false`.
|
||||
- **level:** The higher the more folded regions are open. When level is 0, all
|
||||
folds are closed. Defaults to `0`.
|
||||
|
||||
Available configuration options for the `[output.html.playground]` table:
|
||||
### `[output.html.playground]`
|
||||
|
||||
The `[output.html.playground]` table provides options for controlling Rust sample code blocks, and their integration with the [Rust Playground].
|
||||
|
||||
[Rust Playground]: https://play.rust-lang.org/
|
||||
|
||||
```toml
|
||||
[output.html.playground]
|
||||
editable = false # allows editing the source code
|
||||
copyable = true # include the copy button for copying code snippets
|
||||
copy-js = true # includes the JavaScript for the code editor
|
||||
line-numbers = false # displays line numbers for editable code
|
||||
```
|
||||
|
||||
- **editable:** Allow editing the source code. Defaults to `false`.
|
||||
- **copyable:** Display the copy button on code snippets. Defaults to `true`.
|
||||
|
|
@ -93,7 +215,26 @@ Available configuration options for the `[output.html.playground]` table:
|
|||
|
||||
[Ace]: https://ace.c9.io/
|
||||
|
||||
Available configuration options for the `[output.html.search]` table:
|
||||
### `[output.html.search]`
|
||||
|
||||
The `[output.html.search]` table provides options for controlling the built-in text [search].
|
||||
mdBook must be compiled with the `search` feature enabled (on by default).
|
||||
|
||||
[search]: ../../guide/reading.md#search
|
||||
|
||||
```toml
|
||||
[output.html.search]
|
||||
enable = true # enables the search feature
|
||||
limit-results = 30 # maximum number of search results
|
||||
teaser-word-count = 30 # number of words used for a search result teaser
|
||||
use-boolean-and = true # multiple search terms must all match
|
||||
boost-title = 2 # ranking boost factor for matches in headers
|
||||
boost-hierarchy = 1 # ranking boost factor for matches in page names
|
||||
boost-paragraph = 1 # ranking boost factor for matches in text
|
||||
expand = true # partial words will match longer terms
|
||||
heading-split-level = 3 # link results to heading levels
|
||||
copy-js = true # include Javascript code for search
|
||||
```
|
||||
|
||||
- **enable:** Enables the search feature. Defaults to `true`.
|
||||
- **limit-results:** The maximum number of search results. Defaults to `30`.
|
||||
|
|
@ -116,61 +257,24 @@ Available configuration options for the `[output.html.search]` table:
|
|||
- **copy-js:** Copy JavaScript files for the search implementation to the output
|
||||
directory. Defaults to `true`.
|
||||
|
||||
This shows all available HTML output options in the **book.toml**:
|
||||
### `[output.html.redirect]`
|
||||
|
||||
The `[output.html.redirect]` table provides a way to add redirects.
|
||||
This is useful when you move, rename, or remove a page to ensure that links to the old URL will go to the new location.
|
||||
|
||||
```toml
|
||||
[book]
|
||||
title = "Example book"
|
||||
authors = ["John Doe", "Jane Doe"]
|
||||
description = "The example book covers examples."
|
||||
|
||||
[output.html]
|
||||
theme = "my-theme"
|
||||
default-theme = "light"
|
||||
preferred-dark-theme = "navy"
|
||||
curly-quotes = true
|
||||
mathjax-support = false
|
||||
copy-fonts = true
|
||||
additional-css = ["custom.css", "custom2.css"]
|
||||
additional-js = ["custom.js"]
|
||||
no-section-label = false
|
||||
git-repository-url = "https://github.com/rust-lang/mdBook"
|
||||
git-repository-icon = "fa-github"
|
||||
edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}"
|
||||
site-url = "/example-book/"
|
||||
cname = "myproject.rs"
|
||||
input-404 = "not-found.md"
|
||||
|
||||
[output.html.print]
|
||||
enable = true
|
||||
|
||||
[output.html.fold]
|
||||
enable = false
|
||||
level = 0
|
||||
|
||||
[output.html.playground]
|
||||
editable = false
|
||||
copy-js = true
|
||||
line-numbers = false
|
||||
|
||||
[output.html.search]
|
||||
enable = true
|
||||
limit-results = 30
|
||||
teaser-word-count = 30
|
||||
use-boolean-and = true
|
||||
boost-title = 2
|
||||
boost-hierarchy = 1
|
||||
boost-paragraph = 1
|
||||
expand = true
|
||||
heading-split-level = 3
|
||||
copy-js = true
|
||||
|
||||
[output.html.redirect]
|
||||
"/appendices/bibliography.html" = "https://rustc-dev-guide.rust-lang.org/appendix/bibliography.html"
|
||||
"/other-installation-methods.html" = "../infra/other-installation-methods.html"
|
||||
```
|
||||
|
||||
### Markdown Renderer
|
||||
The table contains key-value pairs where the key is where the redirect file needs to be created, as an absolute path from the build directory, (e.g. `/appendices/bibliography.html`).
|
||||
The value can be any valid URI the browser should navigate to (e.g. `https://rust-lang.org/`, `/overview.html`, or `../bibliography.html`).
|
||||
|
||||
This will generate an HTML page which will automatically redirect to the given location.
|
||||
Note that the source location does not support `#` anchor redirects.
|
||||
|
||||
## Markdown Renderer
|
||||
|
||||
The Markdown renderer will run preprocessors and then output the resulting
|
||||
Markdown. This is mostly useful for debugging preprocessors, especially in
|
||||
|
|
@ -189,20 +293,3 @@ only whether it is enabled or disabled.
|
|||
|
||||
See [the preprocessors documentation](preprocessors.md) for how to
|
||||
specify which preprocessors should run before the Markdown renderer.
|
||||
|
||||
### Custom Renderers
|
||||
|
||||
A custom renderer can be enabled by adding a `[output.foo]` table to your
|
||||
`book.toml`. Similar to [preprocessors](preprocessors.md) this will
|
||||
instruct `mdbook` to pass a representation of the book to `mdbook-foo` for
|
||||
rendering. See the [alternative backends] chapter for more detail.
|
||||
|
||||
The custom renderer has access to all the fields within its table (i.e.
|
||||
anything under `[output.foo]`). mdBook checks for two common fields:
|
||||
|
||||
- **command:** The command to execute for this custom renderer. Defaults to
|
||||
the name of the renderer with the `mdbook-` prefix (such as `mdbook-foo`).
|
||||
- **optional:** If `true`, then the command will be ignored if it is not
|
||||
installed, otherwise mdBook will fail with an error. Defaults to `false`.
|
||||
|
||||
[alternative backends]: ../../for_developers/backends.md
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# Markdown
|
||||
|
||||
mdBook's [parser](https://github.com/raphlinus/pulldown-cmark) adheres to the [CommonMark](https://commonmark.org/)
|
||||
specification. You can take a quick [tutorial](https://commonmark.org/help/tutorial/),
|
||||
mdBook's [parser](https://github.com/raphlinus/pulldown-cmark) adheres to the [CommonMark](https://commonmark.org/) specification with some extensions described below.
|
||||
You can take a quick [tutorial](https://commonmark.org/help/tutorial/),
|
||||
or [try out](https://spec.commonmark.org/dingus/) CommonMark in real time. A complete Markdown overview is out of scope for
|
||||
this documentation, but below is a high level overview of some of the basics. For a more in-depth experience, check out the
|
||||
[Markdown Guide](https://www.markdownguide.org).
|
||||
|
|
@ -84,6 +84,20 @@ Read about [mdBook](mdBook.md).
|
|||
|
||||
A bare url: <https://www.rust-lang.org>.
|
||||
|
||||
----
|
||||
|
||||
Relative links that end with `.md` will be converted to the `.html` extension.
|
||||
It is recommended to use `.md` links when possible.
|
||||
This is useful when viewing the Markdown file outside of mdBook, for example on GitHub or GitLab which render Markdown automatically.
|
||||
|
||||
Links to `README.md` will be converted to `index.html`.
|
||||
This is done since some services like GitHub render README files automatically, but web servers typically expect the root file to be called `index.html`.
|
||||
|
||||
You can link to individual headings with `#` fragments.
|
||||
For example, `mdbook.md#text-and-paragraphs` would link to the [Text and Paragraphs](#text-and-paragraphs) section above.
|
||||
The ID is created by transforming the heading such as converting to lowercase and replacing spaces with dashes.
|
||||
You can click on any heading and look at the URL in your browser to see what the fragment looks like.
|
||||
|
||||
## Images
|
||||
|
||||
Including images is simply a matter of including a link to them, much like in the _Links_ section above. The following markdown
|
||||
|
|
@ -103,5 +117,106 @@ Which, of course displays the image like so:
|
|||
|
||||
|
||||
|
||||
## Extensions
|
||||
|
||||
See the [Markdown Guide Basic Syntax](https://www.markdownguide.org/basic-syntax/) document for more.
|
||||
mdBook has several extensions beyond the standard CommonMark specification.
|
||||
|
||||
### Strikethrough
|
||||
|
||||
Text may be rendered with a horizontal line through the center by wrapping the
|
||||
text with two tilde characters on each side:
|
||||
|
||||
```text
|
||||
An example of ~~strikethrough text~~.
|
||||
```
|
||||
|
||||
This example will render as:
|
||||
|
||||
> An example of ~~strikethrough text~~.
|
||||
|
||||
This follows the [GitHub Strikethrough extension][strikethrough].
|
||||
|
||||
### Footnotes
|
||||
|
||||
A footnote generates a small numbered link in the text which when clicked
|
||||
takes the reader to the footnote text at the bottom of the item. The footnote
|
||||
label is written similarly to a link reference with a caret at the front. The
|
||||
footnote text is written like a link reference definition, with the text
|
||||
following the label. Example:
|
||||
|
||||
```text
|
||||
This is an example of a footnote[^note].
|
||||
|
||||
[^note]: This text is the contents of the footnote, which will be rendered
|
||||
towards the bottom.
|
||||
```
|
||||
|
||||
This example will render as:
|
||||
|
||||
> This is an example of a footnote[^note].
|
||||
>
|
||||
> [^note]: This text is the contents of the footnote, which will be rendered
|
||||
> towards the bottom.
|
||||
|
||||
The footnotes are automatically numbered based on the order the footnotes are
|
||||
written.
|
||||
|
||||
### Tables
|
||||
|
||||
Tables can be written using pipes and dashes to draw the rows and columns of
|
||||
the table. These will be translated to HTML table matching the shape. Example:
|
||||
|
||||
```text
|
||||
| Header1 | Header2 |
|
||||
|---------|---------|
|
||||
| abc | def |
|
||||
```
|
||||
|
||||
This example will render similarly to this:
|
||||
|
||||
| Header1 | Header2 |
|
||||
|---------|---------|
|
||||
| abc | def |
|
||||
|
||||
See the specification for the [GitHub Tables extension][tables] for more
|
||||
details on the exact syntax supported.
|
||||
|
||||
### Task lists
|
||||
|
||||
Task lists can be used as a checklist of items that have been completed.
|
||||
Example:
|
||||
|
||||
```md
|
||||
- [x] Complete task
|
||||
- [ ] Incomplete task
|
||||
```
|
||||
|
||||
This will render as:
|
||||
|
||||
> - [x] Complete task
|
||||
> - [ ] Incomplete task
|
||||
|
||||
See the specification for the [task list extension] for more details.
|
||||
|
||||
### Smart punctuation
|
||||
|
||||
Some ASCII punctuation sequences will be automatically turned into fancy Unicode
|
||||
characters:
|
||||
|
||||
| ASCII sequence | Unicode |
|
||||
|----------------|---------|
|
||||
| `--` | – |
|
||||
| `---` | — |
|
||||
| `...` | … |
|
||||
| `"` | “ or ”, depending on context |
|
||||
| `'` | ‘ or ’, depending on context |
|
||||
|
||||
So, no need to manually enter those Unicode characters!
|
||||
|
||||
This feature is disabled by default.
|
||||
To enable it, see the [`output.html.curly-quotes`] config option.
|
||||
|
||||
[strikethrough]: https://github.github.com/gfm/#strikethrough-extension-
|
||||
[tables]: https://github.github.com/gfm/#tables-extension-
|
||||
[task list extension]: https://github.github.com/gfm/#task-list-items-extension-
|
||||
[`output.html.curly-quotes`]: configuration/renderers.md#html-renderer-options
|
||||
|
|
|
|||
|
|
@ -4,6 +4,7 @@
|
|||
|
||||
There is a feature in mdBook that lets you hide code lines by prepending them
|
||||
with a `#` [like you would with Rustdoc][rustdoc-hide].
|
||||
This currently only works with Rust language code blocks.
|
||||
|
||||
[rustdoc-hide]: https://doc.rust-lang.org/stable/rustdoc/documentation-tests.html#hiding-portions-of-the-example
|
||||
|
||||
|
|
@ -27,6 +28,60 @@ Will render as
|
|||
# }
|
||||
```
|
||||
|
||||
The code block has an eyeball icon (<i class="fa fa-eye"></i>) which will toggle the visibility of the hidden lines.
|
||||
|
||||
## Rust Playground
|
||||
|
||||
Rust language code blocks will automatically get a play button (<i class="fa fa-play"></i>) which will execute the code and display the output just below the code block.
|
||||
This works by sending the code to the [Rust Playground].
|
||||
|
||||
```rust
|
||||
println!("Hello, World!");
|
||||
```
|
||||
|
||||
If there is no `main` function, then the code is automatically wrapped inside one.
|
||||
|
||||
If you wish to disable the play button, you can include the `noplayground` option on the code block like this:
|
||||
|
||||
~~~markdown
|
||||
```rust,noplayground
|
||||
let mut name = String::new();
|
||||
std::io::stdin().read_line(&mut name).expect("failed to read line");
|
||||
println!("Hello {}!", name);
|
||||
```
|
||||
~~~
|
||||
|
||||
## Rust code block attributes
|
||||
|
||||
Additional attributes can be included in Rust code blocks with comma, space, or tab-separated terms just after the language term. For example:
|
||||
|
||||
~~~markdown
|
||||
```rust,ignore
|
||||
# This example won't be tested.
|
||||
panic!("oops!");
|
||||
```
|
||||
~~~
|
||||
|
||||
These are particularly important when using [`mdbook test`] to test Rust examples.
|
||||
These use the same attributes as [rustdoc attributes], with a few additions:
|
||||
|
||||
* `editable` — Enables the [editor].
|
||||
* `noplayground` — Removes the play button, but will still be tested.
|
||||
* `mdbook-runnable` — Forces the play button to be displayed.
|
||||
This is intended to be combined with the `ignore` attribute for examples that should not be tested, but you want to allow the reader to run.
|
||||
* `ignore` — Will not be tested and no play button is shown, but it is still highlighted as Rust syntax.
|
||||
* `should_panic` — When executed, it should produce a panic.
|
||||
* `no_run` — The code is compiled when tested, but it is not run.
|
||||
The play button is also not shown.
|
||||
* `compile_fail` — The code should fail to compile.
|
||||
* `edition2015`, `edition2018`, `edition2021` — Forces the use of a specific Rust edition.
|
||||
See [`rust.edition`] to set this globally.
|
||||
|
||||
[`mdbook test`]: ../cli/test.md
|
||||
[rustdoc attributes]: https://doc.rust-lang.org/rustdoc/documentation-tests.html#attributes
|
||||
[editor]: theme/editor.md
|
||||
[`rust.edition`]: configuration/general.md#rust-options
|
||||
|
||||
## Including files
|
||||
|
||||
With the following syntax, you can include files into your book:
|
||||
|
|
@ -191,6 +246,17 @@ Here is what a rendered code snippet looks like:
|
|||
|
||||
{{#playground example.rs}}
|
||||
|
||||
Any additional values passed after the filename will be included as attributes of the code block.
|
||||
For example `\{{#playground example.rs editable}}` will create the code block like the following:
|
||||
|
||||
~~~markdown
|
||||
```rust,editable
|
||||
# Contents of example.rs here.
|
||||
```
|
||||
~~~
|
||||
|
||||
And the `editable` attribute will enable the [editor] as described at [Rust code block attributes](#rust-code-block-attributes).
|
||||
|
||||
[Rust Playground]: https://play.rust-lang.org/
|
||||
|
||||
## Controlling page \<title\>
|
||||
|
|
|
|||
|
|
@ -38,6 +38,10 @@ template and only add / modify what you need. You can copy the default theme
|
|||
into your source directory automatically by using `mdbook init --theme` and just
|
||||
remove the files you don't want to override.
|
||||
|
||||
`mdbook init --theme` will not create every file listed above.
|
||||
Some files, such as `head.hbs`, do not have built-in equivalents.
|
||||
Just create the file if you need it.
|
||||
|
||||
If you completely replace all built-in themes, be sure to also set
|
||||
[`output.html.preferred-dark-theme`] in the config, which defaults to the
|
||||
built-in `navy` theme.
|
||||
|
|
|
|||
|
|
@ -12,12 +12,14 @@ editable = true
|
|||
To make a specific block available for editing, the attribute `editable` needs
|
||||
to be added to it:
|
||||
|
||||
<pre><code class="language-markdown">```rust,editable
|
||||
~~~markdown
|
||||
```rust,editable
|
||||
fn main() {
|
||||
let number = 5;
|
||||
print!("{}", number);
|
||||
}
|
||||
```</code></pre>
|
||||
```
|
||||
~~~
|
||||
|
||||
The above will result in this editable playground:
|
||||
|
||||
|
|
|
|||
7
guide/src/guide/README.md
Normal file
7
guide/src/guide/README.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
# User Guide
|
||||
|
||||
This user guide provides an introduction to basic concepts of using mdBook.
|
||||
|
||||
- [Installation](installation.md)
|
||||
- [Reading Books](reading.md)
|
||||
- [Creating a Book](creating.md)
|
||||
109
guide/src/guide/creating.md
Normal file
109
guide/src/guide/creating.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
# Creating a Book
|
||||
|
||||
Once you have the `mdbook` CLI tool installed, you can use it to create and render a book.
|
||||
|
||||
## Initializing a book
|
||||
|
||||
The `mdbook init` command will create a new directory containing an empty book for you to get started.
|
||||
Give it the name of the directory that you want to create:
|
||||
|
||||
```sh
|
||||
mdbook init my-first-book
|
||||
```
|
||||
|
||||
It will ask a few questions before generating the book.
|
||||
After answering the questions, you can change the current directory into the new book:
|
||||
|
||||
```sh
|
||||
cd my-first-book
|
||||
```
|
||||
|
||||
There are several ways to render a book, but one of the easiest methods is to use the `serve` command, which will build your book and start a local webserver:
|
||||
|
||||
```sh
|
||||
mdbook serve --open
|
||||
```
|
||||
|
||||
The `--open` option will open your default web browser to view your new book.
|
||||
You can leave the server running even while you edit the content of the book, and `mdbook` will automatically rebuild the output *and* automatically refresh your web browser.
|
||||
|
||||
Check out the [CLI Guide](../cli/index.html) for more information about other `mdbook` commands and CLI options.
|
||||
|
||||
## Anatomy of a book
|
||||
|
||||
A book is built from several files which define the settings and layout of the book.
|
||||
|
||||
### `book.toml`
|
||||
|
||||
In the root of your book, there is a `book.toml` file which contains settings for describing how to build your book.
|
||||
This is written in the [TOML markup language](https://toml.io/).
|
||||
The default settings are usually good enough to get you started.
|
||||
When you are interested in exploring more features and options that mdBook provides, check out the [Configuration chapter](../format/configuration/index.html) for more details.
|
||||
|
||||
A very basic `book.toml` can be as simple as this:
|
||||
|
||||
```toml
|
||||
[book]
|
||||
title = "My First Book"
|
||||
```
|
||||
|
||||
### `SUMMARY.md`
|
||||
|
||||
The next major part of a book is the summary file located at `src/SUMMARY.md`.
|
||||
This file contains a list of all the chapters in the book.
|
||||
Before a chapter can be viewed, it must be added to this list.
|
||||
|
||||
Here's a basic summary file with a few chapters:
|
||||
|
||||
```md
|
||||
# Summary
|
||||
|
||||
[Introduction](README.md)
|
||||
|
||||
- [My First Chapter](my-first-chapter.md)
|
||||
- [Nested example](nested/README.md)
|
||||
- [Sub-chapter](nested/sub-chapter.md)
|
||||
```
|
||||
|
||||
Try opening up `src/SUMMARY.md` in your editor and adding a few chapters.
|
||||
If any of the chapter files do not exist, `mdbook` will automatically create them for you.
|
||||
|
||||
For more details on other formatting options for the summary file, check out the [Summary chapter](../format/summary.md).
|
||||
|
||||
### Source files
|
||||
|
||||
The content of your book is all contained in the `src` directory.
|
||||
Each chapter is a separate Markdown file.
|
||||
Typically, each chapter starts with a level 1 heading with the title of the chapter.
|
||||
|
||||
```md
|
||||
# My First Chapter
|
||||
|
||||
Fill out your content here.
|
||||
```
|
||||
|
||||
The precise layout of the files is up to you.
|
||||
The organization of the files will correspond to the HTML files generated, so keep in mind that the file layout is part of the URL of each chapter.
|
||||
|
||||
While the `mdbook serve` command is running, you can open any of the chapter files and start editing them.
|
||||
Each time you save the file, `mdbook` will rebuild the book and refresh your web browser.
|
||||
|
||||
Check out the [Markdown chapter](../format/markdown.md) for more information on formatting the content of your chapters.
|
||||
|
||||
All other files in the `src` directory will be included in the output.
|
||||
So if you have images or other static files, just include them somewhere in the `src` directory.
|
||||
|
||||
## Publishing a book
|
||||
|
||||
Once you've written your book, you may want to host it somewhere for others to view.
|
||||
The first step is to build the output of the book.
|
||||
This can be done with the `mbdook build` command in the same directory where the `book.toml` file is located:
|
||||
|
||||
```sh
|
||||
mdbook build
|
||||
```
|
||||
|
||||
This will generate a directory named `book` which contains the HTML content of your book.
|
||||
You can then place this directory on any web server to host it.
|
||||
|
||||
For more information about publishing and deploying, check out the [Continuous Integration chapter](../continuous-integration.md) for more.
|
||||
50
guide/src/guide/installation.md
Normal file
50
guide/src/guide/installation.md
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
# Installation
|
||||
|
||||
There are multiple ways to install the mdBook CLI tool.
|
||||
Choose any one of the methods below that best suit your needs.
|
||||
If you are installing mdBook for automatic deployment, check out the [continuous integration] chapter for more examples on how to install.
|
||||
|
||||
[continuous integration]: ../continuous-integration.md
|
||||
|
||||
## Pre-compiled binaries
|
||||
|
||||
Executable binaries are available for download on the [GitHub Releases page][releases].
|
||||
Download the binary for your platform (Windows, macOS, or Linux) and extract the archive.
|
||||
The archive contains an `mdbook` executable which you can run to build your books.
|
||||
|
||||
To make it easier to run, put the path to the binary into your `PATH`.
|
||||
|
||||
[releases]: https://github.com/rust-lang/mdBook/releases
|
||||
|
||||
## Build from source using Rust
|
||||
|
||||
To build the `mdbook` executable from source, you will first need to install Rust and Cargo.
|
||||
Follow the instructions on the [Rust installation page].
|
||||
mdBook currently requires at least Rust version 1.46.
|
||||
|
||||
Once you have installed Rust, the following command can be used to build and install mdBook:
|
||||
|
||||
```sh
|
||||
cargo install mdbook
|
||||
```
|
||||
|
||||
This will automatically download mdBook from [crates.io], build it, and install it in Cargo's global binary directory (`~/.cargo/bin/` by default).
|
||||
|
||||
[Rust installation page]: https://www.rust-lang.org/tools/install
|
||||
[crates.io]: https://crates.io/
|
||||
|
||||
### Installing the latest master version
|
||||
|
||||
The version published to crates.io will ever so slightly be behind the version hosted on GitHub.
|
||||
If you need the latest version you can build the git version of mdBook yourself.
|
||||
Cargo makes this ***super easy***!
|
||||
|
||||
```sh
|
||||
cargo install --git https://github.com/rust-lang/mdBook.git mdbook
|
||||
```
|
||||
|
||||
Again, make sure to add the Cargo bin directory to your `PATH`.
|
||||
|
||||
If you are interested in making modifications to mdBook itself, check out the [Contributing Guide] for more information.
|
||||
|
||||
[Contributing Guide]: https://github.com/rust-lang/mdBook/blob/master/CONTRIBUTING.md
|
||||
74
guide/src/guide/reading.md
Normal file
74
guide/src/guide/reading.md
Normal file
|
|
@ -0,0 +1,74 @@
|
|||
# Reading Books
|
||||
|
||||
This chapter gives an introduction on how to interact with a book produced by mdBook.
|
||||
This assumes you are reading an HTML book.
|
||||
The options and formatting will be different for other output formats such as PDF.
|
||||
|
||||
A book is organized into *chapters*.
|
||||
Each chapter is a separate page.
|
||||
Chapters can be nested into a hierarchy of sub-chapters.
|
||||
Typically, each chapter will be organized into a series of *headings* to subdivide a chapter.
|
||||
|
||||
## Navigation
|
||||
|
||||
There are several methods for navigating through the chapters of a book.
|
||||
|
||||
The **sidebar** on the left provides a list of all chapters.
|
||||
Clicking on any of the chapter titles will load that page.
|
||||
|
||||
The sidebar may not automatically appear if the window is too narrow, particularly on mobile displays.
|
||||
In that situation, the menu icon (three horizontal bars) at the top-left of the page can be pressed to open and close the sidebar.
|
||||
|
||||
The **arrow buttons** at the bottom of the page can be used to navigate to the previous or the next chapter.
|
||||
|
||||
The **left and right arrow keys** on the keyboard can be used to navigate to the previous or the next chapter.
|
||||
|
||||
## Top menu bar
|
||||
|
||||
The menu bar at the top of the page provides some icons for interacting with the book.
|
||||
The icons displayed will depend on the settings of how the book was generated.
|
||||
|
||||
| Icon | Description |
|
||||
|------|-------------|
|
||||
| <i class="fa fa-bars"></i> | Opens and closes the chapter listing sidebar. |
|
||||
| <i class="fa fa-paint-brush"></i> | Opens a picker to choose a different color theme. |
|
||||
| <i class="fa fa-search"></i> | Opens a search bar for searching within the book. |
|
||||
| <i class="fa fa-print"></i> | Instructs the web browser to print the entire book. |
|
||||
| <i class="fa fa-github"></i> | Opens a link to the website that hosts the source code of the book. |
|
||||
| <i class="fa fa-edit"></i> | Opens a page to directly edit the source of the page you are currently reading. |
|
||||
|
||||
Tapping the menu bar will scroll the page to the top.
|
||||
|
||||
## Search
|
||||
|
||||
Each book has a built-in search system.
|
||||
Pressing the search icon (<i class="fa fa-search"></i>) in the menu bar, or pressing the `S` key on the keyboard will open an input box for entering search terms.
|
||||
Typing some terms will show matching chapters and sections in real time.
|
||||
|
||||
Clicking any of the results will jump to that section.
|
||||
The up and down arrow keys can be used to navigate the results, and enter will open the highlighted section.
|
||||
|
||||
After loading a search result, the matching search terms will be highlighted in the text.
|
||||
Clicking a highlighted word or pressing the `Esc` key will remove the highlighting.
|
||||
|
||||
## Code blocks
|
||||
|
||||
mdBook books are often used for programming projects, and thus support highlighting code blocks and samples.
|
||||
Code blocks may contain several different icons for interacting with them:
|
||||
|
||||
| Icon | Description |
|
||||
|------|-------------|
|
||||
| <i class="fa fa-copy"></i> | Copies the code block into your local clipboard, to allow pasting into another application. |
|
||||
| <i class="fa fa-play"></i> | For Rust code examples, this will execute the sample code and display the compiler output just below the example (see [playground]). |
|
||||
| <i class="fa fa-eye"></i> | For Rust code examples, this will toggle visibility of "hidden" lines. Sometimes, larger examples will hide lines which are not particularly relevant to what is being illustrated (see [hiding code lines]). |
|
||||
| <i class="fa fa-history"></i> | For [editable code examples][editor], this will undo any changes you have made. |
|
||||
|
||||
Here's an example:
|
||||
|
||||
```rust
|
||||
println!("Hello, World!");
|
||||
```
|
||||
|
||||
[editor]: ../format/theme/editor.md
|
||||
[playground]: ../format/mdbook.md#rust-playground
|
||||
[hiding code lines]: ../format/mdbook.md#hiding-code-lines
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
# Introduction
|
||||
|
||||
A frontmatter chapter.
|
||||
Loading…
Reference in a new issue