rust-lang / rust-lang/mdBook

Configuration file & Configuration inheritance

Open
#2,270 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-enhancement
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
  1. Custom configuration file

    If omitted defaults to book.toml

    mdbook --config path/to/book.toml
    
  2. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.