MdPress

# Markdown Extensions

# Header Anchors

Headers automatically get anchor links applied. Rendering of anchors can be configured using the enhaceApp mdConfig.anchor option.

Internal links are converted to <a> for SPA navigation. Also, every README.md or index.md contained in each sub-directory will automatically be converted to index.html, with corresponding URL /.

Given the following directory structure:

.
├─ README.md
├─ foo
│  ├─ README.md
│  ├─ one.md
│  └─ two.md
└─ bar
   ├─ README.md
   ├─ three.md
   └─ four.md

And providing you are in foo/one.md:

[Home](/) <!-- Sends the user to the root README.md -->
[foo](/foo/) <!-- Sends the user to index.html of directory foo -->
[foo heading](./#heading) <!-- Anchors user to a heading in the foo README file -->
[bar - three](../bar/three.md) <!-- You can append .md (recommended) -->
[bar - four](../bar/four.html) <!-- Or you can append .html -->

Outbound links automatically gets target="_blank" rel="noopener noreferrer":

You can customize the attributes added to external links by setting enhanceApp mdConfig.externalLinks.

# Frontmatter

YAML frontmatter is supported out of the box:

---
title: Blogging Like a Hacker
lang: en-US
---

This data will be available to the rest of the page, along with all custom and theming components.

For more details, check out the Frontmatter page.

# GitHub-Style Tables

Input

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

Output

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

# Emoji 🎉

Input

:tada: :100:

Output

🎉 💯

A list of all emojis available can be found here.

# Table of Contents

Input

[[toc]]

Output

Rendering of TOC can be configured using the markdown.toc option.

# Custom Containers default theme

Input

::: tip
This is a tip
:::

::: warning
This is a warning
:::

::: danger
This is a dangerous warning
:::

::: details
This is a details block, which does not work in IE / Edge
:::

Output

::: tip This is a tip :::

::: warning This is a warning :::

::: danger This is a dangerous warning :::

::: details This is a details block, which does not work in IE / Edge :::

You can also customize the title of the block:

::: danger STOP
Danger zone, do not proceed
:::

::: details Click me to view the code
```js
console.log('Hello, MdPress!')
```
:::

::: danger STOP Danger zone, do not proceed :::

::: details Click me to view the code

console.log('Hello, MdPress!')

:::

# Syntax Highlighting in Code Blocks

MdPress uses Prism to highlight language syntax in Markdown code blocks, using coloured text. Prism supports a wide variety of programming languages. All you need to do is append a valid language alias to the beginning backticks for the code block:

Input

``` js
export default {
  name: 'MyComponent',
  // ...
}
```

Output

export default {
  name: 'MyComponent',
  // ...
}

Input

``` html
<ul>
  <li
  >
    test
  </li>
</ul>
```

Output

<ul>
  <li
  >
    test
  </li>
</ul>

Check out the list of valid languages on the Prism site.

# Line Highlighting in Code Blocks

Input

``` js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

Output




 




export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

# Line Numbers

You can enable line numbers for each code blocks via config:

module.exports = {
  markdown: {
    lineNumbers: true
  }
}

# Import Code Snippets beta

You can import code snippets from existing files via following syntax:

<<< @/filepath

It also supports line highlighting:

<<< @/filepath{highlightLines}

Input

<<< @/../@mdpress/markdown/__tests__/fragments/snippet.js{2}

Output


 


export default function () {
  // ..
}

::: tip Since the import of the code snippets will be executed before webpack compilation, you can’t use the path alias in webpack. The default value of @ is process.cwd(). :::

# Advanced Configuration

MdPress uses markdown-it as the Markdown renderer. A lot of the extensions above are implemented via custom plugins. You can further customize the markdown-it instance using the mdConfig option in .mdpress/enhaceApp.js:

module.exports = {
  markdown: {
    // options for markdown-it-anchor
    anchor: { permalink: false },
    // options for markdown-it-toc
    toc: { includeLevel: [1, 2] },
    extendMarkdown: md => {
      // use more markdown-it plugins!
      md.use(require('markdown-it-xxx'))
    }
  }
}
export default ({
  mdConfig, // extra markdown config for the app
}) => {
  mdConfig = Object.assign({},mdConfig,{
    // options for markdown-it-anchor
   anchor: { permalink: false },
   // options for markdown-it-toc
   toc: { includeLevel: [1, 2] },
   extendMarkdown: md => {
     // use more markdown-it plugins!
     md.use(require('markdown-it-xxx'))
   }
  })
}

← Asset HandlingUsing React in Markdown →