Showing diffs in the mdbook

announcements
1

I am working on a project using mdbook, and I was thinking that instead of showing code examples, it would be cool to show diffs instead.

My main requirement was syntax highlighting for the code as well as for the changes.

I tinkered with different approaches:

  1. One of them was generating diffs in terminal using tools like delta and difftastic and then converting them from ANSI to HTML. This would have involve creating an mdbook preprocessor, but I was not fully satisfied with results.

  2. mdbook uses highlight.js for syntax highlighting. And I've found a small library that does exactly what I need: highlightjs-code-diff. There was some problem with language detection: something with the need to update the regex inside the highlight.js code. It was totally doable, but I already found diff2html and I liked its output more.

  3. Finally, I decided to use diff2html. And here is the result:
    GitHub - romamik/mdbook-diff2html: Embed diff2html into mdbook
    Screenshot

There are two issues I know:

  1. For a short period, the diff is shown as plain text before being converted to the diff2html elements.
  2. The dark/light themes are working according to system settings and are not synchronized with the mdbook theme.

But I am quite happy with the result anyway.