06 Basic Markdown and text formatting

F

6. Basic 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.1. Body text and fonts

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

^{Figure 6.1 — Body text on a GitHub Wiki page}
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.

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 (on a Windows machine). The line spacing is fixed at 24px (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 in fact the RGB colour (31, 35, 40) or hex colour (#1F2328). It looks like this:

^{Figure 6.2 — Body text font colour}

⬆️ Top

6.1.1 Body text responsive design

GitHub displays the body text in a responsive manner, at browser screen widths of 1280px or more, the main area of the screen is shown at a full width that never exceeds 896px (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 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 for line lengthe are:

^{Table 6.2 — Rules for line length}
● 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.2 Body 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 12px high (as opposed to 16px in the main body text) and has a line spacing of 18px (main body text line spacing 24px) or 150% (this is the same ratio as main body text).

There is no difference between body text in sidebars and in footers it is exactly the same.

⬆️ Top

6.1.3 Body text Markdown rules

^{Table 6.2 — 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 (see section xxx) ❸ Multiple blank lines will be ignored (treated as a single blank line) ❹ Never use the tab character

⬆️ Top

6.1.4 Body text examples

MARKDOWN	HTML	GITHUB OUTPUT
In principle, liquid rocket engines are simple, far simpler than the internal combustion engine.	`<p>In principle, liquid rocket engines are simple, far simpler than the internal combustion engine.</p>`	In principle, liquid rocket engines are simple, far simpler than the internal combustion engine.
^{Table 6.3 — Body text example}

⬆️ Top

6.1.5 Alignment of Body text

Markup does not allow for the alignment of body text (it is always left justified), it does however support HTML alignments:

Left aligned text (default)

<p align="left">Align text to the left</p>

This is the default arrangement, text is at the left-hand side of the body text area, like this:

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.

Right aligned text

<p align="right">Align text to the right</p>

Will force text to the right-hand side of the body text area, like this:

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.

Centred text

<p align="center">Center the text</p>

Will centre the text in the area, like this:

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.

Note the Americanised spelling of "Center".

Justified text

<p align="justify">Justify the text</p>

Will justify the text in the area, like this:

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.

⬆️ Top

6.1.6 Body text properties

	MAIN WINDOW PROPERTIES	SIDEBAR AND FOOTER VARIATIONS
Body text	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.4 — Body text properties}

^{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% (default setting).
Where there are differences between the columns, these are highlighted in bold.}

⬆️ Top

6.2. Paragraphs and line breaks

Paragraphs and line breaks can be a bit hit and miss in Markdown; the following explains both:

6.2.1 Paragraphs

Within Markdown, paragraphs have to be separated by a blank line, the following (on the left) will form two separate paragraphs (shown on the right):

MARKDOWN (with line numbers)	GITHUB OUTPUT
1 Paragraph 1 2 3 Paragraph 2	Paragraph 1 Paragraph 2
^{Figure 6.3 — Separate paragraphs}

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

MARKDOWN (with line numbers)	GITHUB OUTPUT
1 Paragraph 1 2 Paragraph 2	Paragraph 1Paragraph 2
^{Figure 6.4 — Not separate paragraphs}

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

Note

GitHub will ignore multiple blank lines; it will consider multiple blank lines to be the same as a single blank line between paragraphs.

⬆️ Top

6.2.2 Forced 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 (with line numbers)	GITHUB OUTPUT
1 Paragraph 1<br> 2 Paragraph 2 3 4 Paragraph 3<br>Paragraph 4	Paragraph 1 Paragraph 2 Paragraph 3 Paragraph 4
^{Figure 6.5 — Forced line break}

⬆️ Top

6.2.3 Trailing space line break

Caution

DO NOT USE THIS METHOD.

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

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 (with line numbers)	GITHUB OUTPUT
1 Paragraph 1∘∘ 2 Paragraph 2	Paragraph 1 Paragraph 2
^{Figure 6.5 — Forced line break (∘ indicates a space)}

Again, do not use this — use the   shown above (section 6.2.2):

⬆️ Top

6.2.4 Paragraph and line break Markdown rules

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

⬆️ Top

6.2.5 Paragraph and line break examples

MARKDOWN	HTML	GITHUB OUTPUT
Lorem ipsum. Consectetur elit.	<p>Lorem.</p><p>Consectetur elit.</p>	Lorem ipsum. Consectetur elit.
^{Table 6.6 — Paragraph examples}

MARKDOWN	HTML	GITHUB OUTPUT
Lorem ipsum.<br>Consectetur elit.	<p>Lorem ipsum.<br>Consectetur elit.</p>	Lorem ipsum. Consectetur elit.
^{Table 6.7 — Line break examples}

⬆️ Top

6.3. Emphasis with bold

Any text can be made bold by surrounding it with two asterisks (**) i.e.

MARKDOWN	GITHUB OUTPUT
The next word is in bold	The next word is in bold
^{Figure 6.7 — Bold text}

Bold can carry over between lines:

MARKDOWN	GITHUB OUTPUT
This is not in bold the rest of the line is in bold And so is this.	This is not in bold the rest of the line is in bold And so is this.
^{Figure 6.8 — Bold text across lines}

A double underscore can be used in exactly the same way

MARKDOWN	GITHUB OUTPUT
The next word is in __bold__	The next word is in bold
^{Figure 6.9 — Bold text using underscores}

Caution

DO NOT USE UNDERSCORES FOR BOLD.

The use of two underscore characters for bold in the middle of a word is misinterpreted by some Markdown applications, don’t use underscores, always use asterisks.

⬆️ Top

6.3.1 Markdown rules for bold

^{Table 6.8 — Markdown rules for bold}
❶ Surround the text that is to be in bold with two asterisks (\\) before and after ❷ Do not use double underscores (always use asterisks) ❸ Bold text can span lines

⬆️ Top

6.3.2 Bold text examples

MARKDOWN	HTML	GITHUB OUTPUT
Lorem ipsum dolor sit	<p>Lorem.<strong>ipsum</strong> dolor sit</p>	Lorem ipsum dolor sit
Lorem ipsum dolor sit Consectetur elit.	<p>Lorem.<strong>ipsum dolor sit</strong></p><p> <strong>Consectetur</strong> elit.</p>	Lorem ipsum dolor sit Consectetur elit.
^{Table 6.9 — Bold text examples}

⬆️ Top

6.4. Emphasis with italics

Any text can be made italic by surrounding it with a single asterisk (*) i.e.

MARKDOWN	GITHUB OUTPUT
The next word is in italics	The next word is in italics
^{Figure 6.10 — Italic text}

Italics can carry over between lines:

MARKDOWN	GITHUB OUTPUT
This is not in italics the rest of the line is in italics And so is this.	This is not in italics the rest of the line is in italics And so is this.
^{Figure 6.11 — Italic text across lines}

A single underscore can be used in exactly the same way

MARKDOWN	GITHUB OUTPUT
The next word is in _italics_	The next word is in italics
^{Figure 6.12 — Italic text using underscores}

Caution

DO NOT USE UNDERSCORES FOR ITALICS.

The use of underscore characters for italics in the middle of a word is misinterpreted by some Markdown applications, don’t use underscores, always use asterisks.

⬆️ Top

6.4.1 Markdown rules for italics

^{Table 6.10 — Markdown rules for italics}
❶ Surround the text that is to be in italics with an asterisk (\*) before and after ❷ Do not use double underscores (always use asterisks) ❸ Italic text can span lines

⬆️ Top

6.4.2 Italic text examples

MARKDOWN	HTML	GITHUB OUTPUT
Lorem ipsum dolor sit	<p>Lorem.<em>ipsum</em> dolor sit</p>	Lorem ipsum dolor sit
Lorem ipsum dolor sit Consectetur elit.	<p>Lorem.<em>ipsum dolor sit</em></p><p> <em>Consectetur</em> elit.</p>	Lorem ipsum dolor sit Consectetur elit.
^{Table 6.11 — Italic text examples}

⬆️ Top

6.5. Emphasis with bold and italics

Any text can be made both bold and italic by surrounding it with three asterisks (***) i.e.

MARKDOWN	GITHUB OUTPUT
This is both *bold and italic*	This is both *bold and italic*
^{Figure 6.13 — Bold and italic text}

Bold and Italic text can carry over between lines:

MARKDOWN	GITHUB OUTPUT
This is normal *the rest of the line is in bold and italics And so is this.*	This is normal the rest of the line is in bold and italics And so is this.
^{Figure 6.14 — Bold and italic text across lines}

It’s possible to split where bold and italic occur:

MARKDOWN	GITHUB OUTPUT
This is *bold bold and italics* just bold** This is italics bold and italics* just italics*	This is *bold this is bold and italic* just bold** This is italics this is bold and italics* just italics*
^{Figure 6.15 — Variations of bold and italic}

Three underscores can be used in exactly the same way as three asterisks:

MARKDOWN	GITHUB OUTPUT
This is both ___bold and italic__	This is both bold and italic
^{Figure 6.16 — Bold and italic text using underscores}

Caution

DO NOT USE UNDERSCORES FOR BOLD AND ITALIC.

The use of underscore characters in the middle of a word is misinterpreted by some Markdown applications, don’t use underscores, always use asterisks.

⬆️ Top

6.5.1 Markdown rules for bold with italics

^{Table 6.12 — Markdown rules for bold and italics}
❶ Surround the text that is to be in bold and italics with three asterisks (\\\*) before and after ❷ Do not use underscores (always use asterisks) ❸ Bold and italics text can span lines ❹ Bold and italics can be nested

⬆️ Top

6.5.2 Bold with italic text examples

MARKDOWN	HTML	GITHUB OUTPUT
Lorem *ipsum* dolor	<p>Lorem.<strong><em>ipsum</em></strong> dolor</p>	Lorem *ipsum* dolor
Lorem *ipsum dolor Consectetur* elit.	<p>Lorem.<strong><em>ipsum dolor</em></strong></p><p> <strong><em>Consectetur</em></strong> elit.</p>	Lorem *ipsum dolor* *Consectetur* elit.
^{Table 6.13 — Bold and italic text examples}

⬆️ Top

6.6. Emphasis with underlining

There is no direct support for underlining text in Markdown (nothing with asterisks or underscores), but it can be achieved with the use of the HTML inset tag: <ins>…</ins> or the or the underline tag: …^💠1tag.

MARKDOWN	GITHUB OUTPUT
The next word is <ins>underlined</ins> or <p>Lorem.<u>ipsum</u> dolor sit</p>	The next word is underlined
^{Figure 6.17 — Underlined text}

Unlike bold and italics, underlining cannot carry over between lines. Each line must be underlined individually

MARKDOWN	GITHUB OUTPUT
This is not underlined <u>the rest of the line is</u> <u>And so is this.</u>	This is not underlined the rest of the line is And so is this.
^{Figure 6.18 — Underlined text across lines}

Caution

Although both  and <ins> work in Wiki .md files, they do not work in repository Markdown files (for example the README.md file). Consequently, for compatibility, I recommend using the <ins> in place of .

Note

^💠1 Both  and <ins> tags underline the text. The difference between the tags is purely semantic, <ins> tells the browser that the content has been inserted after the site was first published (it has textual significance),  simply means that the text is underlined (for visual emphasis) and has no specific meaning in terms of textual content.↩

⬆️ Top

6.6.1 Markdown rules for underlining

^{Table 6.14 — Markdown rules for underlining}
❶ The first rule is don’t underline things. Ever! Underlined text can be confused as a link, plus it just looks bad ❷ Use a `<ins>` before the text that is to be underlined and a `</ins>` at the end ❸ `<u>` does not work in main repository Markdown files ❹ Underlining does not span blank lines

⬆️ Top

6.6.2 Underlined text examples

MARKDOWN	HTML	GITHUB OUTPUT
Not available	<p>Lorem.<ins>ipsum</ins> dolor sit</p>	Lorem ipsum dolor sit
Not available	<p>Lorem.<u>ipsum</u> dolor sit</p>	Lorem ipsum dolor sit
^{Table 6.15 — Underlined text examples}

⬆️ Top

6.7. Strikethrough text

Any text can be struck through by surrounding it with a double tilde (~~) i.e.

MARKDOWN	GITHUB OUTPUT
The next word has been ~~struck through~~	The next word is ~~struck through~~
^{Figure 6.19 — Strikethrough text}

Unlike bold and italics, strikethrough cannot carry over between lines. Each line must be struck through individually

MARKDOWN	GITHUB OUTPUT
This is not struck through ~~the rest of the line is~~; ~~And so is this.~~	This is not struck through ~~the rest of the line is~~ ~~And so is this.~~
^{Figure 6.20 — Strikethrough text across lines}

Strikethrough can also be achieved with the use of the HTML tags: <del>…</del> or <s>…</s>^💠2.

Note

^💠2 Both <s> and <del> tags strikethrough the text. The difference between the tags is purely semantic, <del> tells the browser that the content has been removed after the site was first published (it has textual significance), <s> simply means that the text has been struckthrough and has no specific meaning in terms of textual content.↩

⬆️ Top

6.7.1 Markdown rules for strikethrough

^{Table 6.16 — Markdown rules for strikethrough}
❶ Surround the text that is to be in struck through with two tildes (~~) before and after ❷ Strikethrough text cannot span lines

⬆️ Top

6.7.2 Strikethrough text examples

MARKDOWN	HTML	GITHUB OUTPUT
Lorem ~~ipsum~~ dolor sit	<p>Lorem.<s>ipsum</s> dolor sit</p> or <p>Lorem.<del>ipsum</del> dolor sit</p>	Lorem ~~ipsum~~ dolor sit
^{Table 6.17 — Strikethrough text examples}

⬆️ Top

6.8. Horizontal rules

Horizontal rules are thick, grey lines that span a Markdown page indicating some form of break.

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

Caution

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 xxx)

The following are all horizontal rules