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:

```diff
- 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 reamde.md 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.


Back to TILs.