Master Markdown Newline Rules for Web Writing

Markdown is a lightweight, accessible syntax for writing text on the web. It simplifies the document formatting process and makes writing robust text-based documents a breeze. This tutorial will delve into one of the most critical components of Markdown syntax—newline rules.

Introduction to Markdown

The foundation of good programming is a strong understanding of your tools, so before we get into newline rules, let's get everyone on the same page about Markdown. Introduced by John Gruber in 2004, Markdown allows you to format your texts without the need for tags as in HTML. Its syntax is precise and straightforward, making it a tool of choice for developers, engineers, and technical writers alike.

The Essence of Newline Rules in Markdown

Basic Markdown Newline Rule

In most raw text formats, such as programming languages, a newline character is considered as an end of a line, but not in Markdown. In Markdown, if you want to insert a line break, you must end a line with two spaces before hitting Return or Enter.

Here is what the rule looks like in action:

This is a line with a line break.  
This is the second line.

Expected output:

This is a line with a line break.
This is the second line.

Paragraphs in Markdown

If you want to insert a blank line, i.e., start a new paragraph in Markdown, you do it by pressing Enter twice—this will begin a new line with a clear separation.

Here is what it looks like:

This is the first paragraph.

This is the second paragraph.

Expected output:

This is the first paragraph.

This is the second paragraph.

Exceptions to the Rule: Markdown Flavors

Remember, there are multiple implementations of Markdown, known as "flavors," some of which behave differently from one another. Some common flavors include GFM (Github Flavored Markdown), CommonMark, and Markdown Extra.

GFM and CommonMark Newline Rule

Both GFM and CommonMark, implemented on sites like GitHub and Reddit, introduced a slight change to the newline rule. In these flavors, a singular newline does create a new line without the necessity for the appended two spaces.

Here's how it looks in CommonMark/GFM:

This is a line with a line break.
This is the second line.

Expected output:

This is a line with a line break.
This is the second line.

Why These Rules Matter

Debates about newline rules aren't just syntax squabbles. They have a substantial impact on the legibility and formatting of your Markdown documents, especially when designing documentation for complex software. Correct usage of newline rules can ensure your text is cleanly formatted and can improve readability.

Wrapping Up

Markdown's newline rules, though simple, are fundamental to mastering this versatile syntax. Remember to always be aware of the flavor of Markdown you're working with to ensure correct application of the newline rule. As with any tool, the best way to become proficient with Markdown's newline rules is through continued use, so get out there and start practicing!

Three Ways to Force a Line Break

If a single Enter press does not give you a new line, you have three options:

Two trailing spaces at the end of the line. This works everywhere but is invisible, and many editors strip trailing whitespace on save, which silently breaks it.
A backslash at the end of the line. This is part of CommonMark and GitHub Flavored Markdown, and it survives editors that trim whitespace. Not every older renderer supports it.
An HTML <br> tag. The most portable choice where raw HTML is allowed, and the only one that works inside a table cell.

A blank line between two blocks of text starts a new paragraph rather than a line break, which usually adds more vertical space.

Platform Differences

Whether a single newline becomes a visible line break depends on where the text is rendered. GitHub treats it as a line break in issue and pull request comments, but not in README and other repository files. Slack and Discord keep single newlines as typed. Jekyll, Hugo and most documentation generators follow the standard and join the lines into one paragraph. If your Markdown looks right in one place and wrong in another, that is usually the cause. Our guide on why your Markdown isn't rendering covers how to identify which renderer you are dealing with, and the Markdown Editor lets you test a snippet and see the result immediately.

Related reading: forcing a line break and the Markdown Linter, which flags trailing spaces and repeated blank lines.