94 Headings, links and contents

93.    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

93.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:

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 93.1 — Body text on a GitHub Wiki page

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.

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 93.15 — Body text font colour

⬆️ Top

93.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 on average 21.2 words per line (this is based on the following extract):

---

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.

---

abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz

---

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.

In calculating the metrics for GitHub, a browser screen width in excess of 1280 pixels is assumed (i.e. the main window is at its full width).

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:

Average number of words per line:	21.2
Average number of characters per line:	123 (including spaces)
Lowercase alphabets:	5.4
Table 93.1 — GitHub body text metrics

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

93.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.

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 they are exactly the same.

⬆️ Top

93.1.3       Body text Markdown rules

1. GitHub will ignore multiple consecutive spaces (it will treat them as a single space)
2. Always leave a blank line between paragraphs (see below)
3. Multiple blank lines will be ignored (treated as a single blank line)
4. Never use the tab character

⬆️ Top

93.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 93.2 — Body text example

⬆️ Top

93.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:

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

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

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

Will centre the text in the area, like this.

⬆️ Top

93.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 93.3 — Body text properties

⬆️ Top

---

93.2.       Paragraphs and line breaks

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

93.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 93.16 — Separate paragraphs

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

/td>

MARKDOWN (with line numbers)	GITHUB OUTPUT
1   Paragraph 1 2   Paragraph 2	Paragraph 1Paragraph 2
Figure 93.17 — 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

93.2.2       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 93.5 — Trailing space line breaks
∘ indicates a space

⬆️ Top

93.2.3       Forced line break

This is the correct mechanism for forcing a line break in Markdown. To force a line break, use <br> at the end of the line where the break is to occur, the <br> 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 93.18 — Forced line breaks

⬆️ Top

93.2.4       Paragraph and line break Markdown rules

1. Always leave a single blank line between paragraphs (multiple blank lines have no effect)
2. Do not indent paragraphs at all (tabs will be ignored, multiple spaces will be treated as single space)
3. Always use <br> to force a line break
4. Do not use trailing spaces to force a line break

⬆️ Top

93.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 93.4 — Paragraph examples
Lorem ipsum.<br>Consectetur elit.	<p>Lorem ipsum.<br>Consectetur elit.</p>	Lorem ipsum. Consectetur elit.
Table 93.5 — Line break examples

⬆️ Top

---

93.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 93.19 — 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 93.20 — Bold text

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 93.21 — Bold text

Caution

DO NOT USE THIS METHOD.

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

93.3.1       Markdown rules for bold

1. Surround the text that is to be in bold with two asterisks (**) before and after
2. Do not use double underscores (always use asterisks)
3. Bold text can span lines

⬆️ Top

93.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 93.6 — Bold text examples

⬆️ Top

---

93.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 93.22 — 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 93.23 — italic text

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 93.24 — italic text

Caution

DO NOT USE THIS METHOD.

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

93.4.1       Markdown rules for italics

1. Surround the text that is to be in italics with an asterisk (*) before and after
2. Do not use underscores (always use asterisks)
3. Italic text can span lines

⬆️ Top

93.4.2       Italic text examples

MARKDOWN	HTML	GITHUB OUTPUT
Lorem *ipsum* dolor sit	<p>Lorem.<em>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 93.7 — Bold text examples

⬆️ Top

---

93.5.       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 tag <u>…</u>.

MARKDOWN	GITHUB OUTPUT
The next word is <u>underlined</u>	The next word is underlined
Figure 93.25 — 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 93.26 — Underlined text

⬆️ Top

93.5.1       Markdown rules for underlining

1. The first rule is don’t underline things. Ever! Underlined text can be confused as a link, plus it just looks bad
2. Use a <u> before the text that is to be underlined and a </u> at the end
3. Underlining does not span blank lines

⬆️ Top

93.5.2       underlined text examples

MARKDOWN	HTML	GITHUB OUTPUT
Not available	<p>Lorem.<u>ipsum</u> dolor sit</p>	Lorem ipsum dolor sit
Table 93.8 — Underlined text examples

⬆️ Top

---

92.2.3       Headings

Headings are created by adding hash signs (#) in front of a word or sentence. The number of hashes indicates the level of the heading: a single # indicates a level 1 heading, ## a level 2 all the way down to ###### (six hashes) which is a level 6 heading.

The headings can also be constructed using the HTML tags <h1></h1> … <h6></h6>.

Headings are also covered in section xxx; this shows how headings are structured for the PracticalSeries Wikis and include a lot of information about spacing and numbering and generally making the headings look better.

Headings level 1 and 2 are underlined. Headings get progressively smaller

⬆️ Top

Heading Markdown rules

1. The first # must be at the start of a line
2. The last # in the group must be followed by a space (before the heading text)
3. All the text on the same line as the first # will form part of the heading
4. Best practice dictates that each heading should be preceded by a blank line (it makes the text easier to read)

⬆️ Top

Heading examples

MARKDOWN	HTML	GITHUB OUTPUT
# Heading level 1	<h1>Heading level 1</h1>	Heading level 1
## Heading level 2	<h2>Heading level 2</h2>	Heading level 2
### Heading level 3	<h3>Heading level 3</h3>	Heading level 3
#### Heading level 4	<h4>Heading level 4</h4>	Heading level 4
##### Heading level 5	<h5>Heading level 5</h5>	Heading level 5
###### Heading level 6	<h6>Heading level 6</h6>	Heading level 6
Body text for comparison	<p>Body text</p>	Body text
Table 92.6 — Headings examples

⬆️ Top

Heading properties

	MAIN WINDOW PROPERTIES	SIDEBAR AND FOOTER VARIATIONS
# Heading 1	Font: Segoe UI Colour: rgb(31, 35, 40) #1F2328 Font size: 32px Line spacing: 40px (125%) Underlined: Yes rgb(223, 228, 233) #DFE4E9	Font: Segoe UI Colour: rgb(31, 35, 40) #1F2328 Font size: 19.2px Line spacing: 24px (125%) Underlined: Yes rgb(223, 228, 233) #DFE4E9
## Heading 2	Font: Segoe UI Colour: rgb(31, 35, 40) #1F2328 Font size: 24px Line spacing: 30px (125%) Underlined: Yes rgb(223, 228, 233) #DFE4E9	Font: Segoe UI Colour: rgb(31, 35, 40) #1F2328 Font size: 16.8px Line spacing: 21px (125%) Underlined: Yes rgb(223, 228, 233) #DFE4E9
### Heading 3	Font: Segoe UI Colour: rgb(31, 35, 40) #1F2328 Font size: 20px Line spacing: 25px (125%) Underlined: No	Font: Segoe UI Colour: rgb(31, 35, 40) #1F2328 Font size: 15px Line spacing: 18.75px (125%) Underlined: No
#### Heading 4	Font: Segoe UI Colour: rgb(31, 35, 40) #1F2328 Font size: 16px Line spacing: 20px (125%) Underlined: No	Font: Segoe UI Colour: rgb(31, 35, 40) #1F2328 Font size: 12px Line spacing: 15px (125%) Underlined: No
##### Heading 5	Font: Segoe UI Colour: rgb(31, 35, 40) #1F2328 Font size: 14px Line spacing: 17.5px (125%) Underlined: No	Font: Segoe UI Colour: rgb(31, 35, 40) #1F2328 Font size: 10.5px Line spacing: 13.125px (125%) Underlined: No
###### Heading 6	Font: Segoe UI Colour: rgb(89, 99, 110) #59636E Font size: 13.6px Line spacing: 17px (125%) Underlined: No	Font: Segoe UI Colour: rgb(89, 99, 110) #59636E Font size: 10.2px Line spacing: 12.75px (125%) Underlined: No
Body text for comparison	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 92.7 — Heading properties

⬆️ Top

Heading alternatives

MARKDOWN	HTML	GITHUB OUTPUT
Heading level 1 ======	<h1>Heading level 1</h1>	Heading level 1
Heading level 2 ----	<h2>Heading level 2</h2>	Heading level 2
Table 92.8 — Heading alternatives

It is generally best not to use these alternatives; they only cover the first two heading levels — stick with the hashes.

Paragraph 1
Paragraph 2

Paragraph 3
Paragraph 4

test

Lorem ipsum dolor sit amet

Consectetur adipiscing elit.

Lorem ipsum dolor sit amet

Consectetur adipiscing~~ elit.

    test

The world is flat round.

Lorem ipsum dolor sit

Consectetur elit.

---