From aa4cb9465ff0a214da1b98c105c9939eeb089456 Mon Sep 17 00:00:00 2001 From: josh rotenberg Date: Sun, 23 May 2021 17:59:52 -0700 Subject: [PATCH] restructure guide configuration section restructure guide configuration section restructure guide configuration section redirect to new config top level fix broken links use a relative path for redirect Co-authored-by: Eric Huss remove extra heading --- guide/book.toml | 3 + guide/src/SUMMARY.md | 6 +- guide/src/format/configuration/README.md | 12 ++ .../configuration/environment-variables.md | 38 ++++ guide/src/format/configuration/general.md | 97 +++++++++ .../src/format/configuration/preprocessors.md | 58 +++++ .../{config.md => configuration/renderers.md} | 202 +----------------- guide/src/format/theme/README.md | 2 +- 8 files changed, 217 insertions(+), 201 deletions(-) create mode 100644 guide/src/format/configuration/README.md create mode 100644 guide/src/format/configuration/environment-variables.md create mode 100644 guide/src/format/configuration/general.md create mode 100644 guide/src/format/configuration/preprocessors.md rename guide/src/format/{config.md => configuration/renderers.md} (60%) diff --git a/guide/book.toml b/guide/book.toml index a37c2a7f..025efc0b 100644 --- a/guide/book.toml +++ b/guide/book.toml @@ -25,3 +25,6 @@ boost-hierarchy = 2 boost-paragraph = 1 expand = true heading-split-level = 2 + +[output.html.redirect] +"/format/config.html" = "configuration/index.html" diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md index 7848743e..d95410cc 100644 --- a/guide/src/SUMMARY.md +++ b/guide/src/SUMMARY.md @@ -11,7 +11,11 @@ - [Format](format/README.md) - [SUMMARY.md](format/summary.md) - [Draft chapter]() - - [Configuration](format/config.md) + - [Configuration](format/configuration/README.md) + - [General](format/configuration/general.md) + - [Preprocessors](format/configuration/preprocessors.md) + - [Renderers](format/configuration/renderers.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) diff --git a/guide/src/format/configuration/README.md b/guide/src/format/configuration/README.md new file mode 100644 index 00000000..4dcb5852 --- /dev/null +++ b/guide/src/format/configuration/README.md @@ -0,0 +1,12 @@ +# Configuration + +This section details the configuration options available in the ***book.toml***: +- **[General]** configuration including the `book`, `rust`, `build` sections +- **[Preprocessor]** configuration for default and custom book preprocessors +- **[Renderer]** configuration for the HTML, Markdown and custom renderers +- **[Environment Variable]** configuration for overriding configuration options in your environment + +[General]: general.md +[Preprocessor]: preprocessors.md +[Renderer]: renderers.md +[Environment Variable]: environment-variables.md \ No newline at end of file diff --git a/guide/src/format/configuration/environment-variables.md b/guide/src/format/configuration/environment-variables.md new file mode 100644 index 00000000..3631769b --- /dev/null +++ b/guide/src/format/configuration/environment-variables.md @@ -0,0 +1,38 @@ +# Environment Variables + +All configuration values can be overridden from the command line by setting the +corresponding environment variable. Because many operating systems restrict +environment variables to be alphanumeric characters or `_`, the configuration +key needs to be formatted slightly differently to the normal `foo.bar.baz` form. + +Variables starting with `MDBOOK_` are used for configuration. The key is created +by removing the `MDBOOK_` prefix and turning the resulting string into +`kebab-case`. Double underscores (`__`) separate nested keys, while a single +underscore (`_`) is replaced with a dash (`-`). + +For example: + +- `MDBOOK_foo` -> `foo` +- `MDBOOK_FOO` -> `foo` +- `MDBOOK_FOO__BAR` -> `foo.bar` +- `MDBOOK_FOO_BAR` -> `foo-bar` +- `MDBOOK_FOO_bar__baz` -> `foo-bar.baz` + +So by setting the `MDBOOK_BOOK__TITLE` environment variable you can override the +book's title without needing to touch your `book.toml`. + +> **Note:** To facilitate setting more complex config items, the value of an +> environment variable is first parsed as JSON, falling back to a string if the +> parse fails. +> +> This means, if you so desired, you could override all book metadata when +> building the book with something like +> +> ```shell +> $ export MDBOOK_BOOK="{'title': 'My Awesome Book', authors: ['Michael-F-Bryan']}" +> $ mdbook build +> ``` + +The latter case may be useful in situations where `mdbook` is invoked from a +script or CI, where it sometimes isn't possible to update the `book.toml` before +building. diff --git a/guide/src/format/configuration/general.md b/guide/src/format/configuration/general.md new file mode 100644 index 00000000..20396fac --- /dev/null +++ b/guide/src/format/configuration/general.md @@ -0,0 +1,97 @@ +# General Configuration + +You can configure the parameters for your book in the ***book.toml*** file. + +Here is an example of what a ***book.toml*** file might look like: + +```toml +[book] +title = "Example book" +author = "John Doe" +description = "The example book covers examples." + +[rust] +edition = "2018" + +[build] +build-dir = "my-example-book" +create-missing = false + +[preprocessor.index] + +[preprocessor.links] + +[output.html] +additional-css = ["custom.css"] + +[output.html.search] +limit-results = 15 +``` + +## Supported configuration options + +It is important to note that **any** relative path specified in the +configuration will always be taken relative from the root of the book where the +configuration file is located. + +### General metadata + +This is general information about your book. + +- **title:** The title of the book +- **authors:** The author(s) of the book +- **description:** A description for the book, which is added as meta + information in the html `` of each page +- **src:** By default, the source directory is found in the directory named + `src` directly under the root folder. But this is configurable with the `src` + key in the configuration file. +- **language:** The main language of the book, which is used as a language attribute `` for example. + +**book.toml** +```toml +[book] +title = "Example book" +authors = ["John Doe", "Jane Doe"] +description = "The example book covers examples." +src = "my-src" # the source files will be found in `root/my-src` instead of `root/src` +language = "en" +``` + +### Rust options + +Options for the Rust language, relevant to running tests and playground +integration. + +- **edition**: Rust edition to use by default for the code snippets. Default + is "2015". Individual code blocks can be controlled with the `edition2015` + or `edition2018` annotations, such as: + + ~~~text + ```rust,edition2015 + // This only works in 2015. + let try = true; + ``` + ~~~ + +### Build options + +This controls the build process of your book. + +- **build-dir:** The directory to put the rendered book in. By default this is + `book/` in the book's root directory. +- **create-missing:** By default, any missing files specified in `SUMMARY.md` + will be created when the book is built (i.e. `create-missing = true`). If this + is `false` then the build process will instead exit with an error if any files + do not exist. +- **use-default-preprocessors:** Disable the default preprocessors of (`links` & + `index`) by setting this option to `false`. + + If you have the same, and/or other preprocessors declared via their table + of configuration, they will run instead. + + - For clarity, with no preprocessor configuration, the default `links` and + `index` will run. + - Setting `use-default-preprocessors = false` will disable these + default preprocessors from running. + - Adding `[preprocessor.links]`, for example, will ensure, regardless of + `use-default-preprocessors` that `links` it will run. diff --git a/guide/src/format/configuration/preprocessors.md b/guide/src/format/configuration/preprocessors.md new file mode 100644 index 00000000..be614cac --- /dev/null +++ b/guide/src/format/configuration/preprocessors.md @@ -0,0 +1,58 @@ +# Configuring Preprocessors + +The following preprocessors are available and included by default: + +- `links`: Expand the `{{ #playground }}`, `{{ #include }}`, and `{{ #rustdoc_include }}` handlebars + helpers in a chapter to include the contents of a file. +- `index`: Convert all chapter files named `README.md` into `index.md`. That is + to say, all `README.md` would be rendered to an index file `index.html` in the + rendered book. + + +**book.toml** +```toml +[build] +build-dir = "build" +create-missing = false + +[preprocessor.links] + +[preprocessor.index] +``` + +### Custom Preprocessor Configuration + +Like renderers, preprocessor will need to be given its own table (e.g. +`[preprocessor.mathjax]`). In the section, you may then pass extra +configuration to the preprocessor by adding key-value pairs to the table. + +For example + +```toml +[preprocessor.links] +# set the renderers this preprocessor will run for +renderers = ["html"] +some_extra_feature = true +``` + +#### Locking a Preprocessor dependency to a renderer + +You can explicitly specify that a preprocessor should run for a renderer by +binding the two together. + +```toml +[preprocessor.mathjax] +renderers = ["html"] # mathjax only makes sense with the HTML renderer +``` + +### 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 +different program name or pass in command-line arguments, this behaviour can +be overridden by adding a `command` field. + +```toml +[preprocessor.random] +command = "python random.py" +``` diff --git a/guide/src/format/config.md b/guide/src/format/configuration/renderers.md similarity index 60% rename from guide/src/format/config.md rename to guide/src/format/configuration/renderers.md index 03b1daed..e3d1a397 100644 --- a/guide/src/format/config.md +++ b/guide/src/format/configuration/renderers.md @@ -1,161 +1,4 @@ -# Configuration - -You can configure the parameters for your book in the ***book.toml*** file. - -Here is an example of what a ***book.toml*** file might look like: - -```toml -[book] -title = "Example book" -author = "John Doe" -description = "The example book covers examples." - -[rust] -edition = "2018" - -[build] -build-dir = "my-example-book" -create-missing = false - -[preprocessor.index] - -[preprocessor.links] - -[output.html] -additional-css = ["custom.css"] - -[output.html.search] -limit-results = 15 -``` - -## Supported configuration options - -It is important to note that **any** relative path specified in the -configuration will always be taken relative from the root of the book where the -configuration file is located. - -### General metadata - -This is general information about your book. - -- **title:** The title of the book -- **authors:** The author(s) of the book -- **description:** A description for the book, which is added as meta - information in the html `` of each page -- **src:** By default, the source directory is found in the directory named - `src` directly under the root folder. But this is configurable with the `src` - key in the configuration file. -- **language:** The main language of the book, which is used as a language attribute `` for example. - -**book.toml** -```toml -[book] -title = "Example book" -authors = ["John Doe", "Jane Doe"] -description = "The example book covers examples." -src = "my-src" # the source files will be found in `root/my-src` instead of `root/src` -language = "en" -``` - -### Rust options - -Options for the Rust language, relevant to running tests and playground -integration. - -- **edition**: Rust edition to use by default for the code snippets. Default - is "2015". Individual code blocks can be controlled with the `edition2015` - or `edition2018` annotations, such as: - - ~~~text - ```rust,edition2015 - // This only works in 2015. - let try = true; - ``` - ~~~ - -### Build options - -This controls the build process of your book. - -- **build-dir:** The directory to put the rendered book in. By default this is - `book/` in the book's root directory. -- **create-missing:** By default, any missing files specified in `SUMMARY.md` - will be created when the book is built (i.e. `create-missing = true`). If this - is `false` then the build process will instead exit with an error if any files - do not exist. -- **use-default-preprocessors:** Disable the default preprocessors of (`links` & - `index`) by setting this option to `false`. - - If you have the same, and/or other preprocessors declared via their table - of configuration, they will run instead. - - - For clarity, with no preprocessor configuration, the default `links` and - `index` will run. - - Setting `use-default-preprocessors = false` will disable these - default preprocessors from running. - - Adding `[preprocessor.links]`, for example, will ensure, regardless of - `use-default-preprocessors` that `links` it will run. - -## Configuring Preprocessors - -The following preprocessors are available and included by default: - -- `links`: Expand the `{{ #playground }}`, `{{ #include }}`, and `{{ #rustdoc_include }}` handlebars - helpers in a chapter to include the contents of a file. -- `index`: Convert all chapter files named `README.md` into `index.md`. That is - to say, all `README.md` would be rendered to an index file `index.html` in the - rendered book. - - -**book.toml** -```toml -[build] -build-dir = "build" -create-missing = false - -[preprocessor.links] - -[preprocessor.index] -``` - -### Custom Preprocessor Configuration - -Like renderers, preprocessor will need to be given its own table (e.g. -`[preprocessor.mathjax]`). In the section, you may then pass extra -configuration to the preprocessor by adding key-value pairs to the table. - -For example - -```toml -[preprocessor.links] -# set the renderers this preprocessor will run for -renderers = ["html"] -some_extra_feature = true -``` - -#### Locking a Preprocessor dependency to a renderer - -You can explicitly specify that a preprocessor should run for a renderer by -binding the two together. - -```toml -[preprocessor.mathjax] -renderers = ["html"] # mathjax only makes sense with the HTML renderer -``` - -### 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 -different program name or pass in command-line arguments, this behaviour can -be overridden by adding a `command` field. - -```toml -[preprocessor.random] -command = "python random.py" -``` - -## Configuring Renderers +# Configuring Renderers ### HTML renderer options @@ -175,7 +18,7 @@ The following configuration options are available: CSS media query. Defaults to `navy`. - **curly-quotes:** Convert straight quotes to curly quotes, except for those that occur in code blocks and code spans. Defaults to `false`. -- **mathjax-support:** Adds support for [MathJax](mathjax.md). Defaults to +- **mathjax-support:** Adds support for [MathJax](../mathjax.md). Defaults to `false`. - **copy-fonts:** Copies fonts.css and respective font files to the output directory and use them in the default theme. Defaults to `true`. - **google-analytics:** If you use Google Analytics, this option lets you enable @@ -363,43 +206,4 @@ anything under `[output.foo]`). mdBook checks for two common fields: - **optional:** If `true`, then the command will be ignored if it is not installed, otherwise mdBook will fail with an error. Defaults to `false`. -[alternative backends]: ../for_developers/backends.md - -## Environment Variables - -All configuration values can be overridden from the command line by setting the -corresponding environment variable. Because many operating systems restrict -environment variables to be alphanumeric characters or `_`, the configuration -key needs to be formatted slightly differently to the normal `foo.bar.baz` form. - -Variables starting with `MDBOOK_` are used for configuration. The key is created -by removing the `MDBOOK_` prefix and turning the resulting string into -`kebab-case`. Double underscores (`__`) separate nested keys, while a single -underscore (`_`) is replaced with a dash (`-`). - -For example: - -- `MDBOOK_foo` -> `foo` -- `MDBOOK_FOO` -> `foo` -- `MDBOOK_FOO__BAR` -> `foo.bar` -- `MDBOOK_FOO_BAR` -> `foo-bar` -- `MDBOOK_FOO_bar__baz` -> `foo-bar.baz` - -So by setting the `MDBOOK_BOOK__TITLE` environment variable you can override the -book's title without needing to touch your `book.toml`. - -> **Note:** To facilitate setting more complex config items, the value of an -> environment variable is first parsed as JSON, falling back to a string if the -> parse fails. -> -> This means, if you so desired, you could override all book metadata when -> building the book with something like -> -> ```shell -> $ export MDBOOK_BOOK="{'title': 'My Awesome Book', authors: ['Michael-F-Bryan']}" -> $ mdbook build -> ``` - -The latter case may be useful in situations where `mdbook` is invoked from a -script or CI, where it sometimes isn't possible to update the `book.toml` before -building. +[alternative backends]: ../../for_developers/backends.md diff --git a/guide/src/format/theme/README.md b/guide/src/format/theme/README.md index b327b1d4..1f40844f 100644 --- a/guide/src/format/theme/README.md +++ b/guide/src/format/theme/README.md @@ -42,5 +42,5 @@ If you completely replace all built-in themes, be sure to also set [`output.html.preferred-dark-theme`] in the config, which defaults to the built-in `navy` theme. -[`output.html.preferred-dark-theme`]: ../config.md#html-renderer-options +[`output.html.preferred-dark-theme`]: ../configuration/renderers.md#html-renderer-options [newer browsers]: https://caniuse.com/#feat=link-icon-svg