Compatibility with mdbook #

This page is not meant as a direct comparison of mdbook and romero, but rather what should work out-of-the box and what does not for an user that wants to migrate from mdbook.

This document use the following pictograms:

• ✅: Complete support
• ⚠: Partial support
• ❌: Not supported

Main features #

HTML Render #

Notable differences with mdbook #

romero is slower to build #

See the syntax highlighting section below.

Syntax highlighting #

By default, romero will compute and highlight code blocks at build time rather than relying on client-side computing at runtime. This results in longer default build times with romero:

# For the rust-lang mdbook
$> time romero build
romero build  4.34s user 0.07s system 104% cpu 4.228 total
$> time mdbook build
mdbook build  0.46s user 0.13s system 94% cpu 0.619 total

This romero behavior can be changed by modifying the following configuration:

[output.html]
highlight-type = "highlightjs"

Which will stop computing the highlights at build but rather client-side at render. This will results in significantly faster build time:

# Still rust-lang, but with highlight-type = "highlightjs"
$> time romero build
../../romero build  0.46s user 0.06s system 132% cpu 0.390 total

Breaking changes with mdbook #

output.html.edit-url-template #

The following default will not work with romero:

[output.html]
edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}"

Due to the way templating works in golang and in rust. The former should be changed to this:

[output.html]
edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{{ . }}"