Line Break
Sometimes we like to begin a new line without starting a whole new text block. Placing such a hard-line break gets complicated when hard-line wraps determine the line length inside the Markdown content files.
Syntax
There are two ways to place intentional hard-line breaks, which depend on the way we handle hard-line wraps.
- CommonMark
- allows hard wraps — a. k. a. hard-line breaks — to limit the line length. They are treated just like spaces. Therefore, CommonMark needs a special syntax element for an intentional line break.
- GitHub
- instead, treats hard-line breaks simply as such. In this case, we should probably enable soft wraps in our editor to limit the line length and avoid horizontal scrolling. (See also: Writing Markdown)
The CommonMark Way
Hugo’s standard configuration is fully CommonMark-compliant, the parameter hardWraps is set to false by default. There are two ways now, to place an intentional line break:
- Two spaces
- before the end of a line.
- One backslash
\ - directly after the text and before the end of the line.
Both options are error-prone. Spaces before the end of the line are usually invisible in text editors and get easily deleted by accident. The backslash is visible, but if there’s only one additional space character between the backslash and the also invisible newline character, the backslash is treated literally. And we get a visible \ instead of a newline on the page.
The GitHub Way
To format line breaks like GitHub, we need to set hardWraps to true, as in the configuration for this project. Now, the syntax becomes intuitive:
- Hard line breaks
- break lines hard.
If we change the line-breaking from CommonMark’s way to GitHub’s, Hugo still recognizes the CommonMark breaks. We don’t need to replace them. But we need to remove simple breaks because they are now all treated as intentional ones.
What now?
When you have to strictly adhere to the CommonMark specification the best option from my point of view is still, to forgo hard wraps and use CommonMark breaks. This way is compatible with CommonMark and GitHub.
When you are allowed to deviate from CommonMark regarding this one element, I strongly recommend the GitHub way. (See also: Writing Markdown)
Layout
There shouldn’t be any difference in the rendered result. You need to check the file content/doc/basic/linebreak/index.md to see the different syntax options in the Markdown content.
Line Break
As quirky joke, chefs won’t pay devil magic zebra tax.
GQ jock wears vinyl tuxedo for showbiz promo. BlewJ’s computer quiz favored proxy hacking.
Two spaces
Quirky spud boys can jam after zapping five worthy Polysixes.
Just poets wax boldly as kings and queens march over fuzz. Kvetching, flummoxed by job, W. zaps Iraq.
Backslash
A very bad quack might jinx zippy fowls.
Battle of Thermopylae: Quick javelin grazed wry Xerxes. Sphinx of black quartz, judge my vow!