diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 08a5bf77..01fa8149 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -35,6 +35,7 @@ function getGuideSidebar() { { text: 'What is VitePress?', link: '/' }, { text: 'Getting Started', link: '/guide/getting-started' }, { text: 'Configuration', link: '/guide/configuration' }, + { text: 'Markdown Extensions', link: '/guide/markdown' }, { text: 'Customization', link: '/guide/customization' }, { text: 'Deploying', link: '/guide/deploy' } ] diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md new file mode 100644 index 00000000..53f48bfe --- /dev/null +++ b/docs/guide/markdown.md @@ -0,0 +1,344 @@ +# Markdown Extensions + +## Header Anchors + +Headers automatically get anchor links applied. Rendering of anchors can be configured using the `markdown.anchor` option. + +## Links + +### Internal Links + +Internal links are converted to router link for SPA navigation. Also, every `index.md` contained in each sub-directory will automatically be converted to `index.html`, with corresponding URL `/`. + +For example, given the following directory structure: + +``` +. +├─ index.md +├─ foo +│ ├─ index.md +│ ├─ one.md +│ └─ two.md +└─ bar + ├─ index.md + ├─ three.md + └─ four.md +``` + +And providing you are in `foo/one.md`: + +```md +[Home](/) +[foo](/foo/) +[foo heading](./#heading) +[bar - three](../bar/three) +[bar - three](../bar/three.md) +[bar - four](../bar/four.html) +``` + +### Page Suffix + +Pages and internal links get generated with the `.html` suffix by default. + +### External Links + +Outbound links automatically get `target="_blank" rel="noopener noreferrer"`: + +- [vuejs.org](https://vuejs.org) +- [VitePress on GitHub](https://github.com/vuejs/vitepress) + +## 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. + +## 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** + +[[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 +::: +``` + +**Output** + +::: tip +This is a tip +::: + +::: warning +This is a warning +::: + +::: danger +This is a dangerous warning +::: + +### Custom Title + +**Input** + +```md +::: danger STOP +Danger zone, do not proceed +::: +``` + +**Output** + +::: danger STOP +Danger zone, do not proceed +::: + +## 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 + +``` +```` + +**Output** + +```html + +``` + +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 + } +} +``` + +- Demo: + + + + Image + + + + + Image + + + + +## 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')) + } + } +} +``` diff --git a/docs/images/line-numbers-desktop.png b/docs/images/line-numbers-desktop.png new file mode 100644 index 00000000..e16e6707 Binary files /dev/null and b/docs/images/line-numbers-desktop.png differ diff --git a/docs/images/line-numbers-mobile.gif b/docs/images/line-numbers-mobile.gif new file mode 100644 index 00000000..87af6cf0 Binary files /dev/null and b/docs/images/line-numbers-mobile.gif differ