Back to TILs.

Calmcode TIL

Code Diffs with Color in Markdown logoCode Diffs with Color in Markdown

Let's say that you're working on a guide on how to contribute to an open-source package. Then you may want to emphesize a good practice against a bad one. It turns out that if you use Github, there's a nifty trick that you can pull off in their codeblocks.

Here's an example of a codeblock that you could write:

- def func(some_arg: dict) -> None:
+ def func(some_arg: Dict[str, Any]) -> None:

Here's what it would render:

To write these diff blocks make sure that you:

  • annotate the codeblock on top with diff
  • start each red line with -
  • start each green line with +

Found in the Wild

It's a very neat trick that really makes a shine. I first saw it when I was exploring the developer docs for spaCy on GitHub. It's a great read, not only because of the concent but also because of the presentation.


If you're interested in more markdown tricks then you may also enjoy our readme course.

Back to TILs.