Paragraphs and Line Breaks

To insert a hard line break (i.e., a line-break in the input that is reproduced in the output), insert two spaces at the end of the line. If commonmark input parsing is enabled, this may also be effected by escaping the newline:

Darmok and Jalad...\
at Tanagra.

Headers

This is an underlined header 1
==============================

For hash-marked headers, use the corresponding number of hash characters to the corresponding level of header, up to 6 levels, at the start of the line separated by one space followed by the header.

## This is a hash-marked header 2

If commonmark input parsing is enabled, the space is required after the hash-marks in any hash-marked header.

Both types support PHP Extra attributes enclosed in curly braces. These may begin at any point and must end at the end of the line.

## Star Trek: Enterprise { #stent }

Star Trek: Enterprise { .reboots }
---------------------

Non-empty values with a leading period are interpreted as HTML (CSS) or OpenDocument classes, and values with a leading pound symbol are interpreted as in-document link identifiers.

Extra attribute identifiers override the default mechanism for creating header identifiers. They should contain only ASCII alphanumeric characters.

Block Quotes

> The Prime Directive is not just a set of rules;
> it is a philosophy... and a very correct one.
>
> (It goes on for a few paragraphs).

Block quotes may also have a non-multiline invocation: you need only invoke the right-angle bracket at the start of a paragraph and omit it entirely between paragraphs.

> You cannot explain away a wantonly immoral act because
you think it is connected to some higher purpose.

> Here is another paragraph about Picard wisdom.

Consecutive blockquotes as above will be merged as paragraphs within a single block quote on output, even if styles (non-multiline and otherwise) are mixed.

Block quotes may be nested within other block quotes, as may any other block elements such as headers, ordered/unordered lists, and code blocks.

> ### hash-marked header 3
>
> > I'd be delighted to offer any advice
> > I have on understanding women.
> > When I have some, I'll let you know.
>
> 1.  advice list item 1
> 2.  advice list item 2
>
> Here's the code to implement JLP's advice:

>     yes | read engage

Lists

1. Make.
2. It.
1. So. (Not 1. again!)

If commonmark input parsing is enabled, list items may alternatively terminate with the right parenthesis:

1) Live long
2) Prosper

To prevent lists erroneously started by a paragraph beginning with a number and period, use a backslash before the period.

1987. The year TNG premiered.

1987\. The year TNG premiered.

Unordered lists, on the other hand, can be invoked using either asterisk (“*”), pluses (“+”), or hyphens (“-”), and can be a mix of all three styles. Regardless the style, list items are rendered the same way.

- Earl Grey tea.
* Shakespeare.
+ Exotic fish.

All nested block elements need a new line break, otherwise they will be rendered on the same line as the list item on output. To insert paragraphs into a list item, indent each paragraph with either four spaces or one tab.

- First list item

    Courage can be an emotion too.

    Things are only impossible until they're not.
+ Second list item
+ Third list item

To insert block quotes into a list item, indent the block quote with four spaces or one tab prior to the right-angle bracket (“>”).

* List item 1
* List item 2

     > I am Locutus of Borg.

     > That is the cutest of Borg.

Code blocks need to be indented twice (two tabs or eight leading spaces): once for being recognised within the list item, another for the code block itself.

* Here is a list item for an indented code block:

        alias path='echo -e ${PATH//:/\n}'

To make list elements occur in tight sequence — like a grocery list — don't have an empty line between the items.

- Phaser
- Communicator

On the other hand, if you want to render lists separated by white-space, use the following syntax:

- A phaser is a type of weapon.

- A communicator keeps Riker in contact with Troi.

This applies to ordered and unordered list types.

Task lists

Star Trek series with episodes in the Delta quadrant:

- [ ] Original series
- [x] TNG
- [ ] DS9
- [x] Voyager
- [ ] Enterprise
- [ ] Discovery

The check may be upper or lower case. A space must follow the right square bracket.

Definition Lists

Best understated characters:

*Quark*
: Armin Shimerman

*Weyoun*
: Jeffrey Combs

Keys consist of a single line and may contain inline elements. Like other lists, values may consist of arbitrary nested blocks. There may be multiple consecutive values per key. If the key and value are separated by a blank line, the list is emitted as if it contained block elements (usually output as spacing between key-value pairs).

Code Blocks

Here is a paragraph about Bridge protocol

    Here is a code block for the command "Engage"

Within a code block, text is escaped given the output format. Therefore, characters that would normally need to be escaped in other text processing languages such as ampersands (“&”) do not need to be escaped.

Here is how you start the program xterm:

    xterm &

Horizontal Rules

***
* * *
---
- - -
___
_ _ _
___________________________

Metadata

The metadata block begins on the document's first line and continues until the first blank line. It consists of one or more key-value pairs, with keys and values separated by a colon, and pairs separated by a newline. A key (and following value) must exist on the line beginning the metadata pair, but the value may span multiple lines.

Title: Captain's log
Author: Captain J-L Picard
Summary: As part of an exchange program, we're taking
 aboard a Klingon officer to return the recent visit
 of Commander Riker to the cruiser Pagh.
Stardate: 43917.4

If there are multiple lines of text in a metadata value, subsequent lines should (but need not) be offset with whitespace. Otherwise, they must not have a colon in the value, else they will be construed as a subsequent pair's key.

End each line with two spaces to ensure linebreaks are rendered on output for non-conforming Markdown renderers. Moreover, beginning a document with a regular sentence containing a colon might invoke metadata. To escape this, add one blank line to the beginning of the document.

Metadata keys must consist of alphanumeric ASCII characters, the hyphen (“-”), or the underscore (“_”). They must have at least one character and are stripped of white-space and converted to lower case.

Metadata values are opaque text: Markdown statements (e.g., italics, entities, etc.) are copied as-is. The values will have leading white-space stripped, i.e., space following the colon.

If multiple metadata keys resolve to the same name, the last invocation is retained. This check happens after canonicalising the name by stripping spaces, converting to lower-case, and substituting unknown characters.

Metadata values may be pasted into a document by referencing the [%key], such as using the above example, again with the caveat that Markdown annotations (italics, etc.) are copied verbatim:

Stardate: 43917.4

It's currently stardate [%stardate].

Mathematics

This is an inline $f(x)$ function.
This is a block $$f(x)$$ function.
This is also an inline \\(f(x)\\) function.
This is also a block \\[f(x)\\] function.

Tables

| Officer         | Rank                 |
| --------------: | -------------------- |
| Jean-Luc Picard | Captain              |
| Worf            | Lieutenant Commander |
| Data            | Lieutenant Commander |
| William Riker   | Commander            |

The table header must be followed by a line of hyphens with at least three hyphen/colons per column. Columns are separated by vertical bars. The colon indicates alignment: a colon at the beginning means left justified; at the right for right justified, and both for centred.

The leading and trailing column separator is superfluous. Table data is not necessary, but the table header is. The minimum table structure for the above is:

Officer | Rank
--:|---
Jean-Luc Picard | Captain

Table columns may contain arbitrary span elements.

Footnote Definition

[^pt]:
    Klingon insult, meaning something like "weirdo," deriving from
    the verb "to be weird" (**taQ**), with and [sic] you (plural)
    imperative prefix (**pe-**).

Footnote contents may be on the same line as the colon. The footnote name is rendered as a number. If a footnote definition is not referred to, it is not printed.

HTML Blocks

In the original Markdown, block-level elements were well-defined by HTML4. HTML5 elements are also accepted, but as there is no concept of block-level in HTML5, these are non-canonical. Accepted elements are <address>, <article>, <aside>, <blockquote>, <del>, <details>, <dialog>, <dd>, <div>, <dl>, <dt>, <fieldset>, <figcaption>, <figure>, <footer>, <form>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <header>, <hgroup>, <iframe>, <ins>, <li>, <main>, <math>, <nav>, <noscript>, <ol>, <p>, <pre>, <section>, <script>, <style>, <table>, <ul>, and self-closing <hr />.

Emphasis

Text surrounded by a single asterisk (“*”) or underscore (“_”), the single-emphasis variant, is traditionally rendered with italics.

*Captain Picard*
_Captain Picard_

Text surrounded by a double asterisk (“**”) or underscore (“__”), the double-emphasis variant, is traditionally rendered as bold.

**Jean-Luc Picard**
__Jean-Luc Picard__

Emphasis may occur within the middle of a word:

En*ter*prise

In order to produce a literal asterisk (“*”) or underscore (“_”) simply surround the character by white space.

The ship * USS Enterprise * will not be emphasized

Two additional types of double-emphasis are the strike-through and highlight. These are produced by pairs of tilde and equal characters, respectively:

~~Kirk~~Picard is the best ==captain==.

The highlight variant may be enabled in lowdown(1) with highlight parsing enabled. It's disabled by default because if used at the beginning of a line it may be erroneously interpreted as a section.

Links

[text to link](https://bsd.lv)

Local references may be absolute or relative paths:

[Picard](/Picard)

A reference link, on the other hand, keeps the URL outside of the text — usually in the footnotes. Define a reference link anywhere in a document by a title in square brackets (“[]”) followed a colon (“:”) followed by the corresponding URL or path, then an optional title.

[link1]: https://www.bsd.lv/picard.jpg "Optional Title"

The title may be delimited with single quotes, double quotes, or parenthesis. It is only rendered in HTML output. It encompasses all text until the last delimiter before the end of line, so it may contain delimiters. The title may be on its own line.

Reference the link anywhere in your text using [text to the link] and the same [link title], both in square brackets (“[]”) next to each other:

Text about [Captain Picard][link1].

References need not follow the definition: both may appear anywhere in relation to the other.

Reference and inline links may be followed by PHP Extra attributes.

Lowdown [homepage][home] or
[github](https://github.com/kristapsdz/lowdown){ .gh #link1 }.

[home]: https://kristaps.bsd.lv/lowdown { .home #link2 }

For inline links, the open brace must immediately follow the closing parenthesis. Attributes are separated by spaces.

Values with a leading period (“.class”) are interpreted as HTML (CSS) or OpenDocument classses, and values with a leading pound symbol (“#id”) are interpreted as in-document link identifiers.

Automatic Links

<https://bsd.lv/>
<kristaps@localhost>

Images

![Image text](imageurl.jpg)

Just like with links, there are both inline and reference image links.

The inline style consists of an exclamation mark (“!”) followed by the alternate text (which may be empty) surrounded by square brackets “([])” followed by the URL or the path in parentheses “(())”.

Unlike link text within square brackets, the alternate text is interpreted as-is. Thus, passing Markdown or HTML entities will be passed directly to output (escaped according to output medium). Alternate text may not begin with the caret (“^”) or percent (“%”), else they will be interpreted as footnote or metadata references, respectively.

The parentheses may contain optional dimensions (widthx[height]) starting with an equal sign or a quoted (single or double quotes) title in any order after the URL or path. These dimensions are pixel sizes.

![Picard](https://bsd.lv/picard.jpg =250x250 'Engage!')

The reference style definition consists of an image identifier surrounded by square brackets “([])” followed by a colon “(:)” followed by an image URL or path to image and optional title attribute in double quotation marks.

[image1]: https://bsd.lv/picard.jpg "Picture of Picard"

Invoking the image reference is as follows:

A picture of the captain: ![Captain Picard][image1]

As with regular reference links, the definition and references may occur anywhere in relation to each other.

Images may also be followed by PHP Extra attributes for classes, identifiers, and width and height. Implementation of these depends on the output medium.

![Picard](https://bsd.lv/picard.jpg){width=20% .class}

The open brace must immediately follow the closing parenthesis. Attributes are separated by spaces.

Value pairs “width=xx” and “height=xx” are interpreted as HTML (CSS), OpenOffice, or LaTeX dimensions. These override set pixel dimensions. Percentages are understood by all three media; otherwise, dimension units are interpreted according to the medium.

Values with a leading period (“.class”) are interpreted as HTML (CSS) or OpenDocument classes, and values with a leading pound symbol (“#id”) are interpreted as in-document link identifiers.

Code

I need your IP address to scp you Picard pics.
Use the `ifconfig iwm0` command.

To include literal backticks (“`”) within a code of span, surround the code using multiple backticks (“(``”).

``Here is a span of code with `backticks` inside it.``

If you have a literal backtick at the start or end of the span of code, leave a space between the literal backtick and the delimiting backticks.

`` `So many backticks.` ``

Footnote Reference

P'tahk[^pt], tell me who you are, or I will kill you right here!

The footnote name is rendered as a number. There may only be one footnote reference per definition. If a footnote reference refers to an unknown definition, or if it has already been used in referring to a definition, it is printed as-is. Footnote definitions without references are not printed. Nested footnotes are not allowed.

Superscripts

Though a great book, Q^2 (Q^(squared)) isn't Star Trek canon.

HTML Content

Thus, <p>, <Leonard Nimoy>, and <span class="foo"> are all accepted. Even malformed content, such as <span class="foo> is accepted, so long as it begins and ends with angle brackets.

Automatic Escapes

Backslash Escapes

*Captain Picard*

However, if you want to invoke those italics as literal characters, escape those asterisks using backslashes (“\”).

\*Captain Picard\*

The following characters may be escaped to produce literal text: