marking up

unified diffs

and styling them

When rendering diffs as web content, most websites put a light red background on removed text, and additions get a light green background. Often, specific changed bits within those regions stand out with darker red or green backgrounds.

Listing 1: a diff
diff --git a/Makefile b/Makefile
index 3d44f79..ddcc50b 100644
--- a/Makefile
+++ b/Makefile
@@ -1,9 +1,12 @@
 # -*- makefile-gmake -*-

-.PHONY: all clean distclean html install installdirs uninstall
+.PHONY: all clean distclean docs install installdirs view-docs uninstall

 SHELL = /bin/sh

okay, but what should

the markup

look like?

A diff is a kind of code listing, and we mark up code listings with the <pre><code class=lang>…</code></pre> pattern. In this case, lang is "diff".

Of course, we use the <ins> and <del> elements to mark the additions and removals, respectively. But how should we mark up the specific changes within each <ins> or <del>? Well, HTML’s <mark> element has more or less exactly the semantic we’re looking for:

The mark element represents a run of text[…] marked or highlighted for reference purposes[…]. [It] indicates a highlight[…] which has been added to bring the reader's attention to a part of the text[…].

Putting it all together, this is what the markup for Listing 1 looks like:

Listing 2: the markup
<pre><code class=diff>diff --git a/Makefile b/Makefile
index 3d44f79..ddcc50b 100644
--- a/Makefile
+++ b/Makefile
@@ -1,9 +1,12 @@
 # -*- makefile-gmake -*-

<del>-.PHONY: all clean distclean <mark>html </mark>install installdirs uninstall</del>
<ins>+.PHONY: all clean distclean <mark>docs </mark>install installdirs <mark>view-docs </mark>uninstall</ins>

 SHELL = /bin/sh</code></pre>

let’s

style

this stuff

Styling this sort of thing is super straightforward.

By default, <del> gets a strike-through and <ins> an underline. Let’s disable that with text-decoration: none.

Listing 3: remove text decorations

After that, all we need to do is provide background colors.

Listing 4: color those backgrounds