Markdown
Markdown is a markup language that can be used to format text. At the basic level, if all you want to do is add paragraphs of text, all you need to do is separate the desired paragraphs with a blank line.
Distributed Proofreaders uses parsedown for the rendering library. The parsedown website includes an interactive demo for testing out different markup.
Below is a basic introduction to the Markdown flavor used at Distributed Proofreaders.
Headers
Markdown has six levels of headers. To cause a line to be displayed as a header, precede it immediately by a # for <h1>:
# This is a heading
The number of #s indicates the heading level:
###### This is the equivalent of an <h6> heading!
If you want the header to have an id tag you can link to elsewhere:
# Heading {#head}
Which you can then reference in links with:
[see this heading](#head)
Paragraphs
A blank line in between blocks of text will cause a new paragraph to be started.
This section has two paragraphs, separated by a single blank line.
Forced line breaks within a paragraph
If you want to force a line break in normal text, put two spaces following the last printable character, before the return -- if you simply press return without the spaces, the lines will be joined into a normal paragraph.
You may want to use this when you need to force line breaks, but don't want paragraph spacing.
Inline markup
Bold
To bold text, add two asterisks (*) or underscores (_) before and after a word or phrase. To bold the middle of a word for emphasis, add two asterisks or underscores without spaces around the letters.
**this is bold** __this is bold too__
displays as
this is bold
this is bold too
Italic
To italicize text, add one asterisk (*) or underscore (_) before and after a word or phrase. To italicize the middle of a word for emphasis, add one asterisks or underscores without spaces around the letters.
*this is italics* _this is italics too_
displays as
this is italics
this is italics too
Bold and Italic
To emphasize text with bold and italics at the same time, add three asterisks (*) or underscore (_) before and after a word or phrase. To bold and italicize the middle of a word for emphasis, add three asterisks or underscores without spaces around the letters.
***this is bold and italics*** ___this is bold and italics too___
displays as
this is bold and italics
this is bold and italics too
Monospace text
If you want to display just a few words within a paragraph as monospaced, use a single backtick before and after. If you want to display a whole block of text as preformatted text, see the Code blocks section.
Regular text with some `monospaced text` inside it.
displays as
Regular text with some monospaced text inside it.
Strikethrough
To render strikethrough text, use two tildes (~) before and after the word or phrase.
~~not this text~~
displays as
not this text
Links
For a named link, enclose the name in square brackets, and follow that with the URL in parentheses:
[task center](https://www.pgdp.net/c/tasks.php)
will display as
task center
To just include the link without the name, enclosing it in parens will delimit the link.
Images
The following displays the DP logo with alt text of "DP Logo"
You can copy the link to an image in your project's View/Replace Images page and use the form:
- Note
- - Images included in PCs should be sized to the correct display size; we can't specify width and height in Markdown.
- - Images that are stored in the project directory will no longer display once the project is archived.
Lists
Bulleted lists
As with the wiki, a line preceded by an asterisk (* ) or a dash (- ) will be transformed into a bullet point:
* one * two * three - four - five - six
displays as
- one
- two
- three
- four
- five
- six
They can be embedded at multiple levels too:
* one
* two
* three
displays as
- one
- two
- three
- two
Numbered lists
For numbered lists, the first characters on the line should be numbers, either the same or incrementing, followed by a period 1.:
1. one 1. two 1. three 1. alpha 2. beta 3. gamma
displays as
- one
- two
- three
- alpha
- beta
- gamma
Definition lists
For definition lists, put the definition term on the first line, and the definition data on the following line, with a colon (: ) at the beginning of the next line. The definition term will be flush left; the definition data will be indented. If you wish the definition term to be bold, you will need to apply the inline formatting yourself; otherwise, it will display as plain text.
term 1 : definition 1 term 2 : definition 2
Will display as
- term 1
- definition 1
- term 2
- definition 2
Paragraphs within list items
If a list item needs to have multiple paragraphs or distinct lines (particularly within a numbered list, to avoid resetting the numbers), indent each line of content by an equal number of spaces: both the lines with content and the lines without content.
As with forcing line breaks (see above), if you don't want paragraphs spacing between lines, you need to add two trailing spaces at the end of the line.
Block Quotes
Precede each line of the blockquote with a > character.
> This is a blockquoted sentence.
You can have blockquotes with multiple paragraphs by adding a > on the otherwise blank lines between paragraphs.
> Blockquote, first paragraph followed by an empty line > > Blockquote, second paragraph.
displays approximately as:
Blockquote, first paragraph followed by an empty line
Blockquote, second paragraph.
Code blocks
Code blocks are blocks of text that display exactly as entered, including line breaks and spaces. Code blocks display as monospaced text. If you want to include just a few monospaced words within an otherwise normal paragraph, see the Monospace text section.
Code blocks are preformatted text -- every character within the block is displayed as it is entered. That is, long lines will not rewrap. If you need a line break, you must put it in yourself.
Markdown provides multiple ways of doing code blocks:
Indented code blocks
Indent each line by 4 spaces. If you want any of the text to be indented from the left margin, use additional spaces for indentation.
This
is an
indented
code block
displays as
This is an indented code block
Fenced code blocks
If you prefer, you can use fenced code blocks. You can use either three backticks (grave accents) ``` or three tildes ~~~ on a separate line above the first line of the code block and following the last line of the code block.
To avoid confusion with the strikethrough inline formatting, which also uses tildes, it's probably best to use the backticks.
``` This is a fenced code block ```
displays as
This is a fenced code block
Horizontal Rules
Three hyphens in a row as the only characters on a line, preceded and followed by a blank line, will display a horizontal rule. The blank lines before and after are required. If you put three hyphens on the line following a line of text without the blank line in between, the preceding line will be treated as a heading.
---
displays as
Tables
The first row of a table is always a header row. The second row will allow alignment to be adjusted, and must consist of at least three hyphens per cell per column in the table, with optional colons to indicate column alignment:
| Left-aligned | Centered | Right-aligned |
|---|---|---|
| To force text to be left-aligned the contents of the cell below the header row for that column should start with a colon (:) and be followed by a minimum of three hyphens | To force text to be centered for a column, the three hyphens should have a colon at the beginning and end | To right-align text in a column, the colon should be at the end of the string of hyphens |
Like so:
|Left-aligned|Centered|Right-aligned| |:---|:---:|---:| | To force text to be **left-aligned** the contents of the cell below the header row for that column should start with a colon (:) and be followed by a minimum of three hyphens | To force text to be **centered** for a column, the three hyphens should have a colon at the beginning and end | To **right-align** text in a column, the colon should be at the end of the string of hyphens |
A table without the alignment indicators in the row below the header row will be left aligned.
Note that each row must be a continuous string with no line breaks: the forced line break example shown in the paragraphs section above will not work as desired for table cell contents.
Escaping special characters
Markdown uses certain special characters to indicate how words or paragraphs should be formatted. Sometimes, however, we need to include these characters in what we're typing. You can use the backslash character to escape each special character you need to use.
Note that some of these are only an issue when used at the beginning of a line. For instance, using + or _ or . or ! in a sentence or paragraph shouldn't cause problems.
\ backslash
` backtick
~ tilde
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash mark
+ plus sign
- minus sign (hyphen)
. dot
! exclamation mark
Additional Resources
This page is only an introduction, and is not meant to cover everything. There are also things that the Markdown used at DP cannot do, like applying color, or processing selected HTML elements.
See the Markdown Guide Extended Syntax page and associated pages for some things that may be useful, bearing in mind the above restrictions.