Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update serve documentation in the guide #1525

Merged
merged 3 commits into from
May 10, 2021
Merged

Update serve documentation in the guide #1525

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
aa349e0
update serve documentation
joshrotenberg May 8, 2021
f4b4a33
consisten note format, update gitignore language
joshrotenberg May 8, 2021
c922b8a
backquote port
joshrotenberg May 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 13 additions & 17 deletions guide/src/cli/serve.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,13 @@
# The serve command

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
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
changes, rebuilding the book and refreshing clients for each change. A websocket
connection is used to trigger the client-side refresh.

Expand All @@ -17,24 +23,14 @@ root instead of the current working directory.
mdbook serve path/to/book
```

#### Server options

`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.
### Server options

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:
The `serve` hostname defaults to `localhost`, and the port defaults to `3000`. Either option can be specified on the command line:

```bash
mdbook serve path/to/book -p 8000 -n 127.0.0.1 --websocket-hostname 192.168.1.100
mdbook serve path/to/book -p 8000 -n 127.0.0.1
```

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`) flag, mdbook will open the book in your
Expand All @@ -55,5 +51,5 @@ 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.

_Note: Only `.gitignore` from book root directory is used. Global
`$HOME/.gitignore` or `.gitignore` files in parent directories are not used._
***Note:*** *Only the `.gitignore` from the book root directory is used. Global
`$HOME/.gitignore` or `.gitignore` files in parent directories are not used.*