# Markdown Extensions

# Header Anchors

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

# Links

# Internal Links

Inbound links ending in .md or .html are converted to <router-link> for SPA navigation.

Each sub-directory in your static site should contain a README.md. It will automatically be converted to index.html.

If you want to link to another markdown file within a directory, remember to:

1. Append it with either .html or .md
2. Make sure the case matches since the path is case-sensitive

# Example

Given the following directory structure:

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

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

# External Links

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

• vuejs.org
• VuePress on GitHub

You can customize the attributes added to external links by setting config.markdown.externalLinks.

# Front Matter

YAML front matter is supported out of the box:

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

The data will be available to the rest of the page, plus all custom and theming components as $page.

title and lang will be automatically set on the current page. In addition you can specify extra meta tags to be injected:

---
meta:
  - name: description
    content: hello
  - name: keywords
    content: super duper SEO
---

# Alternative Front Matter Formats

In addition, VuePress also supports JSON or TOML front matter.

JSON front matter needs to start and end in curly braces:

---
{
  "title": "Blogging Like a Hacker",
  "lang": "en-US"
}
---

TOML front matter needs to be explicitly marked as TOML:

---toml
title = "Blogging Like a Hacker"
lang = "en-US"
---

# GitHub-Style Tables

Input

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

Output

# 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

Input

::: tip
This is a tip
:::

::: warning
This is a warning
:::

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

Output

You can also customize the title of the block:

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

# 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
  }
}  

• Demo:

# Import Code Snippets beta0.10.1+

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

<<< @/filepath

It also supports line highlighting:

<<< @/filepath{highlightLines} 

Input

<<< @/test/markdown/fragments/snippet.js{2}

Output

export default function () {
  // ..
}

# Advanced Configuration

VuePress 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 markdown option in .vuepress/config.js:

module.exports = {
  markdown: {
    // options for markdown-it-anchor
    anchor: { permalink: false },
    // options for markdown-it-toc
    toc: { includeLevel: [1, 2] },
    config: md => {
      // use more markdown-it plugins!
      md.use(require('markdown-it-xxx'))
    }
  }
}