docs: initial port of mardown extensions guide from vuepress

docs/.vitepress/config.js

@@ -36,6 +36,7 @@ function getGuideSidebar() {
         { text: 'Getting Started', link: '/guide/getting-started' },
         { text: 'Configuration', link: '/guide/configuration' },
         { text: 'Customization', link: '/guide/customization' },
+        { text: 'Markdown Extensions', link: '/guide/markdown' },
         { text: 'Deploying', link: '/guide/deploy' }
       ]
     }

docs/guide/markdown.md

@@ -0,0 +1,456 @@
+# Markdown Extensions
+
+## Header Anchors
+
+Headers automatically get anchor links applied. Rendering of anchors can be configured using the `markdown.anchor` option.
+
+<!-- TODO: link to option description (../config/README.md#markdown-anchor) -->
+
+## Links
+
+### Internal Links
+
+Internal links are converted to router link 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 `/`.
+
+For example, 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`:
+
+```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 -->
+```
+
+### Redirection for URLs
+
+VitePress supports redirecting to clean links. If a link `/foo` is not found, VitePress will look for a existing `/foo/` or `/foo.html`. Conversely, when one of `/foo/` or `/foo.html` is not found, VitePress will try the other. With this feature, we can customize your website’s URLs with the official plugin [vuepress-plugin-clean-urls](https://vuepress.github.io/plugins/clean-urls/).
+
+::: tip
+Regardless of whether the permalink and clean-urls plugins are used, your relative path should be defined by the current file structure. In the above example, even though you set the path of `/foo/one.md` to `/foo/one/`, you should still access `/foo/two.md` via `./two.md`.
+:::
+
+### Page Suffix
+
+Pages and internal links get generated with the `.html` suffix by default.
+
+<!-- TODO: support pageSuffix
+You can customize this by setting [config.markdown.pageSuffix](../config/README.md#markdown-pagesuffix).
+-->
+
+### External Links
+
+Outbound links automatically get `target="_blank" rel="noopener noreferrer"`:
+
+- [vuejs.org](https://vuejs.org)
+- [VitePress on GitHub](https://github.com/vuejs/vitepress)
+
+You can customize the attributes added to external links by setting [config.markdown.externalLinks](../config/README.md#markdown-externallinks).
+
+## Frontmatter
+
+[YAML frontmatter](https://jekyllrb.com/docs/frontmatter/) is supported out of the box:
+
+```yaml
+---
+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.
+
+<!-- TODO: port frontmatter
+For more details, see [Frontmatter](./frontmatter.md).
+-->
+
+## 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 :tada:
+
+**Input**
+
+```
+:tada: :100:
+```
+
+**Output**
+
+:tada: :100:
+
+A [list of all emojis](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.json) is available.
+
+## Table of Contents
+
+**Input**
+
+```
+[[toc]]
+```
+
+**Output**
+
+<!--lint disable no-shortcut-reference-link no-undefined-references-->
+
+[[toc]]
+
+<!--lint enable no-shortcut-reference-link no-undefined-references-->
+
+<!-- TODO: link to config docs, was (../config/README.md#markdown-toc) -->
+
+Rendering of the TOC can be configured using the `markdown.toc` option.
+
+## Custom Containers
+
+Custom containers can be defined by their types, titles, and contents.
+
+### Default Title
+
+**Input**
+
+```md
+::: 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
+:::
+
+<!-- TODO: details block not working
+
+::: details
+This is a details block, which does not work in Internet Explorer or Edge.
+:::
+-->
+
+### Custom Title
+
+**Input**
+
+```md
+::: danger STOP
+Danger zone, do not proceed
+:::
+```
+
+<!-- TODO: details block not working
+::: details Click me to view the code
+
+```js
+console.log('Hello, VitePress!')
+```
+:::
+-->
+
+**Output**
+
+::: danger STOP
+Danger zone, do not proceed
+:::
+
+<!-- TODO: details block not working
+::: details Click me to view the code
+
+```js
+console.log('Hello, VitePress!')
+```
+
+:::
+-->
+
+## Syntax Highlighting in Code Blocks
+
+VitePress uses [Prism](https://prismjs.com/) 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**
+
+```js
+export default {
+  name: 'MyComponent'
+  // ...
+}
+```
+
+**Input**
+
+````
+``` html
+<ul>
+  <li
+    v-for="todo in todos"
+    :key="todo.id"
+  >
+    {{ todo.text }}
+  </li>
+</ul>
+```
+````
+
+**Output**
+
+```html
+<ul>
+  <li v-for="todo in todos" :key="todo.id">{{ todo.text }}</li>
+</ul>
+```
+
+A [list of valid languages](https://prismjs.com/#languages-list) is available on Prism’s site.
+
+## Line Highlighting in Code Blocks
+
+**Input**
+
+````
+``` js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+````
+
+**Output**
+
+```js{4}
+export default {
+  data() {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+
+In addition to a single line, you can also specify multiple single lines, ranges, or both:
+
+- Line ranges: for example `{5-8}`, `{3-10}`, `{10-17}`
+- Multiple single lines: for example `{4,7,9}`
+- Line ranges and single lines: for example `{4,7-13,16,23-27,40}`
+
+**Input**
+
+````
+``` js{1,4,6-7}
+export default { // Highlighted
+  data () {
+    return {
+      msg: `Highlighted!
+      This line isn't highlighted,
+      but this and the next 2 are.`,
+      motd: 'VitePress is awesome',
+      lorem: 'ipsum',
+    }
+  }
+}
+```
+````
+
+**Output**
+
+```js{1,4,6-8}
+export default {
+  // Highlighted
+  data() {
+    return {
+      msg: `Highlighted!
+      This line isn't highlighted,
+      but this and the next 2 are.`,
+      motd: 'VitePress is awesome',
+      lorem: 'ipsum'
+    }
+  }
+}
+```
+
+## Line Numbers
+
+You can enable line numbers for each code blocks via config:
+
+```js
+module.exports = {
+  markdown: {
+    lineNumbers: true
+  }
+}
+```
+
+<!-- TODO Support line numbers for specific fence block -->
+
+- Demo:
+
+<picture>
+  <source srcset="../images/line-numbers-desktop.png" media="(min-width: 719px)">
+  <img src="../images/line-numbers-desktop.png" class="line-numbers-desktop-snap" alt="Image">
+</picture>
+
+<picture>
+  <source srcset="../images/line-numbers-mobile.gif" media="(max-width: 719px)">
+  <img src="../images/line-numbers-mobile.gif" class="line-numbers-mobile-snap" alt="Image">
+</picture>
+
+<style>
+  @media screen and (min-width:  719px) {
+    .line-numbers-mobile-snap {
+       display: none;
+    }
+  }
+  @media screen and (max-width:  719px) {
+    .line-numbers-desktop-snap {
+       display: none;
+    }
+    .line-numbers-mobile-snap {
+      max-width: none!important;
+      margin: 0 -1.5rem;
+      width: 100vw;
+    }
+  }
+</style>
+
+## Import Code Snippets
+
+You can import code snippets from existing files via following syntax:
+
+```md
+<<< @/filepath
+```
+
+It also supports [line highlighting](#line-highlighting-in-code-blocks):
+
+```md
+<<< @/filepath{highlightLines}
+```
+
+**Input**
+
+```md
+<<< @/../@vitepress/markdown/**tests**/fragments/snippet.js{2}
+```
+
+**Output**
+
+<!--lint disable strong-marker-->
+
+<!-- TODO: snippets
+<<< @/../@vitepress/markdown/**tests**/fragments/snippet.js{2}
+-->
+
+<!--lint enable strong-marker-->
+
+::: 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()`.
+:::
+
+You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) to only include the corresponding part of the code file. You can provide a custom region name after a `#` following the filepath (`snippet` by default):
+
+**Input**
+
+```md
+<<< @/../@vitepress/markdown/**tests**/fragments/snippet-with-region.js#snippet{1}
+```
+
+**Code file**
+
+<!--lint disable strong-marker-->
+<!-- TODO: snippets
+<<< @/../@vitepress/markdown/**tests**/fragments/snippet-with-region.js
+-->
+<!--lint enable strong-marker-->
+
+**Output**
+
+<!--lint disable strong-marker-->
+<!-- TODO: snippets
+<<< @/../@vitepress/markdown/**tests**/fragments/snippet-with-region.js#snippet{1}
+-->
+<!--lint enable strong-marker-->
+
+## Advanced Configuration
+
+VitePress uses [markdown-it](https://github.com/markdown-it/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 `.vitepress/config.js`:
+
+```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'))
+    }
+  }
+}
+```