Skip to content

Latest commit

 

History

History
321 lines (207 loc) · 6.47 KB

Markdown.md

File metadata and controls

321 lines (207 loc) · 6.47 KB

Markdown

Spec Markdown is first and foremost Markdown. More specifically, it's based on Github-flavored Markdown.

This section explains the syntax and capabilities of Markdown that Spec Markdown supports and augments.

Character Encoding

Markdown allows you to write text which uses &, <, and >. The output HTML will automatically use the &amp;, &lt;, and &gt; entities.

Well formed HTML entities can be written inline directly. If you write &copy;, it will appear in the HTML output as ©.

Escape sequence

Markdown makes use of certain characters to format text, in order to render one explicitly, place a backslash before it.

You can type *literal asterisks* instead of emphasis by typing \*literal asterisks\*.

Escaping does not apply within code.

Spec Markdown allows backslash escapes for any ASCII punctuation character.

\!\"\#\$\%\&\'\(\)\*\+\,\-\.\/\:\;\<\=\>\?\@\[\\\]\^\_\`\{\|\}\~

Produces the following:

!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~

Inline formatting

Markdown allows for inline stylistic and structual formatting. Inline formatting is allowed in paragraphs, list items, and table cells.

Inline HTML

Markdown is not a replacement for HTML and instead leverages HTML by allowing its use inline within paragraphs, links, etc.

This code has blinking and emphasized formatting.

Markdown syntax can continue to be used within inline HTML.

Links

Use [ ] square brackets to indicate linked text followed immediately by ( ) parenthesis to describe the URL the text will link to.

The linked text can contain any other inline formatting.

This is an [-->*example*<--](https://www.facebook.com) of a link.

Produces the following:

This is an -->example<-- of a link.

Todo: Links do not yet support a reference style short-form.

Emphasis

Wrapping asterisks (*) indicate emphasis.

Example of **bold** and *italic* and ***bold italic***.

Produces the following:

Example of bold and italic and bold italic.

Alternatively, use underscore (_) for italic emphasis.

Example of _italic_ and **_bold italic_** or _**bold italic**_.

Produces the following:

Example of italic and bold italic or bold italic.

Inline Code

Wrapping back-ticks (`) indicate inline code, text inside back-ticks is not formatted, allowing for special characters to be used in inline code without escapes.

This is an `example` of some inline code.

Produces

This is an example of some inline code.

Inline code can also use double- or triple-backticks. Wrapping spaces are removed.

`` ` `` Produces `

Images

![Specs](http://i.imgur.com/aV8o3rE.png)

Produces the following:

Specs

Blocks

Markdown allows for block-level structual formatting. Every block is seperated by at least two new lines. Spec Markdown makes use of Markdown's blocks to produce more specific structural formatting.

Block HTML

Markdown is not a replacement for HTML and instead leverages HTML by allowing its use as complete blocks when separated from surrounding content by blank lines.

Note: Markdown formatting syntax is not processed within block-level HTML tags.

For example, to add an HTML table to a Markdown article:

Unrelated previous paragraph followed by a blank line

<table>
<tr>
<td>Table cell</td>
<td>

<table>
<tr>
<td>*Tables in tables*</td>
</tr>
</table>

</td>
</tr>
</table>

Produces the following:

Unrelated previous paragraph followed by a blank line

Table cell
*Tables in tables*

And using <pre> produces a simple code block:

<pre>
Buffalo Bill ’s
defunct
       who used to
       ride a watersmooth-silver
                                stallion
and break onetwothreefourfive pigeonsjustlikethat
                                                 Jesus
he was a handsome man
                     and what i want to know is
how do you like your blueeyed boy
Mister Death
</pre>

Produces the following:

Buffalo Bill ’s
defunct
       who used to
       ride a watersmooth-silver
                                stallion
and break onetwothreefourfive pigeonsjustlikethat
                                                 Jesus
he was a handsome man
                     and what i want to know is
how do you like your blueeyed boy
Mister Death

Section Headers

Regular Markdown supports two styles of headers, Setext and atx, however Spec Markdown generally only supports atx style headers.

# Header

Setext headers are not supported by Spec Markdown.

Header
------

The number of # characters refers to the depth of the section. To produce an, <h3>, type ###. Optionally, a header may be "closed" by any number of # characters.

Note: Spec Markdown requires that documents start with a header.

Paragraphs

Paragraphs are the most simple Markdown blocks. Lines are appended together to form a single <p> tag. Any inline syntax is allowed within a paragraph.

Lists

Markdown lists are lines which each start with either a ordered bullet 1. or unordered bullet, *, -, or +. Lists are optionally indented by two spaces.

Lists can be nested within other lists by indenting by at least two spaces.

  1. this
  2. is
  3. a
    - nested
  4. list

Produces the following:

  1. this
  2. is
  3. a - nested
  4. list

Task Lists

Spec Markdown also supports task lists. Start a list item with [ ] or [x] to render a checkbox. This can be useful for keeping your tasks inline with in-progress draft specifications.

  1. this
  2. [ ] is
  3. [x] a
    - [X] nested
  4. todo list

Produces the following:

  1. this
  2. is
  3. a - [X] nested
  4. todo list

Code Block

A block of code is formed by either indenting by 4 spaces, or wrapping with ``` on their own lines.

```
const code = sample();
```

Produces the following:

const code = sample();

Block Quotes

Spec markdown does not yet support Markdown's > style block quotes.

Horizontal Rules

Spec Markdown does not yet support Markdown's --- style <hr>.

Automatic Links

Spec Markdown does not yet automatically link urls.