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

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.

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

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:

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

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

⬆️ Top

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

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>

⬆️ Top

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

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

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

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

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

Centres the text in the body text area.

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

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

<p align="justify">Justified text</p>

⬆️ Top

The following are the GitHub properties to applied body text:

⬆️ Top

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:

Paragraph 1

Paragraph 2

Paragraph 1




Paragraph 2

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

Paragraph 1
Paragraph 2

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

⬆️ Top

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:

Paragraph 1<br>
Paragraph 2

Paragraph 3<br>Paragraph 4

Using <br> 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 <br> can be used consecutively to give the spacing required (they are not ignored like blank lines).

⬆️ Top

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 <br> forced line breaks.

Using one <br> 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 <br> simply forces the text onto the next line (as you would expect).

In the next example, there are two <br> 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 <p> 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

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:

Paragraph 1  
Paragraph 2

⬆️ Top

⬆️ Top

Lorem ipsum

Consectetur.

Lorem ipsum<br>
Consectetur.

Lorem ipsum<br><br>
Consectetur.

<p>Lorem ipsum</p>
<p>Consectetur</p>

<p>Lorem ipsum<br>Consectetur</p>

<p>Lorem ipsum<br><br>Consectetur</p>

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:

***
---
___

<hr>

<hr>

⬆️ Top

Text Linea
<hr>
Text Line

Text Line
<hr>

Text Line