Glorified Plumbing

I write a lot. Personal letters and postcards are written using pen and paper. Work documents are mostly typed in Markdown, often within a Git repository. Markdown is a fast, clean way to compose text.

As we update our technical docs, we put them through a review cycle much as we do with our code. We are interested in the flow and accuracy of the whole document, but the key focus is on the changes.

Diffing Markdown

Diffing two versions of a Markdown file will result in line-by-line comparisons. When I type in MS Word or WordPress I only hit [ENTER] at the end of a paragraph. Okay, on some computers, that’s [RETURN]. That signifies a paragraph break to the tool.

The result of this style of editing is that every paragraph is delineated by a single line end marker. In a Git repository, diffs are line-based. You end up comparing paragraphs. These are very long lines. Depending on how you render your diffs, you will either have to pan a long way right to find changed words or sentences, or the diffed paragraphs will wrap, and changes may not appear aligned side-by-side in your viewer.

To limit the scope of your diff, you can use semantic line breaks in several document file types.

• Markdown
• LaTeX
• AsciiDoc
• reStructured

As I said before, I use Markdown. If I use a single vertical whitespace (press enter once), the source text is shown on a new line, but the rendering in the final format will not. To force a paragraph break, I just add a blank line between.

The final document, using a markdown viewer (built into GitHub for example), or processed by a tool like Pandoc (a publishing tool that can convert text formats), will render nicely in paragraphs. The source text will diff easily, each sentence (or shorter if you wish) handled as a unit.

Non-standard Markdown

I was enjoying this feature until last night when something tripped up one of my GitHub files in GitBook. I am maintaining my pages on GitHub, and it auto publishes a branch to GitBook.

The Engineer’s Notebook I am building has a new Best Practices chapter about Coding Standards. It’s formatted like all my other pages, using semantic line breaks. But GitBook is placing each line on a line. It’s not seeing paragraph breaks, though. A paragraph should have a specific spacing, which can be seen where I put a double newline. I did finally take the semantic line brakes out of this file.

This is using the previewer in VSCode where semantic line breaks are understood.

I then changed the setting for enhanced preview.

The result was how I saw it in GitBooks.

I tried a web search and a ChatGPT session to try and work out why this was the first page to render this way. ChatGPT came up with a response about how the tool was trying to render it in a poetic way, based on sentence length in the first paragraph. That sounded like a hallucination. I have not found evidence one way or the other.

What the Internet Says

This morning, I did a bit more looking into it and found a page that feels informative, or at least definitive. https://sembr.org links to a page that discusses semantic breaks. I think it describes common attributes, and then has a call to action to unify the behavior; or at least that’s my take on it.

A few years ago, a colleague introduced me to semantic line breaks in the context of diffing README.md files. I learned the how and why together. In last night's searching, I found someone who only half knew the why. Their post (and its responses) highlight the perils of navigating different dialects of Markdown.

What GitBooks Support Said

Thank you for your message and patience here so far.

Our team is aware of this and we are looking into this on our side.
I’ll keep you posted on the progress.

and then later

Thank you for your message and patience here so far.

Our team has issued a fix for this and you should now be able to work this out. Can you confirm if the line breaks are now working as expected?

Summing Up

This was just meant to be a short post, and I think I said all I wanted to say. To recap

• Semantic Line Breaks are a convenience to break paragraphs into smaller blocks for you and your computer to work with.
  • Easier for diffs
  • Easier to focus on
• Mostly do not disrupt paragraph print formatting and style.
  • Not all Markdown viewers agree on dialect
• GitBook is great when hooked up to GitHub, until it isn’t.
• ChatGPT is a great tool, but I still don’t trust it all the way.

So, what are your thoughts on Markdown? Have you tripped up on anything when moving your Markdown to other platforms or tools? Do you use semantic line breaks, and if so, what is your motivation?

I look forward to your comments and questions.

---

Post script

Thanks to a comment from someone at InnerSource, I followed up on the GitBook issue. It was an acknowledged bug that has since been resolved. The fix came within a week or so. I’m happy again.