diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 08a5bf77..47cf9410 100644 --- a/docs/.vitepress/config.js +++ b/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' } ] } diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md new file mode 100644 index 00000000..482f5fd1 --- /dev/null +++ b/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. + + + +## 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](/) +[foo](/foo/) +[foo heading](./#heading) +[bar - three](../bar/three.md) +[bar - four](../bar/four.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. + + + +### 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. + + + +## 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 +::: + +::: 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 +::: + + + +### 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 + + + + +## 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** + + + + + + + +::: 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** + + + + + +**Output** + + + + + +## 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