writing markdown diffs and adventures in open-source



~2 min read


286 words

Back in January of 2020, I opened a ticket about diff highlighting with PrismJS and Gatsby. (The ticket itself came out of research I was doing for how to take advantage of syntax highlighting with PrismJS in Gatsby.) Nearly a year and a half later, I woke up to an email saying someone had decided to take on the problem and solve it. How cool is that!?

Sure, if it had been urgent or important, I might have been forced to go with a different solution or build one myself. But it wasn’t. So, I asked a question, I inspired someone else (Jon Sully in this case) to come up with a solution and the whole community benefited! I haven’t been able to participate in open source work as much as I would like lately, so this was a really nice reminder about some of the benefits from doing so.

Even better, not only do I get to learn by reviewing his code, but I learned the appropriate way to write a Diff in Markdown:

Canonically, when writing code diffs, the code should be indented by two characters. If the code is being changed, the first character should be a +, -, or ! otherwise left a space. The second character should always be a space. Git-style file-location coordinates need not be indented.1

@@ -4,6 +4,5 @@
  const doTheThing = aParm => {
+   console.log(`Parm is: ${aParm}`)
-   console.log('Hit this function')
!   console.log('Rubber duck > debugging anybody?')
    return true



Hi there and thanks for reading! My name's Stephen. I live in Chicago with my wife, Kate, and dog, Finn. Want more? See about and get in touch!