diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 47cf9410..01fa8149 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -35,8 +35,8 @@ function getGuideSidebar() { { text: 'What is VitePress?', link: '/' }, { text: 'Getting Started', link: '/guide/getting-started' }, { text: 'Configuration', link: '/guide/configuration' }, - { text: 'Customization', link: '/guide/customization' }, { 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 index 969964f0..53f48bfe 100644 --- a/docs/guide/markdown.md +++ b/docs/guide/markdown.md @@ -4,25 +4,23 @@ 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 `/`. +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: ``` . -├─ README.md +├─ index.md ├─ foo -│ ├─ README.md +│ ├─ index.md │ ├─ one.md │ └─ two.md └─ bar - ├─ README.md + ├─ index.md ├─ three.md └─ four.md ``` @@ -30,29 +28,18 @@ For example, given the following directory structure: 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) +[Home](/) +[foo](/foo/) +[foo heading](./#heading) +[bar - three](../bar/three) +[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"`: @@ -60,8 +47,6 @@ 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: @@ -71,15 +56,10 @@ You can customize the attributes added to external links by setting [config.mark 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** @@ -124,14 +104,8 @@ A [list of all emojis](https://github.com/markdown-it/markdown-it-emoji/blob/mas **Output** - - [[toc]] - - - - Rendering of the TOC can be configured using the `markdown.toc` option. ## Custom Containers @@ -154,10 +128,6 @@ This is a warning ::: danger This is a dangerous warning ::: - -::: details -This is a details block, which does not work in IE / Edge -::: ``` **Output** @@ -174,13 +144,6 @@ This is a warning This is a dangerous warning ::: - - ### Custom Title **Input** @@ -191,31 +154,12 @@ 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: @@ -223,7 +167,7 @@ VitePress uses [Prism](https://prismjs.com/) to highlight language syntax in Mar **Input** ```` -``` js +```js export default { name: 'MyComponent', // ... @@ -243,12 +187,9 @@ export default { **Input** ```` -``` html +```html @@ -259,10 +200,7 @@ export default { ```html @@ -275,7 +213,7 @@ A [list of valid languages](https://prismjs.com/#languages-list) is available on **Input** ```` -``` js{4} +```js{4} export default { data () { return { @@ -307,7 +245,7 @@ In addition to a single line, you can also specify multiple single lines, ranges **Input** ```` -``` js{1,4,6-7} +```js{1,4,6-7} export default { // Highlighted data () { return { @@ -350,96 +288,40 @@ module.exports = { } ``` - - - Demo: - - Image + + Image - - 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`: @@ -449,8 +331,10 @@ 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'))