markedpp

Preprocessor for documents written in markdown

markedpp is a preprocessor for documents written in markdown. The output itself is again markdown.

It supports the following extensions:

• Generation of a "Table of Contents"
• Automatic numbering of Headings
• Include various files into a single output document
• Sorted collection of References
• Autonumbering of ordered lists
• Automatic update of heading identifiers
• Support for autoid for marked, markdown-it, unified, pandoc, github.com, gitlab.com, bitbucket.org, ghost.org.

This project is inspired by markdown-pp. Albeight the markdown syntax of this project here is slightly different, markdown-pp commands can be used as well.

Table of Contents

• 1. Extended Markdown Syntax
  • 1.1. toc
    • 1.1.1. level
    • 1.1.2. minlevel
    • 1.1.3. numbered
    • 1.1.4. omit
  • 1.2. ref
  • 1.3. include
  • 1.4. numberedheadings
    • 1.4.1. level
    • 1.4.2. minlevel
    • 1.4.3. skip
    • 1.4.4. start
    • 1.4.5. omit
• 2. Specials
  • 2.1. Using custom anchors
  • 2.2. Changing type of autoId generation
• 3. Installation
• 4. Usage
• 5. CLI
• 6. Running Tests & Contributing
  • 6.1. Contribution and License Agreement
• 7. License
• 8. References

1. Extended Markdown Syntax

The extended markdown syntax for the pre-processor borrows from the already existing image tag. All commands start using a ! followed by the command. Options for the specific command are specified in normal brackets.

!<command> (<options>)

1.1. toc

!toc [([level=1-6] [minlevel=1-6] [numbered] [omit="...;..."])]

Inserts a "Table of Contents" section:

• level: [optional] level of headings to show (default is 3)
• minlevel: [optional] min-level of headings to show (default is 1)
• numbered: [optional] show numbered
• omit: [optional] remove headings from ToC. Headings need to be given in " and separated by ;

E.g.

• One
  • One One
    • One One One
• Two

  • Two One

    This includes a "Table of Contents" section. All headings up to level=3 will be linked with their references as a unnumbered bullet list.

For compatibility reasons the following alternative syntax is supported:

!TOC

[[TOC]]

<!-- toc -->
<!-- /toc -->

<!-- toc -->
<!-- toc stop -->

<!-- toc -->

1.1.1. level

!toc (level=5)

To change the default level of 3 to a different one specify the option level in brackets.

1.1.2. minlevel

!toc (minlevel=2)

The option minlevel only displays the ToC from minlevel leaving out all headings with a lower level.

E.g. with the above example:

• One One
  • One One One
• Two One

1.1.3. numbered

!toc (numbered)

The option numbered displays the ToC without a bullet list but in a flat numbered fashion

E.g.

1. One
1.1. One One
1.1.1. One One One
2. Two
2.1. Two One

The Preprocessor inserts a html comment tag which allows regenerating the TOC on an already preprocessed document.

E.g.

<!-- !toc (level=1) -->

* [One](#one)
* [Two](#two)

<!-- toc! -->

1.1.4. omit

To omit headings in the ToC define those with omit.

E.g. to remove "Table of Contents" and the branch of "Heading 1":

# Table of Contents

!toc (omit="Table of Contents;Heading 1")

# Heading 1
## Heading 1.1
# Heading 2

will result in:

# Table of Contents

<!-- !toc -->

* [Heading 2](#heading-2)

<!-- toc! -->

# Heading 1

## Heading 1.1

# Heading 2

1.2. ref

!ref

This command includes a references section displaying all references using the alternate link syntax
[<name>]: <url> "<title>" given in the document being preprocessed.

Local references which start with a "#" are ignored.

E.g.

!ref

[markdown]: http://daringfireball.net/projects/markdown/syntax
[GFM]: https://help.github.com/articles/github-flavored-markdown "Github-Flavored-Markdown"

renders as:

<!-- !ref -->

* [Github-Flavored-Markdown][GFM]
* [markdown][markdown]

<!-- ref! -->

[markdown]: http://daringfireball.net/projects/markdown/syntax
[GFM]: https://help.github.com/articles/github-flavored-markdown "Github-Flavored-Markdown"

1.3. include

!include (filename [lang=...] [indent=x] [start=x] [end=x] [link="label"] [vscode="label"])

This inserts the the file specified with filename at the given position in the document being preprocessed. The preprocessor inserts any type of files.

• filename: [mandatory] Name of file to include
• lang: [optional] language of file - if set, then GFM fences are added around include.
• indent: [optional] Indent the included file by x spaces
• start: [optional] Start including the file from line x
• end: [optional] End including the file at line x
• link: [optional] Add a link to this include file with the given label
• vscode: [optional] Add a vscode link to this include file with the given label for vscode

To include a file with specifying the language use the option lang.

start and end will include only the lines from start to end from the source file. If only start is specified, the lines beginning at start will be included to the end of the file. If only end is specified, the lines from the beginning of the file to end will be included.

The link and vscode options will add a link in the resulting file that will allow you to open the original file. The text specified in label will be the name of the link in the markdown file. This is useful for including code snippets within the markdown file and still allow navigation to the original source file.

This then will render using GFM fences.

E.g.

!include (test.js lang=javascript)

renders as

```javascript
/* contents of test.js */
```

Files to insert which cannot be found or recursive inset of the same file leaves the !include command as is.

1.4. numberedheadings

!numberedheadings [([level=1-6] [minlevel=1-6] [skip=1..] [start=1..] [omit="...;..."] [skipEscaping])]

Add numbers on headings

• level: {Number} [optional] level of Headings to show (default is 3)
• minlevel: {Number} [optional] min-level of Headings to show (default is 1)
• skip: {Number} [optional] skip number of Headings on min-level
• start: {Number} [optional] start numbering of Headings with given number
• omit: {String} [optional] omit numbering of Headings. Headings need to be given in " and separated by ;
• skipEscaping: [optional] if enabled \ will not escape the last . in Headings

All Headings up to level 3 will get numbered. If used, this command shall be given at the very top of a document.

1.4.1. level

With the option level, the Headings level where the numbering shall be applied, can be specified.

E.g.

!numberedheadings (level=2)

will number all Headings of level 1 and 2.

Used together with !toc the numbered Headings with show up numberd in the bullet-list style.

E.g.

• 1. One
  • 1.1. One One

!toc (numbered) will display the flat style, still with the numbers.

1. One
1.1. One One

1.4.2. minlevel

The option minlevel omits numbering all Headings below minlevel.

1.4.3. skip

The option skip skips numbering for the first Headings on minlevel.

1.4.4. start

The option start starts the numbering with the given number.

1.4.5. omit

The option omit omits numbering all Headings matching.

2. Specials

2.1. Using custom anchors

Custom anchors can be added to headings by putting a <a name="..."></a> in a separate line right in front of the heading.

<a name="custom-heading"></a>
# Heading with custom id

Instead of using the auto generated id #heading-with-custom-id, #custom-heading will be used as anchor in the ToC.

2.2. Changing type of autoId generation

Unfortunately there is no unique format which defines the composition of an auto identifier in markdown. marked uses a different format then github.

Available options:

• --marked for marked - is default
• --markdownit for markdown-it parser using markdown-it-anchor plugin
• --unified for unified parser using remark-slug plugin
• --pandoc for pandoc
• --github for https://github.com
• --gitlab for https://gitlab.com
• --bitbucket for https://bitbucket.org
• --ghost for https://ghost.org

For other markdown processors:

• --autoid: adds named anchors on headings using <a name="..."></a>.

On the CLI

markedpp --github file.md

Or use in your options

var markedpp = require('markedpp'),
    md = '!toc\n# hello\n## hello & again',
    options = { github: true };

markedpp(md, options, function(err, result){
    console.log(result);
});

3. Installation

For use from commandline consider global install

npm install -g markedpp

For your project

npm install markedpp

4. Usage

var markedpp = require('markedpp'),
    md = '!numberedheadings\n!toc(level=1)\n# hello\n## hello again';

markedpp(md, function(err, result){
    console.log(result);
    /* Outputs
    <!-- !numberedheadings -->

    <!-- !toc (level=1) -->

    * [1\. hello](#1-hello)

    <!-- toc! -->

    # 1\. hello

    ## 1.1\. hello again
    */
});

To include files the dirname need to be defined via options, otherwise it is assumed that the file to include is relative to the current working directory:

var markedpp = require('markedpp'),
    md = '!include(hello.md)',
    options = { dirname: __dirname };

markedpp(md, options, function(err, result){
    console.log(result);
});

5. CLI

Standalone

$ (cat<<EOF
!numberedheadings
!toc(level=1)
# hello
## hello again
EOF
) > hello.md
$ markedpp hello.md
<!-- !numberedheadings -->

<!-- !toc (level=1) -->

* [1\. hello](#1-hello)

<!-- toc! -->

# 1\. hello

## 1.1\. hello again

Together with marked

$ markedpp --no-tags hello.md | marked
<ul>
<li><a href="#1-hello">1. hello</a></li>
</ul>
<h1 id="1-hello">1. hello</h1>
<h2 id="1-1-hello-again">1.1. hello again</h2>

6. Running Tests & Contributing

If you want to submit a pull request, make sure your changes pass the tests. If you're adding a new feature, be sure to add your own test.

To run the tests:

npm test

6.1. Contribution and License Agreement

If you contribute code to this project, you are implicitly allowing your code to be distributed under the MIT license. You are also implicitly verifying that all code is your original work.

7. License

Copyright (c) 2014-, Commenthol. (MIT License)

See LICENSE for more info.

8. References

• bitbucket.org
• ghost.org
• Github-Flavored-Markdown
• github.com
• gitlab.com
• LICENSE
• markdown
• markdown-it
• markdown-it-anchor
• markdown-pp
• marked
• pandoc
• remark-slug
• unified