About

This module provides the @@markdown transform for including markdown snippets in a quantum site and the @markdown transform for inlining markdown files.

Example

Example Markup

Quantum

@@markdown
  ### Heading Text

  _italic_ or **bold** text.

Example Result

Heading Text

italic or bold text.

HTML Output

<div class="qm-markdown">
  <h3 id="heading-text">Heading Text</h3>
  <p><em>italic</em> or <strong>bold</strong> text.</p>
</div>

Markdown File Example

It is also possible to include markdown inline directly from .md files using @markdown and @inline

Example

Quantum

@markdown: @inline path/to/file.md

Inlining files in this way uses @markdown as non-quantum files are not parsed by quantum when using @inline (so all the # for headings are retained)

Note

Always use @@markdown for markdown blocks and @markdown when inlining markdown files.

Using @@markdown prevents the # character being treated as a quantum comment. Since # is used for headings in markdown it is important to do this otherwise they will not show up in the rendered page!

Markdown Table of Contents

When using markdown, it is possible to create an automated table of contents (toc) for the @@markdown section you are writing, or for the @markdown file you are inlining.

To add a table of contents, add  to the place in the section that you want the toc to be added. This will find all the subsequent headings and convert them to a list structure.

The below example demonstrates using some markdown headings. All # headings will be used for the toc that appear after the :

Example

Example Markup

Quantum

@@markdown
  ### First Heading
  This heading won't display in the table of contents as it is
  before the `toc` comment

  Table of contents will display below here
  <!-- toc -->

  ### First heading in toc

  ### Second Heading in toc

  #### Sub Heading

Example Result

First Heading

This heading won't display in the table of contents as it is before the toc comment

Table of contents will display below here

Contents

First heading in toc
Second Heading in toc
- Sub Heading

First heading in toc

Second Heading in toc

Sub Heading

The header links and table of contents apply de-duplication so if you have multiple headings with the same text, subsequent headings are given a numbered suffix.

As anchors are all converted to lower case, the casing of duplicate headings is ignored:

De-duplication example

Example Markup

Quantum

@@markdown
  <!-- toc -->
  # Example
  This heading has anchor `#example`
  ## example
  This heading has anchor `#example-1`
  # example
  This heading has anchor `#example-2`
  ## Example
  This heading has anchor `#example-3`

Example Result

Contents

Example
- example
example
- Example

Example

This heading has anchor #example

example

This heading has anchor #example-1

example

This heading has anchor #example-2

Example

This heading has anchor #example-3

Special Characters

The special characters ~!@#$%^&*(){}[]=:/\,;?+\'" will be removed from the header links to make them both URL safe and easy to follow.

Other characters, such as Chinese letters, will be uri encoded (e.g. from 华 to %E5%8D%8E

)

Entities

The below entities are provided by the entityTransforms function.

Entities

@markdownadded

An entity for rendering markdown using quantum

Example Markup

Quantum

@@markdown
  ### Heading

  _italic_ or **bold** text.

Example Result

Heading

italic or bold text.

markdownadded

An entity for including markdown files in quantum.

Example

Quantum

@markdown: @inline path/to/file.md

Api

Below are all the properties of the object returned from require('quantum-markdown'). For information about different versions, see the Changelog

Functions

entityTransformsoptionsObjectObject[EntityTransform]added

A function that returns a set of EntityTransform functions for use in quantum-html

Arguments

options

The options to use when creating the set of entity transforms.

Returns

Object[EntityTransform]

The entity transforms to use in quantum-html to define the entities that can be rendered.

Cheatsheet

Examples pulled from the Markdown Cheatsheet and combined into a single example:

Example Markup

Quantum

@@markdown
  # H1
  ## H2
  ### H3
  #### H4
  ##### H5
  ###### H6

  Alternatively, for H1 and H2, an underline-ish style:

  Alt-H1
  ======

  Alt-H2
  ------

  Emphasis, aka italics, with *asterisks* or _underscores_.

  Strong emphasis, aka bold, with **asterisks** or __underscores__.

  Combined emphasis with **asterisks and _underscores_**.

  Strikethrough uses two tildes. ~~Scratch this.~~

  1. First ordered list item
  2. Another item
    * Unordered sub-list.
1. Actual numbers don't matter, just that it's a number
  1. Ordered sub-list
4. And another item.

   You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown).

   To have a line break without a paragraph, you will need to use two trailing spaces.
   Note that this line is separate, but within the same paragraph.
   (This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)

* Unordered list can use asterisks
- Or minuses
+ Or pluses

[I'm an inline-style link](https://www.google.com)

[I'm an inline-style link with title](https://www.google.com "Google's Homepage")

[I'm a reference-style link][Arbitrary case-insensitive reference text]

[I'm a relative reference to a repository file](../blob/master/LICENSE)

[You can use numbers for reference-style link definitions][1]

Or leave it empty and use the [link text itself].

URLs and URLs in angle brackets will automatically get turned into links.
http://www.example.com or <http://www.example.com> and sometimes
example.com (but not on Github, for example).

Some text to show that the reference links can follow later.

[arbitrary case-insensitive reference text]: https://www.mozilla.org
[1]: http://slashdot.org
[link text itself]: http://www.reddit.com

Here's our logo (hover to see the title text):

Inline-style:
![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")

Reference-style:
![alt text][logo]

[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2"

Inline `code` has `back-ticks around` it.

```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```

```python
s = "Python syntax highlighting"
print s
```

```
No language indicated, so no syntax highlighting.
But let's throw in a <b>tag</b>.
```

Colons can be used to align columns.

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

There must be at least 3 dashes separating each header cell.
The outer pipes (|) are optional, and you don't need to make the
raw Markdown line up prettily. You can also use inline Markdown.

Markdown | Less | Pretty
--- | --- | ---
*Still* | `renders` | **nicely**
1 | 2 | 3

> Blockquotes are very handy in email to emulate reply text.
> This line is part of the same quote.

Quote break.

> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.

<dl>
  <dt>Definition list</dt>
  <dd>Is something people use sometimes.</dd>

  <dt>Markdown in HTML</dt>
  <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
</dl>

## Horizontal Rule

Three or more...

---

Hyphens

***

Asterisks

___

Underscores

Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a *separate paragraph*.

This line is also a separate paragraph, but...
This line is only separated by a single newline, so it's a separate line in the *same paragraph*.

Example Result

H1

H2

H3

H4

H5

H6

Alternatively, for H1 and H2, an underline-ish style:

Alt-H1

Alt-H2

Emphasis, aka italics, with asterisks or underscores.

Strong emphasis, aka bold, with asterisks or underscores.

Combined emphasis with asterisks and underscores.

Strikethrough uses two tildes. ~~Scratch this.~~

First ordered list item
Another item
- Unordered sub-list.

1. Actual numbers don't matter, just that it's a number 1. Ordered sub-list4. And another item. You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown). To have a line break without a paragraph, you will need to use two trailing spaces. Note that this line is separate, but within the same paragraph. (This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)* Unordered list can use asterisks- Or minuses+ Or pluses[I'm an inline-style link](https://www.google.com)[I'm an inline-style link with title](https://www.google.com "Google's Homepage")[I'm a reference-style link][Arbitrary case-insensitive reference text][I'm a relative reference to a repository file](../blob/master/LICENSE)[You can use numbers for reference-style link definitions][1]Or leave it empty and use the [link text itself].URLs and URLs in angle brackets will automatically get turned into links.http://www.example.com or and sometimesexample.com (but not on Github, for example).Some text to show that the reference links can follow later.[arbitrary case-insensitive reference text]: https://www.mozilla.org[1]: http://slashdot.org[link text itself]: http://www.reddit.comHere's our logo (hover to see the title text):Inline-style:![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")Reference-style:![alt text][logo][logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2"Inline `code` has `back-ticks around` it.```javascriptvar s = "JavaScript syntax highlighting";alert(s);``````pythons = "Python syntax highlighting"print s``````No language indicated, so no syntax highlighting.But let's throw in a tag.```Colons can be used to align columns.| Tables | Are | Cool || ------------- |:-------------:| -----:|| col 3 is | right-aligned | $1600 || col 2 is | centered | $12 || zebra stripes | are neat | $1 |There must be at least 3 dashes separating each header cell.The outer pipes (|) are optional, and you don't need to make theraw Markdown line up prettily. You can also use inline Markdown.Markdown | Less | Pretty--- | --- | ---*Still* | `renders` | **nicely**1 | 2 | 3> Blockquotes are very handy in email to emulate reply text.> This line is part of the same quote.Quote break.> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.

Definition list: Is something people use sometimes.
Markdown in HTML: Does *not* work **very** well. Use HTML tags.

Three or more...---Hyphens***Asterisks___UnderscoresHere's a line for us to start with.This line is separated from the one above by two newlines, so it will be a *separate paragraph*.This line is also a separate paragraph, but...This line is only separated by a single newline, so it's a separate line in the *same paragraph*.