[Discussion] New renderers design

[azerupi]

The idea, is to separate mdBook into more clearly defined "modules". (not Rust modules)

• core: The core handles the internal representation. It parses the configuration file and the summary file. It should contain only generic metadata and the structure of the book (see [Discussion] Book representation #146 for more discussion)
• renderers: Renderers are self contained modules that consume the book as stored in core and render it to one specific target (e.g. html, EPUB, pdf, ...)

Renderers could need additional metadata or offer specific settings that could (and should) not be represented in the core internal representation. For that purpose, the configuration file will allow sub-sections for the renderer specific options. Imagine:

[outputs.html]
path = "book/"
favicon = "src/img/favicon.png"

[outputs.epub]
isbn = "978-0-9999999-9-9"
uuid = "58dce2ac-7aec-45c3-a6de-903a30061545"
version = "1.0"

# ...

Those configuration parameters will be passed down to the renderer, it's his job to actually make sense of those settings.

Essentially MDBook + [outputs.renderer] => Renderer = Output

[gambhiro]

So, different Renderer implementations would be responsible for creating the different output from book.toml + SUMMARY.md + Markdown chapters?

I'm thinking of examples such as,

• a Renderer that uses an ebook page template and writes a bunch of files to an epub folder
• another that writes LaTeX chapters (ready to compile) to a latex folder?

[azerupi]

Yes, that's the idea. :)

[azerupi]

@gambhiro I have updated the first post because I noticed that I hadn't written down my thoughts about this part yet. I hope this clarifies some things. :)

[gambhiro]

It seems the key here is to design the data flow between:

• the summary parser
• book struct representation
• renderers processing for different targets (renderer specific structs?)
• page templates

Remembering that a new renderer will probably want to store more data (in the summary? in a renderer specific file?) -- and that data has to make it to the page templates somehow.

[Michael-F-Bryan]

I believe the majority of this will be implemented in #507, so this issue can be closed when that gets merged. The mechanism used for backends is also documented as part of the user guide (rendered).