Skip to content

Commit

Permalink
Rewrap guide markdown at 80 columns
Browse files Browse the repository at this point in the history
Much of the book was wrapped at around 80 columns, but let's make this consistent.
  • Loading branch information
mattico committed Aug 3, 2018
1 parent 5f6c281 commit 44e27e0
Show file tree
Hide file tree
Showing 20 changed files with 312 additions and 234 deletions.
20 changes: 15 additions & 5 deletions book-example/src/README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,25 @@
# mdBook

**mdBook** is a command line tool and Rust crate to create books using Markdown files. It's very similar to Gitbook but written in [Rust](http://www.rust-lang.org).
**mdBook** is a command line tool and Rust crate to create books using Markdown
files. It's very similar to Gitbook but written in
[Rust](http://www.rust-lang.org).

What you are reading serves as an example of the output of mdBook and at the same time as a high-level documentation.
What you are reading serves as an example of the output of mdBook and at the
same time as a high-level documentation.

mdBook is free and open source, you can find the source code on [Github](https://github.com/rust-lang-nursery/mdBook). Issues and feature requests can be posted on the [Github Issue tracker](https://github.com/rust-lang-nursery/mdBook/issues).
mdBook is free and open source, you can find the source code on
[GitHub](https://github.com/rust-lang-nursery/mdBook). Issues and feature
requests can be posted on the [GitHub issue
tracker](https://github.com/rust-lang-nursery/mdBook/issues).

## API docs

Alongside this book you can also read the [API docs](https://docs.rs/mdbook/*/mdbook/) generated by Rustdoc if you would like to use mdBook as a crate or write a new renderer and need a more low-level overview.
Alongside this book you can also read the [API
docs](https://docs.rs/mdbook/*/mdbook/) generated by Rustdoc if you would like
to use mdBook as a crate or write a new renderer and need a more low-level
overview.

## License

mdBook, all the source code, is released under the [Mozilla Public License v2.0](https://www.mozilla.org/MPL/2.0/)
mdBook, all the source code, is released under the [Mozilla Public License
v2.0](https://www.mozilla.org/MPL/2.0/).
14 changes: 7 additions & 7 deletions book-example/src/cli/build.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ The build command is used to render your book:
mdbook build
```

It will try to parse your `SUMMARY.md` file to understand the structure of your book
and fetch the corresponding files.
It will try to parse your `SUMMARY.md` file to understand the structure of your
book and fetch the corresponding files.

The rendered output will maintain the same directory structure as the source for
convenience. Large books will therefore remain structured when rendered.
Expand All @@ -28,11 +28,11 @@ your default web browser after building it.

#### --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.
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*
6 changes: 3 additions & 3 deletions book-example/src/cli/clean.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@ 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.
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
Expand Down
39 changes: 21 additions & 18 deletions book-example/src/cli/init.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,16 @@
# 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:

```bash
mdbook init
```

When using the `init` command for the first time, a couple of files will be set up for you:
When using the `init` command for the first time, a couple of files will be set
up for you:
```bash
book-test/
├── book
Expand All @@ -18,34 +19,36 @@ book-test/
└── SUMMARY.md
```

- The `src` directory is were you write your book in markdown. It contains all the source files,
configuration files, etc.
- The `src` directory is were you write your book in markdown. It contains all
the source files, 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 `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: 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.
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

The `init` command can take a directory as an argument to use as the book's
root instead of the current working directory.
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

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.
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
specific file, just delete it and the default file will be used.
The theme is selectively overwritten, this means that if you don't want to
overwrite a specific file, just delete it and the default file will be used.
25 changes: 12 additions & 13 deletions book-example/src/cli/serve.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# 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 changes, rebuilding the book and refreshing clients for each change.
A websocket connection is used to trigger the client-side refresh.
`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

Expand All @@ -20,8 +20,8 @@ mdbook serve path/to/book
to listen on, and the hostname for the browser to connect to for WebSockets.

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:
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 -n 127.0.0.1 --websocket-hostname 192.168.1.100
Expand All @@ -34,17 +34,16 @@ configured.

#### --open

When you use the `--open` (`-o`) flag, mdbook will open the book in your
your default web browser after starting the server.
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
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.
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 is for testing, and is not intended
to be a complete HTTP server for a website.*
***Note:*** *The `serve` command is for testing, and is not intended to be a
complete HTTP server for a website.*
17 changes: 8 additions & 9 deletions book-example/src/cli/test.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ When writing a book, you sometimes need to automate some tests. For example,
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 a book.
At the moment, only rustdoc tests are supported, but this may be expanded upon
in the future.
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.

#### Disable tests on a code block

Expand All @@ -31,8 +31,8 @@ rustdoc *does* test code blocks which have no language specified:

#### 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.
The `test` command can take a directory as an argument to use as the book's root
instead of the current working directory.

```bash
mdbook test path/to/book
Expand All @@ -47,7 +47,6 @@ 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.
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.
11 changes: 5 additions & 6 deletions book-example/src/cli/watch.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

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.
changed. But using `mdbook watch` once will watch your files and will trigger a
build automatically whenever you modify a file.

#### Specify a directory

Expand All @@ -21,7 +21,6 @@ your default web browser.

#### --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.
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.
8 changes: 6 additions & 2 deletions book-example/src/continuous-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,13 @@ script:
Following these instructions will result in your book being published to GitHub
pages after a successful CI run on your repository's `master` branch.

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.
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.

Then, append this snippet to your `.travis.yml` and update the path to the `book` directory:
Then, append this snippet to your `.travis.yml` and update the path to the
`book` directory:

```yaml
deploy:
Expand Down
10 changes: 5 additions & 5 deletions book-example/src/for_developers/README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# For Developers

While `mdbook` is mainly used as a command line tool, you can also import the
While `mdbook` is mainly used as a command line tool, you can also import the
underlying library directly and use that to manage a book. It also has a fairly
flexible plugin mechanism, allowing you to create your own custom tooling and
flexible plugin mechanism, allowing you to create your own custom tooling and
consumers (often referred to as *backends*) if you need to do some analysis of
the book or render it in a different format.

The *For Developers* chapters are here to show you the more advanced usage of
The *For Developers* chapters are here to show you the more advanced usage of
`mdbook`.

The two main ways a developer can hook into the book's build process is via,
Expand All @@ -32,11 +32,11 @@ The process of rendering a book project goes through several steps.

The `mdbook` binary is just a wrapper around the `mdbook` crate, exposing its
functionality as a command-line program. As such it is quite easy to create your
own programs which use `mdbook` internally, adding your own functionality (e.g.
own programs which use `mdbook` internally, adding your own functionality (e.g.
a custom preprocessor) or tweaking the build process.

The easiest way to find out how to use the `mdbook` crate is by looking at the
[API Docs]. The top level documentation explains how one would use the
[API Docs]. The top level documentation explains how one would use the
[`MDBook`] type to load and build a book, while the [config] module gives a good
explanation on the configuration system.

Expand Down
Loading

0 comments on commit 44e27e0

Please sign in to comment.