mirror of
https://github.com/rust-lang/mdBook
synced 2024-12-13 22:32:35 +00:00
Update documentation for commands
This commit is contained in:
Matt Ickstadt
parent
b8f8e76899
commit
a776aa9783
8 changed files with 122 additions and 60 deletions
|
|
@ -14,8 +14,8 @@ convenience. Large books will therefore remain structured when rendered.
|
|||
|
||||
#### Specify a directory
|
||||
|
||||
Like `init`, the `build` command can take a directory as an argument to use
|
||||
instead of the current working directory.
|
||||
The `build` command can take a directory as an argument to use as the book's
|
||||
root instead of the current working directory.
|
||||
|
||||
```bash
|
||||
mdbook build path/to/book
|
||||
|
|
@ -23,13 +23,16 @@ mdbook build path/to/book
|
|||
|
||||
#### --open
|
||||
|
||||
When you use the `--open` (`-o`) option, mdbook will open the rendered book in
|
||||
When you use the `--open` (`-o`) flag, mdbook will open the rendered book in
|
||||
your default web browser after building it.
|
||||
|
||||
#### --dest-dir
|
||||
|
||||
The `--dest-dir` (`-d`) option allows you to change the output directory for your book.
|
||||
The `--dest-dir` (`-d`) option allows you to change the output directory for
|
||||
the book. If not specified it will default to the value of the
|
||||
`build.build-dir` key in `book.toml`, or to `./book` relative to the book's
|
||||
root directory.
|
||||
|
||||
-------------------
|
||||
|
||||
***note:*** *make sure to run the build command in the root directory and not in the source directory*
|
||||
***Note:*** *Make sure to run the build command in the root directory and not in the source directory*
|
||||
|
|
|
|||
|
|
@ -7,12 +7,21 @@ artifacts.
|
|||
mdbook clean
|
||||
```
|
||||
|
||||
It will try to delete the built book. If a path is provided, it will be used.
|
||||
|
||||
#### Specify a directory
|
||||
|
||||
Like `init`, the `clean` command can take a directory as an argument to use
|
||||
instead of the normal build directory.
|
||||
The `clean` command can take a directory as an argument to use as the book's
|
||||
root instead of the current working directory.
|
||||
|
||||
```bash
|
||||
mdbook clean path/to/book
|
||||
```
|
||||
|
||||
#### --dest-dir
|
||||
|
||||
The `--dest-dir` (`-d`) option allows you to override the book's output
|
||||
directory, which will be deleted by this command. If not specified it
|
||||
will default to the value of the `build.build-dir` key in `book.toml`, or to
|
||||
`./book` relative to the book's root directory.
|
||||
|
||||
```bash
|
||||
mdbook clean --dest-dir=path/to/book
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# The init command
|
||||
There is some minimal boilerplate that is the same for every new book. It's for this purpose that mdBook includes an `init` command.
|
||||
|
||||
There is some minimal boilerplate that is the same for every new book. It's for this purpose
|
||||
that mdBook includes an `init` command.
|
||||
|
||||
The `init` command is used like this:
|
||||
|
||||
|
|
@ -22,23 +24,27 @@ configuration files, etc.
|
|||
- The `book` directory is where your book is rendered. All the output is ready to be uploaded
|
||||
to a server to be seen by your audience.
|
||||
|
||||
- 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.md)
|
||||
- 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.md)
|
||||
|
||||
#### Tip & Trick: Hidden Feature
|
||||
When a `SUMMARY.md` file already exists, the `init` command will first parse it and generate the missing files according to the paths used in the `SUMMARY.md`. This allows you to think and create the whole structure of your book and then let mdBook generate it for you.
|
||||
#### Tip: Generate chapters from SUMMARY.md
|
||||
|
||||
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.
|
||||
|
||||
#### Specify a directory
|
||||
|
||||
When using the `init` command, you can also specify a directory, instead of using the current working directory,
|
||||
by appending a path to the command:
|
||||
The `init` command can take a directory as an argument to use as the book's
|
||||
root instead of the current working directory.
|
||||
|
||||
```bash
|
||||
mdbook init path/to/book
|
||||
```
|
||||
|
||||
## --theme
|
||||
#### --theme
|
||||
|
||||
When you use the `--theme` argument, the default theme will be copied into a directory
|
||||
When you use the `--theme` flag, the default theme will be copied into a directory
|
||||
called `theme` in your source directory so that you can modify it.
|
||||
|
||||
The theme is selectively overwritten, this means that if you don't want to overwrite a
|
||||
|
|
|
|||
|
|
@ -1,40 +1,50 @@
|
|||
# The serve command
|
||||
|
||||
The `serve` command is useful when you want to preview your book. It also does hot reloading of the webpage whenever a file changes.
|
||||
It achieves this by serving the books content over `localhost:3000` (unless otherwise configured, see below) and runs a websocket server on `localhost:3001` which triggers the reloads.
|
||||
This preferred by many for writing books with mdbook because it allows for you to see the result of your work instantly after every file change.
|
||||
The serve command is used to preview a book by serving it over HTTP at
|
||||
`localhost:3000` by default. Additionally it watches the book's directory
|
||||
for changes, rebuilding the book and refreshing clients for each change.
|
||||
A websocket connection is used to trigger the client-side refresh.
|
||||
|
||||
#### Specify a directory
|
||||
|
||||
Like `watch`, `serve` can take a directory as an argument to use instead of
|
||||
the current working directory.
|
||||
The `serve` command can take a directory as an argument to use as the book's
|
||||
root instead of the current working directory.
|
||||
|
||||
```bash
|
||||
mdbook serve path/to/book
|
||||
```
|
||||
|
||||
|
||||
#### Server options
|
||||
|
||||
`serve` has four options: the http port, the websocket port, the interface to serve on, and the public address of the server so that the browser may reach the websocket server.
|
||||
`serve` has four options: the HTTP port, the WebSocket port, the HTTP hostname
|
||||
to listen on, and the hostname for the browser to connect to for WebSockets.
|
||||
|
||||
For example: suppose you had an nginx server for SSL termination which has a public address of 192.168.1.100 on port 80 and proxied that to 127.0.0.1 on port 8000. To run use the nginx proxy do:
|
||||
For example: suppose you have an nginx server for SSL termination which has a
|
||||
public address of 192.168.1.100 on port 80 and proxied that to 127.0.0.1 on
|
||||
port 8000. To run use the nginx proxy do:
|
||||
|
||||
```bash
|
||||
mdbook serve path/to/book -p 8000 -i 127.0.0.1 -a 192.168.1.100
|
||||
mdbook serve path/to/book -p 8000 -n 127.0.0.1 --websocket-hostname 192.168.1.100
|
||||
```
|
||||
|
||||
If you were to want live reloading for this you would need to proxy the websocket calls through nginx as well from `192.168.1.100:<WS_PORT>` to `127.0.0.1:<WS_PORT>`. The `-w` flag allows for the websocket port to be configured.
|
||||
If you were to want live reloading for this you would need to proxy the
|
||||
websocket calls through nginx as well from `192.168.1.100:<WS_PORT>` to
|
||||
`127.0.0.1:<WS_PORT>`. The `-w` flag allows for the websocket port to be
|
||||
configured.
|
||||
|
||||
#### --open
|
||||
|
||||
When you use the `--open` (`-o`) option, mdbook will open the book in your
|
||||
When you use the `--open` (`-o`) flag, mdbook will open the book in your
|
||||
your default web browser after starting the server.
|
||||
|
||||
#### --dest-dir
|
||||
|
||||
The `--dest-dir` (`-d`) option allows you to change the output directory for your book.
|
||||
The `--dest-dir` (`-d`) option allows you to change the output directory for
|
||||
the book. If not specified it will default to the value of the
|
||||
`build.build-dir` key in `book.toml`, or to `./book` relative to the book's
|
||||
root directory.
|
||||
|
||||
-----
|
||||
|
||||
***note:*** *the `serve` 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/rust-lang-nursery/mdBook/issues)*
|
||||
***Note:*** *The `serve` command is for testing, and is not intended
|
||||
to be a complete HTTP server for a website.*
|
||||
|
|
|
|||
|
|
@ -1,19 +1,53 @@
|
|||
# The test command
|
||||
|
||||
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.
|
||||
Therefore it is very important for them to be able to automatically test these code examples.
|
||||
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. Therefore it is very important for
|
||||
them to be able to automatically test these code examples.
|
||||
|
||||
mdBook supports a `test` command that will run all available tests in mdBook. At the moment, only one test is available:
|
||||
*"Test Rust code examples using Rustdoc"*, but I hope this will be expanded in the future to include more tests like:
|
||||
mdBook supports a `test` command that will run all available tests in a book.
|
||||
At the moment, only rustdoc tests are supported, but this may be expanded upon
|
||||
in the future.
|
||||
|
||||
- checking for broken links
|
||||
- checking for unused files
|
||||
- ...
|
||||
#### Disable tests on a code block
|
||||
|
||||
In the future I would like the user to be able to enable / disable test from the `book.toml` configuration file and support custom tests.
|
||||
rustdoc doesn't test code blocks which contain the `ignore` attribute:
|
||||
|
||||
```rust,ignore
|
||||
fn main() {}
|
||||
```
|
||||
|
||||
rustdoc also doesn't test code blocks which specify a language other than Rust:
|
||||
|
||||
```markdown
|
||||
**Foo**: _bar_
|
||||
```
|
||||
|
||||
rustdoc *does* test code blocks which have no language specified:
|
||||
|
||||
```
|
||||
This is going to cause an error!
|
||||
```
|
||||
|
||||
#### Specify a directory
|
||||
|
||||
The `test` command can take a directory as an argument to use as the book's
|
||||
root instead of the current working directory.
|
||||
|
||||
**How to use it:**
|
||||
```bash
|
||||
$ mdbook test
|
||||
[*]: Testing file: "/mdBook/book-example/src/README.md”
|
||||
mdbook test path/to/book
|
||||
```
|
||||
|
||||
#### --library-path
|
||||
|
||||
The `--library-path` (`-L`) option allows you to add directories to the library
|
||||
search path used by `rustdoc` when it builds and tests the examples. Multiple
|
||||
directories can be specified with multiple options (`-L foo -L bar`) or with a
|
||||
comma-delimited list (`-L foo,bar`).
|
||||
|
||||
#### --dest-dir
|
||||
|
||||
The `--dest-dir` (`-d`) option allows you to change the output directory for
|
||||
the book. If not specified it will default to the value of the
|
||||
`build.build-dir` key in `book.toml`, or to `./book` relative to the book's
|
||||
root directory.
|
||||
|
|
|
|||
|
|
@ -1,12 +1,14 @@
|
|||
# The watch command
|
||||
|
||||
The `watch` command is useful when you want your book to be rendered on every file change.
|
||||
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.
|
||||
The `watch` command is useful when you want your book to be rendered on every
|
||||
file change. 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.
|
||||
|
||||
#### Specify a directory
|
||||
|
||||
Like `init` and `build`, `watch` can take a directory as an argument to use
|
||||
instead of the current working directory.
|
||||
The `watch` command can take a directory as an argument to use as the book's
|
||||
root instead of the current working directory.
|
||||
|
||||
```bash
|
||||
mdbook watch path/to/book
|
||||
|
|
@ -19,8 +21,7 @@ your default web browser.
|
|||
|
||||
#### --dest-dir
|
||||
|
||||
The `--dest-dir` (`-d`) option allows you to change the output directory for your book.
|
||||
|
||||
-----
|
||||
|
||||
***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/rust-lang-nursery/mdBook/issues)*
|
||||
The `--dest-dir` (`-d`) option allows you to change the output directory for
|
||||
the book. If not specified it will default to the value of the
|
||||
`build.build-dir` key in `book.toml`, or to `./book` relative to the book's
|
||||
root directory.
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ Will render as
|
|||
With the following syntax, you can include files into your book:
|
||||
|
||||
```hbs
|
||||
\{{#include file.rs}}
|
||||
{{#include file.rs}}
|
||||
```
|
||||
|
||||
The path to the file has to be relative from the current source file.
|
||||
|
|
@ -37,10 +37,10 @@ The path to the file has to be relative from the current source file.
|
|||
Usually, this command is used for including code snippets and examples. In this case, oftens one would include a specific part of the file e.g. which only contains the relevant lines for the example. We support four different modes of partial includes:
|
||||
|
||||
```hbs
|
||||
\{{#include file.rs:2}}
|
||||
\{{#include file.rs::10}}
|
||||
\{{#include file.rs:2:}}
|
||||
\{{#include file.rs:2:10}}
|
||||
{{#include file.rs:2}}
|
||||
{{#include file.rs::10}}
|
||||
{{#include file.rs:2:}}
|
||||
{{#include file.rs:2:10}}
|
||||
```
|
||||
|
||||
The first command only includes the second line from file `file.rs`. The second command includes all lines up to line 10, i.e. the lines from 11 till the end of the file are omitted. The third command includes all lines from line 2, i.e. the first line is omitted. The last command includes the excerpt of `file.rs` consisting of lines 2 to 10.
|
||||
|
|
@ -50,7 +50,7 @@ The first command only includes the second line from file `file.rs`. The second
|
|||
With the following syntax, you can insert runnable Rust files into your book:
|
||||
|
||||
```hbs
|
||||
\{{#playpen file.rs}}
|
||||
{{#playpen file.rs}}
|
||||
```
|
||||
|
||||
The path to the Rust file has to be relative from the current source file.
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ Since the original directory structure is maintained, it is useful to prepend re
|
|||
|
||||
In addition to the properties you can access, there are some handlebars helpers at your disposal.
|
||||
|
||||
1. ### toc
|
||||
### 1. toc
|
||||
|
||||
The toc helper is used like this
|
||||
|
||||
|
|
@ -68,7 +68,7 @@ In addition to the properties you can access, there are some handlebars helpers
|
|||
</script>
|
||||
```
|
||||
|
||||
2. ### previous / next
|
||||
### 2. previous / next
|
||||
|
||||
The previous and next helpers expose a `link` and `name` property to the previous and next chapters.
|
||||
|
||||
|
|
@ -87,5 +87,4 @@ In addition to the properties you can access, there are some handlebars helpers
|
|||
|
||||
------
|
||||
|
||||
*If you would like me to expose other properties or helpers, please [create a new issue](https://github.com/rust-lang-nursery/mdBook/issues)
|
||||
and I will consider it.*
|
||||
*If you would like other properties or helpers exposed, please [create a new issue](https://github.com/rust-lang-nursery/mdBook/issues)*
|
||||
|
|
|
|||
Loading…
Reference in a new issue