06 Basic Markdown and text formatting

6Basic Markdown and text formatting

This section lists all the Basic Markdown syntax for formatting text. This stuff is supported by (virtually) every Markdown processor.

It lists the Markdown syntax, the equivalent HTML (where possible) and shows the resultant output as rendered on GitHub.

In some cases there are alternative syntax options. I list these alternatives where they exist, but the main syntax (not the alternative options) is generally the preferred option.

⬆️ Top

6.1Body text and fonts

Body text in Markdown is whatever text is on a line that is not formatted by some other instruction. The following paragraph is body text and is rendered in the main GitHub Wiki window as shown below:

_{🔽🔽🔽🔽🔽🔽 Standard body text on a GitHub Wiki page below 🔽🔽🔽🔽🔽🔽}

Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam faucibus. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque placerat orci aliquam, eu sodales dui blandit. Maecenas nec risus vel magna blandit euismod. Suspendisse id finibus purus. Nam ultricies non sapien ac rutrum.

^{🔼🔼🔼🔼🔼🔼 Figure 6.1 — Body text on a GitHub Wiki page above 🔼🔼🔼🔼🔼🔼}

The GitHub site is responsive in terms of screen width and sidebar (the sidebar drops to the bottom of the page at lower resolutions), the text narrows and line-wraps as the screen narrows. It does not however, change point size.

Note

GitHub body text is always 16px high and is in the Segoe UI font, (pronounced seg-o-ee) on a Windows machine. The line spacing is fixed at 24 px (giving a line spacing of 150% which is a bit big; most body text has line spacing in the range 120-145%).

The font colour is a dark grey colour (not black), it is the colour rgb(31, 35, 40) or hex colour #1F2328. It looks like this:

^{Figure 6.2 — Body text font colour}

⬆️ Top

6.1.1Body text responsive design

GitHub displays the body text in a responsive manner. At browser screen widths of 1280 px or more, the main area of the screen is shown at a full width that never exceeds 896 px (this is as wide as it gets). At this width, the body text displays an average of 21.2 words per line (this is based on the following extract):

Body text extract for metrics

In principle, liquid rocket engines are simple, far simpler than the internal combustion engine. Liquid fuel is pumped into a combustion chamber in the presence of liquid oxygen and a flame. It burns. That’s all there is to it. There are no crankshafts to turn, no pistons to drive. The burning fuel produces energy in the form of gases that exit through the rocket’s nozzle. The force the gases produce against the top of the engine is called thrust. The thrust is transmitted through the rocket’s structure and, if it is greater than the weight of the rocket, the rocket lifts off. Put in its most basic terms, for any rocket to work there are two things that must be done extremely well: The propellants must be brought together, and then they must burn smoothly. In the F-l, just pumping the propellants to the combustion chamber raised unprecedented demands. The F-l used liquid oxygen (LOX) and R.P.-1, a form of kerosene. The pumps, one for the fuel and one for the LOX, had to deliver the kerosene from the tankage to the combustion chamber at the rate of 15,741 gallons per minute, and the LOX at the rate of 24,811 gallons per minute. Driven by a 55,000-horsepower turbine, the pumps had to operate at drastically different temperatures: 60 degrees Fahrenheit for the fuel, –300 degrees for the LOX, while the turbine itself ran at 1,200 degrees. To complicate matters, the whole assembly had to be light and compact enough to fit on board the rocket and nonetheless sturdy enough to resist the pressures, vibrations, and other stresses of launch and flight. Developing the pumps was still not as hard as solving the second basic problem of rocket engines: making the propellants burn smoothly once they had reached the combustion chamber. The pumps brought the kerosene and the LOX to a circular metal slab three feet in diameter and about four inches thick, weighing 1,000 pounds, called the injector plate. The injector plate was pocked with 6,300 holes less than a quarter of an inch in diameter through which the kerosene and LOX entered the combustion chamber. Most of the propellant streams were arranged in groups of five. Two of the five, both kerosene, impinged on each other at a carefully defined distance below the top of the plate, forming a fan-shaped spray. The other three in each five-hole group were of LOX. These also impinged on one another, forming another fan. The two fans intersected. There, given the presence of a flame, they would combust. In the F-l, the combustion chamber was a barrel about thirty-six inches wide and thirty inches long, closed at one end by the injection plate and opening into a nozzle at the other end. A few seconds before ignition, four small pre-burners in the combustion chamber — pilot lights, in effect — were lit, providing a flame at the point of impingement. As the pumps screamed up to speed, valves snapped open and more than a ton of kerosene and two tons of liquid oxygen burst into the combustion chamber. Per second. The gases produced by their ignition roared out through the throat, the open bottom of the barrel, into the cone of the nozzle below. In the course of the few seconds from ignition to full power (mainstage), the interior of the combustion chamber went from ambient temperature to 5,000 degrees Fahrenheit. At the face of the injector plate, pressure went from zero to 1,150 pounds per square inch. Given that combination of propellants, pressures, and nozzle design, the force generated totalled 1.5 million pounds. In the first stage of a Saturn V, five F-l s were to ignite simultaneously and sustain mainstage combustion for 150 seconds.

This is an extract from “Race to the Moon”: Cox, Catherine Bly & Charles Murray (1989). Published by Simon and Schuster. There is a Kindle version by the same authors, but it is just called Apollo.

Below is a series of lowercase alphabets, also used for page metrics:

abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz

Taking the first 29 lines of the above extract (these are complete lines and end with the phrase “to ignite simultaneously and sustain”), the metrics are:

^{Table 6.1 — GitHub body text metrics}
Average number of words per line:	21.2
Average number of characters per line:	123 (including spaces)
Lowercase alphabets:	5.4 (without spaces)

By most publishing standards, these figures are way too high, the lines are too long for comfortable reading.

Some good rules of thumb are: to have between 9.5 to 15 words per line, this equates to 45-90 characters per line (including spaces) or between 2-3 lowercase alphabets (without spaces).

While it may be too high, we are however, stuck with it. GitHub determines these things.

⬆️ Top

6.1.2Body text in sidebars and footers

Both sidebars and footers can have body text within them. Body text in sidebars and footers is smaller than that in the main window.

Note

GitHub sidebar and footer body text is always 12 px high (as opposed to 16 px in the main body text) and has a line spacing of 18 px (main body text line spacing 24 px) or 150% (this is the same ratio as main body text).

⬆️ Top

6.1.3Body text Markdown rules

	^{List 6.1 — Body text Markdown rules}
❶	GitHub will ignore multiple consecutive spaces (it will treat them as a single space)
❷	Always leave a blank line between paragraphs (section 6.2)
❸	Multiple blank lines will be ignored (treated as a single blank line, see section 6.2)
❹	Never use the tab character

GitHub always ignores multiple spaces (unless they’re at the end of a line in which case it can be treated as a line break, see section 6.2.2).

GitHub always ignores multiple blank lines (it acts as if there is only one blank line, section 6.2).

Tab characters are at best ignore and at worst convert text into a code fragment, see section 13.

⬆️ Top

6.1.4Body text examples

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
In principle, liquid rocket engines are simple, far simpler than the internal combustion engine.
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<p> In principle, liquid rocket engines are simple, far simpler than the internal combustion engine.</p>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
In principle, liquid rocket engines are simple, far simpler than the internal combustion engine.
^{Table 6.2 — Body text examples}

⬆️ Top

6.1.5Alignment of Body text

Markdown does not allow for the alignment of body text, it does however support HTML alignments with the use of the align attribute:

Left aligned text (default)

This is the default arrangement, text is at the left-hand side of the body text area.

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<p align="left">Align text to the left</p>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque placerat orci aliquam, eu sodales blandit. Maecenas nec risus vel magna blandit euismod. Suspendisse id finibus purus.

Right aligned text

Forces text to the right-hand side of the body text area.

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<p align="right">Align text to the right</p>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque placerat orci aliquam, eu sodales blandit. Maecenas nec risus vel magna blandit euismod. Suspendisse id finibus purus.

Centred text

Centres the text in the body text area.

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<p align="center">Centre the text</p>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque placerat orci aliquam, eu sodales blandit. Maecenas nec risus vel magna blandit euismod. Suspendisse id finibus purus.

Note

The American spelling of “center”

Justified text

Justifies the text in the body text area (the text is aligned with both margins of the page, giving it straight edges on both sides).

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<p align="justify">Justified text</p>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Lorem ipsum dolor sit amet, consectetur adipiscing elit. In consectetur tortor a tortor ornare, non pretium diam. Morbi ut mollis dolor, nec pretium tellus. Suspendisse ornare neque placerat orci aliquam, eu sodales blandit. Maecenas nec risus vel magna blandit euismod. Suspendisse id finibus purus.

⬆️ Top

6.1.6Body text properties

The following are the GitHub properties to applied body text:

MAIN WINDOW PROPERTIES	SIDEBAR AND FOOTER VARIATIONS
Font: Segoe UI Colour: `rgb(31, 35, 40) #1F2328` Font size: 16px Line spacing: 24px (150%) Underlined: No	Font: Segoe UI Colour: `rgb(31, 35, 40) #1F2328` Font size: 12px Line spacing: 18px (150%) Underlined: No
^{Table 6.3 — Body text properties}	^{Differences are in bold}

Note

These figures are for a Windows PC using a 2560 × 1560 monitor at native resolution, the browser is Edge set to a zoom of 100%. Where there are differences between the columns, these are highlighted in bold.

⬆️ Top

6.2Paragraphs and line breaks

Paragraphs and line breaks can be a bit hit and miss in Markdown.

Paragraphs must be separated by a blank line.

Multiple blank lines are treated as a single blank line; this can be seen below:

^{Markdown and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
Paragraph 1 Paragraph 2
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
Paragraph 1 Paragraph 2
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Paragraph 1 Paragraph 2
^{Table 6.4 — Separating paragraphs (multiple blank lines are ignored)}

Leaving out the blank line between paragraphs, causes the paragraphs to merge together:

^{Markdown and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
Paragraph 1 Paragraph 2
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Paragraph 1 Paragraph 2
^{Table 6.5 — Unseparated paragraphs}

In this example, GitHub effectively ignores the physical line break after Paragraph 1 (the actual line break cause by hitting the enter key).

⬆️ Top

6.2.1Forced line break

This is the correct mechanism for forcing a line break in Markdown.

To force a line break, use   at the end of the line where the break is to occur, the   can also be used within lines:

^{Markdown and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
Paragraph 1<br> Paragraph 2 Paragraph 3<br>Paragraph 4
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Paragraph 1 Paragraph 2 Paragraph 3 Paragraph 4
^{Table 6.6 — Standard_Markdown_HTML_Output_table}

Using   forces the text following onto the next immediate line (there is no blank line in-between). In the above example, the blank line between paragraphs 2 and 3 is because there is a blank line in the Markdown.

The   can be used consecutively to give the spacing required (they are not ignored like blank lines).

⬆️ Top

6.2.2Blank line and a line break

This is a bit odd, and I haven’t seen it mentioned anywhere else.

There is a difference between leaving a blank line to separate paragraphs and using   forced line breaks.

Using one   forces the text following onto the next

^{Markdown and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
Text line 1 <br> Text line 2 (forced break above)
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

^{Table 6.7 — A single <br>}

In the GitHub output above, I’ve shown the actual output on the right-hand side, the left side (highlighted in blue) with the dotted orange line and Text Line shows the standard line spacing used by GitHub (this is the line spacing if a line wraps around at the edge of the screen, just like this paragraph).

It can be seen that using a single   simply forces the text onto the next line (as you would expect).

In the next example, there are two   line breaks:

^{Markdown and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
Text line 1 <br><br> Text line 3 (2 x forced breaks above)
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

^{Table 6.8 — A double <br>}

As expected, there is now a blank line in the middle. The top-line (on the right) is in line with the first line of text (on the left) and the bottom-line lines up with the third line of text and there is a blank line in the middle. All well and good.

Now look at this, this is Markdown with a blank line separating the paragraphs:

^{Markdown and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
Text line 1 Text line 3 (blank line above)
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

^{Table 6.9 — A blank line between paragraphs}

The blank line does not put in the spacing of a full blank line (it is actually ⅔ of a blank line).

So what does this mean?

Well, it means that normal paragraph spacing created by leaving a blank line between paragraphs, cannot be replicated by forced line breaks, one line break is not big enough, two is too big.

The HTML  tag does produce the correct paragraph spacing (same as a blank line):

^{HTML and GitHub output}
${\large \color{#B00000}\text{H\ T\ M\ L}}$ 🔽
<p>Text Line 1</p> <p>Text Line 3 (HTML paragraphs)</p>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

^{Table 6.10 — HTML paragraphs}

⬆️ Top

6.2.3Trailing space line break

It is a feature of Markdown that two trailing spaces at the end of a line will force a line break.

${\LARGE \color{#c00000}\text{DO\ NOT\ USE\ TRAILING\ SPACE\ LINE\ BREAKS}}$

It is hard to see two spaces at the end of a line (they don’t show up in most editors), The following shows how it works:

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
Paragraph 1 Paragraph 2
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Paragraph 1 Paragraph 2
^{Table 6.11 — Trailing space line break}

⬆️ Top

6.2.4Paragraph and line break Markdown rules

	^{List 6.2 — Paragraph and line break Markdown rules}
❶	Always leave a single blank line between paragraphs (multiple blank lines have no effect) or use HTML `<p>` tags
❷	Do not indent paragraphs at all (tabs will be misinterpreted, multiple spaces will be treated as single space)
❸	Always use `<br>` to force a line break
❹	Do not use trailing space line breaks

⬆️ Top

6.2.5Paragraph and line break examples

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
Lorem ipsum Consectetur.	Lorem ipsum<br> Consectetur.	Lorem ipsum<br><br> Consectetur.
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<p>Lorem ipsum</p> <p>Consectetur</p>	<p>Lorem ipsum<br>Consectetur</p>	<p>Lorem ipsum<br><br>Consectetur</p>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Lorem ipsum Consectetur	Lorem ipsum Consectetur	Lorem ipsum Consectetur
^{Table 6.12 — Paragraph and line break examples}

6.3Horizontal line

Horizontal lines (sometimes called “rules”) are thick grey lines that span a Markdown page indicating some form of break. The also act as line breaks (see section 6.2.1).

Horizontal lines are created using three or more asterisks ***, dashes --- or underscores ___. That said, the best way to create a horizontal lines is to use the <hr> tag, this has become the standard.

If using three dashes, make sure it is surrounded by blank lines, if there is any text on the line immediately above, it will be turned into a heading (see section 6.10)

The following are all horizontal lines:

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
*** --- ___ <hr>
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<hr>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

^{Table 6.13 — Horizontal lines}

⬆️ Top

6.3.1Markdown rules for horizontal lines

	^{List 6.3 — Markdown rules for horizontal lines}
❶	Use the `<hr>` tag for horizontal rules
❷	Always put a blank line after the `<hr>`

Note

Always put a blank line after the <hr>, this evens up the spacing around the horizontal line. The difference is shown below:

^{Markdown, HTML equivalence and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
Text Linea <hr> Text Line	Text Line <hr> Text Line
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
Text Linea Text Line	Text Line Text Line
^{Table 6.14 — Horizontal lines with and without a blank line after}