2afad43bdd
This adds several changes to how environment variables are handled to
more closely align with how configs are handled, and to fix an issue
with replacing entire tables. The changes are:
- Top-level tables like `MDBOOK_BOOK` now *replace* the contents of the
`book` table instead of merging it. This adds consistency with how all
the other environment objects work.
- Fixed allowing top-level replacement of `MDBOOK_BOOK` and
`MDBOOK_OUTPUT`. This was inadvertently recently broken.
- Added ability to replace top-level `MDBOOK_RUST`. I don't recall why
that wasn't included.
- Reject invalid keys like `MDBOOK_FOO`.
- Reject unknown keys, like `MDBOOK_BOOK='{"xyz": 123}'`
- Reject invalid types, like `MDBOOK_BOOK='{"title": 123}'`
1.5 KiB
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_book->bookMDBOOK_BOOK->bookMDBOOK_BOOK__TITLE->book.titleMDBOOK_BOOK__TEXT_DIRECTION->book.text-direction
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
$ 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.