Markdown

From DPWiki
Jump to navigation Jump to search

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 as an inline image.

![image](dp-logo-360x68px.png)

The following displays the DP logo as a block-level image.

![DP Logo][image]

[image]: dp-logo-360x68px.png

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

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

  1. one
  2. two
  3. three


  1. alpha
  2. beta
  3. 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