search

rust-lang / mdBook

Create book from markdown files. Like Gitbook but implemented in Rust
https://rust-lang.github.io/mdBook/
Mozilla Public License 2.0
18.08k stars 1.63k forks source link

Allow alternatives to `book.toml` on the command-line #1154

Open jpgoldberg opened 4 years ago

jpgoldberg commented 4 years ago

For various reasons, I need a different .toml file depending on whether I am building for HTML or PDF (with mdbook-latex). It would be nice if I could specify which TOML file to use during mdbook build.

(I realize as I ask this that I can just create different directories, each with their own book.toml file pointing to the common source to get the behavior that I want. So perhaps this feature isn't needed.)

bryfry commented 3 years ago

I have this same use case requirement. The same source repository has two mdbook derived downstream outputs: PDF and HTML. As a result of the target between the two requires different book.toml files [1]. Another possible solution would be to allow some additional configurations in the book.toml to be overridden by cli flags.

  1. I really like the new feature to disable print page but it also disables the creation of the print.html page entirely. Our workflow previously used a forked version of mdbook which removed the html button for printing but kept the file. The new way is better (you can't just browse to the predictable page name) but it broke the other workflow that required the print.html which we used to create a pdf file. I'd use two config files (pdf.toml and html.toml) if I could.
joshrotenberg commented 3 years ago

I'm taking a crack at implementing this (because I wanted it for something too).

My approach, briefly, is to add a method on MDBook in the library to load a book from a config file in addition to the existing option to load it from book.toml or use the default if one doesn't exist.

This is then exposed via the CLI with a new, optional flag in all of the commands that need to load the book (basically everything except for init and help). I'm going with -c, --config-file.

bryfry commented 3 years ago

https://github.com/rust-lang/mdBook/pull/1518#issuecomment-847434334 pointed me in the direction to solve this problem with environment variables, specifically: 

MDBOOK_OUTPUT__HTML__PRINT__ENABLE=true mdbook build

I still see value in multiple configs, especially when committing the configs to a git repo