Custom Preprocessors

[Michael-F-Bryan]

This lets anyone provide their own custom preprocessor by shelling out to the provided command.

CC: #762, @badboy

[Michael-F-Bryan]

I think I've got the basic idea implemented, and the example program works exactly as I'd expect.

This will need a proper review and we may want to bikeshed on the nuances of how information is passed/received from the subcommand though. Plus I still need to create a new page in the user guide.

[badboy]

One thing I'd like to see mentioned in the docs is the handling of multiple preprocessors: Are they executed in the specified order?

And another thing: Will the input/output format be documented somewhere? This would make writing preprocessor not based on the mdbook lib possible (e.g. in other languages)

[Michael-F-Bryan]

Are they executed in the specified order?

In general, I believe it'll run default preprocessors first then all other preprocessors will be run in the order they were defined in book.toml. I'm tempted to say the order will be implementation defined, seeing as it's more a side-effect of how preprocessors are discovered and not due to any explicit plan.

Will the input/output format be documented somewhere?

At the moment the format is a JSON array where the first element is PreprocessorContext and the second element is a Book, but the best reference would be the CmdPreprocessor::parse_input() helper function.

In the long term it should probably be documented, but that would mean we also need to document (and stabilize) the entire internals for Book and Config. If possible, I'd like to defer that decision until there is a need for it (e.g. someone makes an issue wanting to create a preprocessor or backend in Python).

[Michael-F-Bryan]

I think this implementation for custom preprocessors is a good starting point. I've merged it so people can start using it in real-life scenarios (like @badboy's) as of the next release.

[badboy]

Thanks!