diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2c230fe344..03083d66b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,11 +56,11 @@ mdBook builds on stable Rust, if you want to build mdBook from source, here are The resulting binary can be found in `mdBook/target/debug/` under the name `mdbook` or `mdbook.exe`. -## Code Quality +## Code quality We love code quality and Rust has some excellent tools to assist you with contributions. -### Formatting Code with rustfmt +### Formatting code with rustfmt Before you make your Pull Request to the project, please run it through the `rustfmt` utility. This will ensure we have good quality source code that is better for us all to maintain. @@ -84,7 +84,7 @@ The quick guide is For more information, such as running it from your favourite editor, please see the `rustfmt` project. [rustfmt](https://github.com/rust-lang/rustfmt) -### Finding Issues with Clippy +### Finding issues with clippy [Clippy](https://doc.rust-lang.org/clippy/) is a code analyser/linter detecting mistakes, and therefore helps to improve your code. Like formatting your code with `rustfmt`, running clippy regularly and before your Pull Request will help us maintain awesome code. diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md index 974d65fae7..1a2a9421be 100644 --- a/guide/src/SUMMARY.md +++ b/guide/src/SUMMARY.md @@ -2,15 +2,15 @@ [Introduction](README.md) -# User Guide +# User guide - [Installation](guide/installation.md) -- [Reading Books](guide/reading.md) -- [Creating a Book](guide/creating.md) +- [Reading books](guide/reading.md) +- [Creating a book](guide/creating.md) -# Reference Guide +# Reference guide -- [Command Line Tool](cli/README.md) +- [Command-line tool](cli/README.md) - [init](cli/init.md) - [build](cli/build.md) - [watch](cli/watch.md) @@ -25,18 +25,18 @@ - [General](format/configuration/general.md) - [Preprocessors](format/configuration/preprocessors.md) - [Renderers](format/configuration/renderers.md) - - [Environment Variables](format/configuration/environment-variables.md) + - [Environment variables](format/configuration/environment-variables.md) - [Theme](format/theme/README.md) - [index.hbs](format/theme/index-hbs.md) - [Syntax highlighting](format/theme/syntax-highlighting.md) - [Editor](format/theme/editor.md) - - [MathJax Support](format/mathjax.md) + - [MathJax support](format/mathjax.md) - [mdBook-specific features](format/mdbook.md) - [Markdown](format/markdown.md) -- [Continuous Integration](continuous-integration.md) -- [For Developers](for_developers/README.md) +- [Continuous integration](continuous-integration.md) +- [For developers](for_developers/README.md) - [Preprocessors](for_developers/preprocessors.md) - - [Alternative Backends](for_developers/backends.md) + - [Alternative backends](for_developers/backends.md) ----------- diff --git a/guide/src/cli/README.md b/guide/src/cli/README.md index d3f5bea948..fb16941ad3 100644 --- a/guide/src/cli/README.md +++ b/guide/src/cli/README.md @@ -1,4 +1,4 @@ -# Command Line Tool +# Command-line tool 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. diff --git a/guide/src/continuous-integration.md b/guide/src/continuous-integration.md index 96b5a8e618..8662c3c916 100644 --- a/guide/src/continuous-integration.md +++ b/guide/src/continuous-integration.md @@ -1,4 +1,4 @@ -# Running `mdbook` in Continuous Integration +# Running `mdbook` in continuous integration 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. diff --git a/guide/src/for_developers/README.md b/guide/src/for_developers/README.md index ea9ed11675..bb53b65080 100644 --- a/guide/src/for_developers/README.md +++ b/guide/src/for_developers/README.md @@ -1,4 +1,4 @@ -# For Developers +# For developers While `mdbook` is mainly used as a command line tool, you can also import the underlying libraries directly and use those to manage a book. It also has a fairly @@ -14,7 +14,7 @@ The two main ways a developer can hook into the book's build process is via, - [Preprocessors](preprocessors.md) - [Alternative Backends](backends.md) -## The Build Process +## The build process The process of rendering a book project goes through several steps. @@ -27,7 +27,7 @@ The process of rendering a book project goes through several steps. 1. Run all the preprocessors. 2. Call the backend to render the processed result. -## Using `mdbook` as a Library +## Using `mdbook` as a library The `mdbook` binary is just a wrapper around the underlying mdBook crates, exposing their functionality as a command-line program. If you want to diff --git a/guide/src/for_developers/backends.md b/guide/src/for_developers/backends.md index c49381d954..1c0dc40e7e 100644 --- a/guide/src/for_developers/backends.md +++ b/guide/src/for_developers/backends.md @@ -1,4 +1,4 @@ -# Alternative Backends +# Alternative backends A "backend" is simply a program which `mdbook` will invoke during the book rendering process. This program is passed a JSON representation of the book and @@ -10,7 +10,7 @@ See [Configuring Renderers](../format/configuration/renderers.md) for more infor The community has developed several backends. See the [Third Party Plugins] wiki page for a list of available backends. -## Setting Up +## 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 @@ -50,7 +50,7 @@ fn main() { > It is recommended that backends use the [`semver`] crate to inspect this field > and emit a warning if there may be a compatibility issue. -## Inspecting the Book +## Inspecting the book Now our backend has a copy of the book, lets count how many words are in each chapter! @@ -79,7 +79,7 @@ fn count_words(ch: &Chapter) -> usize { ``` -## Enabling the Backend +## Enabling the backend Now we've got the basics running, we want to actually use it. First, install the program. @@ -216,7 +216,7 @@ and then add a check to make sure we skip ignored chapters. ``` -## Output and Signalling Failure +## Output and signalling failure While it's nice to print word counts to the terminal when a book is built, it might also be a good idea to output them to a file somewhere. `mdbook` tells a @@ -319,7 +319,7 @@ 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. -## Wrapping Up +## Wrapping up Although contrived, hopefully this example was enough to show how you'd create an alternative backend for `mdbook`. If you feel it's missing something, don't diff --git a/guide/src/for_developers/preprocessors.md b/guide/src/for_developers/preprocessors.md index 1abd39cc5b..1ffc708ed1 100644 --- a/guide/src/for_developers/preprocessors.md +++ b/guide/src/for_developers/preprocessors.md @@ -10,7 +10,7 @@ the book. Possible use cases are: See [Configuring Preprocessors](../format/configuration/preprocessors.md) for more information about using preprocessors. -## Hooking Into MDBook +## 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` @@ -43,7 +43,7 @@ be adapted for other preprocessors. ``` -## Hints For Implementing A Preprocessor +## Hints for implementing a preprocessor By pulling in `mdbook-preprocessor` as a library, preprocessors can have access to the existing infrastructure for dealing with books. diff --git a/guide/src/format/configuration/environment-variables.md b/guide/src/format/configuration/environment-variables.md index 8799c54874..0170e75936 100644 --- a/guide/src/format/configuration/environment-variables.md +++ b/guide/src/format/configuration/environment-variables.md @@ -1,4 +1,4 @@ -# Environment Variables +# Environment variables All configuration values can be overridden from the command line by setting the corresponding environment variable. Because many operating systems restrict diff --git a/guide/src/format/configuration/general.md b/guide/src/format/configuration/general.md index c2c1a9da63..a01b0b1008 100644 --- a/guide/src/format/configuration/general.md +++ b/guide/src/format/configuration/general.md @@ -1,4 +1,4 @@ -# General Configuration +# General configuration You can configure the parameters for your book in the ***book.toml*** file. diff --git a/guide/src/format/configuration/preprocessors.md b/guide/src/format/configuration/preprocessors.md index 24745d35cf..8da96f98b0 100644 --- a/guide/src/format/configuration/preprocessors.md +++ b/guide/src/format/configuration/preprocessors.md @@ -23,7 +23,7 @@ For information on how to create a new preprocessor, see the [Preprocessors for [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 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: @@ -42,7 +42,7 @@ For example, if our example preprocessor needed some extra configuration options some-extra-feature = true ``` -## Locking a Preprocessor dependency to a renderer +## Locking a preprocessor dependency to a renderer You can explicitly specify that a preprocessor should run for a renderer by binding the two together. @@ -52,7 +52,7 @@ binding the two together. 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 @@ -76,7 +76,7 @@ optional = true This demotes the error to a warning. -## 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: diff --git a/guide/src/format/configuration/renderers.md b/guide/src/format/configuration/renderers.md index dc8a81f0fc..2155102680 100644 --- a/guide/src/format/configuration/renderers.md +++ b/guide/src/format/configuration/renderers.md @@ -318,7 +318,7 @@ This will generate an HTML page which will automatically redirect to the given l When fragment redirects are specified, the page must use JavaScript to redirect to the correct location. This is useful if you rename or move a section header. Fragment redirects work with existing pages and deleted pages. -## Markdown Renderer +## Markdown renderer The Markdown renderer will run preprocessors and then output the resulting Markdown. This is mostly useful for debugging preprocessors, especially in diff --git a/guide/src/format/markdown.md b/guide/src/format/markdown.md index 0077302d40..b5a7c73e16 100644 --- a/guide/src/format/markdown.md +++ b/guide/src/format/markdown.md @@ -6,7 +6,7 @@ or [try out](https://spec.commonmark.org/dingus/) CommonMark in real time. A com 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). -## Text and Paragraphs +## Text and paragraphs Text is rendered relatively predictably: diff --git a/guide/src/format/mathjax.md b/guide/src/format/mathjax.md index 3dd792159d..d60ed0a5fd 100644 --- a/guide/src/format/mathjax.md +++ b/guide/src/format/mathjax.md @@ -1,4 +1,4 @@ -# MathJax Support +# MathJax support mdBook has optional support for math equations through [MathJax](https://www.mathjax.org/). diff --git a/guide/src/format/mdbook.md b/guide/src/format/mdbook.md index 99e2b39d39..4243627fd1 100644 --- a/guide/src/format/mdbook.md +++ b/guide/src/format/mdbook.md @@ -71,7 +71,7 @@ nothidden(): ``` ~~~ -## Rust Playground +## Rust playground Rust language code blocks will automatically get a play button () which will execute the code and display the output just below the code block. This works by sending the code to the [Rust Playground]. diff --git a/guide/src/format/theme/editor.md b/guide/src/format/theme/editor.md index 2ed1ed8363..f78ca2186d 100644 --- a/guide/src/format/theme/editor.md +++ b/guide/src/format/theme/editor.md @@ -32,7 +32,7 @@ fn main() { Note the new `Undo Changes` button in the editable playgrounds. -## Customizing the Editor +## Customizing the editor By default, the editor is the [Ace](https://ace.c9.io/) editor, but, if desired, the functionality may be overridden by providing a different folder: diff --git a/guide/src/format/theme/index-hbs.md b/guide/src/format/theme/index-hbs.md index e1046c0f6c..16e14b2c07 100644 --- a/guide/src/format/theme/index-hbs.md +++ b/guide/src/format/theme/index-hbs.md @@ -38,7 +38,7 @@ Here is a list of the properties that are exposed: containing all the chapters of the book. It is used for example to construct the table of contents (sidebar). -## Handlebars Helpers +## Handlebars helpers In addition to the properties you can access, there are some handlebars helpers at your disposal. diff --git a/guide/src/format/theme/syntax-highlighting.md b/guide/src/format/theme/syntax-highlighting.md index df36041ca1..069c568957 100644 --- a/guide/src/format/theme/syntax-highlighting.md +++ b/guide/src/format/theme/syntax-highlighting.md @@ -1,4 +1,4 @@ -# Syntax Highlighting +# Syntax highlighting mdBook uses [Highlight.js](https://highlightjs.org) with a custom theme for syntax highlighting. diff --git a/guide/src/guide/README.md b/guide/src/guide/README.md index 90deb10e74..bce04e373f 100644 --- a/guide/src/guide/README.md +++ b/guide/src/guide/README.md @@ -1,4 +1,4 @@ -# User Guide +# User guide This user guide provides an introduction to basic concepts of using mdBook. diff --git a/guide/src/guide/creating.md b/guide/src/guide/creating.md index f68a8c6095..613114c82b 100644 --- a/guide/src/guide/creating.md +++ b/guide/src/guide/creating.md @@ -1,4 +1,4 @@ -# Creating a Book +# Creating a book Once you have the `mdbook` CLI tool installed, you can use it to create and render a book. @@ -106,4 +106,4 @@ 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. \ No newline at end of file +For more information about publishing and deploying, check out the [Continuous Integration chapter](../continuous-integration.md) for more. diff --git a/guide/src/guide/reading.md b/guide/src/guide/reading.md index fdfec65b4e..e43d5bcb7a 100644 --- a/guide/src/guide/reading.md +++ b/guide/src/guide/reading.md @@ -1,4 +1,4 @@ -# Reading Books +# 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.