Configuration file & Configuration inheritance
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 22.2k
- Forks
- 1.9k
- PR merge metrics
- PR metrics pending
Description
Problem
Assume that I am creating the book as a PDF file using the mdbook-pdf plugin and verifying all of the links with the mdbook-linkcheck plugin.
The process of validating links and creating the PDF file, which is mostly required only for book releases, takes a significant amount of time, and the development process (using mdbook serve) suffers because the book has to be rebuilt for every change.
Removing [output.pdf] and [output.linkcheck] manually from book.toml is the only way to resolve this, and don't forget to add them back before committing!
The entire process is excessively error-prone and tedious.
It would be really useful if mdbook had a command line parameter for customizing the configuration file.
Furthermore, supports configuration inheritance to prevent needless duplications. This means that all common configurations (such as title, description, author, etc.) can be contained in a base configuration file, and the latter can be extended by additional configuration files based on the context (like development and release).
The entire feature should be similar to TypeScript extends.
Proposed Solution
-
Custom configuration file
If omitted defaults to
book.tomlmdbook --config path/to/book.toml -
Configuration inheritance
book.dev.toml
[book] title = "Book" # ...book.toml
extends = "./book.dev.toml" [output.pdf] [output.linkcheck] follow-web-links = true warning-policy = "error"
Notes
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the mdbook command and the existing book.toml loading behavior, then compare the proposed book.dev.toml and book.toml examples. Define how --config selects a file and how extends combines inherited and context-specific settings; done means development and release configurations can be used without editing book.toml manually.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- build-system, cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100