2016-08-06 05:40:00 +08:00
|
|
|
# The serve command
|
|
|
|
|
|
2021-05-08 11:29:01 +08:00
|
|
|
The serve command is used to preview a book by serving it via HTTP at
|
|
|
|
|
`localhost:3000` by default:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
mdbook serve
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The `serve` command watches the book's `src` directory for
|
2021-05-25 19:45:30 +08:00
|
|
|
changes, rebuilding the book and refreshing clients for each change; this includes
|
|
|
|
|
re-creating deleted files still mentioned in `SUMMARY.md`! A websocket
|
2018-08-03 10:34:26 +08:00
|
|
|
connection is used to trigger the client-side refresh.
|
2016-08-06 05:40:00 +08:00
|
|
|
|
2018-09-06 23:24:56 +08:00
|
|
|
***Note:*** *The `serve` command is for testing a book's HTML output, and is not
|
|
|
|
|
intended to be a complete HTTP server for a website.*
|
|
|
|
|
|
2016-08-06 05:40:00 +08:00
|
|
|
#### Specify a directory
|
|
|
|
|
|
2018-08-03 05:52:54 +08:00
|
|
|
The `serve` command can take a directory as an argument to use as the book's
|
|
|
|
|
root instead of the current working directory.
|
2016-08-06 05:40:00 +08:00
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
mdbook serve path/to/book
|
|
|
|
|
```
|
|
|
|
|
|
2021-05-09 00:51:30 +08:00
|
|
|
### Server options
|
2016-08-06 05:40:00 +08:00
|
|
|
|
2021-05-09 00:51:30 +08:00
|
|
|
The `serve` hostname defaults to `localhost`, and the port defaults to `3000`. Either option can be specified on the command line:
|
2016-08-06 05:40:00 +08:00
|
|
|
|
|
|
|
|
```bash
|
2021-05-08 11:29:01 +08:00
|
|
|
mdbook serve path/to/book -p 8000 -n 127.0.0.1
|
2016-08-06 05:40:00 +08:00
|
|
|
```
|
|
|
|
|
|
2017-01-02 01:42:47 +08:00
|
|
|
#### --open
|
|
|
|
|
|
2019-04-12 22:53:21 +08:00
|
|
|
When you use the `--open` (`-o`) flag, mdbook will open the book in your
|
2018-08-03 10:34:26 +08:00
|
|
|
default web browser after starting the server.
|
2017-01-02 01:42:47 +08:00
|
|
|
|
2017-01-17 08:11:39 +08:00
|
|
|
#### --dest-dir
|
|
|
|
|
|
2018-08-03 10:34:26 +08:00
|
|
|
The `--dest-dir` (`-d`) option allows you to change the output directory for the
|
2018-09-06 23:24:42 +08:00
|
|
|
book. Relative paths are interpreted relative to the book's root directory. If
|
|
|
|
|
not specified it will default to the value of the `build.build-dir` key in
|
|
|
|
|
`book.toml`, or to `./book`.
|
2020-03-11 01:32:12 +08:00
|
|
|
|
|
|
|
|
#### Specify exclude patterns
|
|
|
|
|
|
|
|
|
|
The `serve` command will not automatically trigger a build for files listed in
|
|
|
|
|
the `.gitignore` file in the book root directory. The `.gitignore` file may
|
|
|
|
|
contain file patterns described in the [gitignore
|
|
|
|
|
documentation](https://git-scm.com/docs/gitignore). This can be useful for
|
|
|
|
|
ignoring temporary files created by some editors.
|
|
|
|
|
|
2021-05-08 12:02:55 +08:00
|
|
|
***Note:*** *Only the `.gitignore` from the book root directory is used. Global
|
|
|
|
|
`$HOME/.gitignore` or `.gitignore` files in parent directories are not used.*
|
