Headers automatically get anchor links applied. Rendering of anchors can be configured using the `markdown.anchor` option.
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
## Links
### Internal 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:
For example, given the following directory structure:
```
```
.
.
├─ README.md
├─ index.md
├─ foo
├─ foo
│ ├─ README.md
│ ├─ index.md
│ ├─ one.md
│ ├─ one.md
│ └─ two.md
│ └─ two.md
└─ bar
└─ bar
├─ README.md
├─ index.md
├─ three.md
├─ three.md
└─ four.md
└─ four.md
```
```
@ -30,29 +28,18 @@ For example, given the following directory structure:
And providing you are in `foo/one.md`:
And providing you are in `foo/one.md`:
```md
```md
[Home](/) <!-- Sends the user to the root README.md -->
[Home](/) <!-- sends the user to the root README.md -->
[foo](/foo/) <!-- Sends the user to index.html of directory foo -->
[foo](/foo/) <!-- sends the user to index.html of directory foo -->
[foo heading](./#heading) <!-- Anchors user to a heading in the foo README file -->
[foo heading](./#heading) <!-- anchors user to a heading in the foo README file -->
[bar - three](../bar/three.md) <!-- You can append .md (recommended) -->
[bar - three](../bar/three) <!-- you can omit extention -->
[bar - four](../bar/four.html) <!-- Or you can append .html -->
[bar - three](../bar/three.md) <!-- you can append .md -->
[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
### Page Suffix
Pages and internal links get generated with the `.html` suffix by default.
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
### External Links
Outbound links automatically get `target="_blank" rel="noopener noreferrer"`:
Outbound links automatically get `target="_blank" rel="noopener noreferrer"`:
<!-- TODO: link to config docs, was (../config/README.md#markdown-toc) -->
Rendering of the TOC can be configured using the `markdown.toc` option.
Rendering of the TOC can be configured using the `markdown.toc` option.
## Custom Containers
## Custom Containers
@ -154,10 +128,6 @@ This is a warning
::: danger
::: danger
This is a dangerous warning
This is a dangerous warning
:::
:::
::: details
This is a details block, which does not work in IE / Edge
:::
```
```
**Output**
**Output**
@ -174,13 +144,6 @@ This is a warning
This is a dangerous warning
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
### Custom Title
**Input**
**Input**
@ -191,31 +154,12 @@ Danger zone, do not proceed
:::
:::
```
```
<!-- TODO: details block not working
::: details Click me to view the code
```js
console.log('Hello, VitePress!')
```
:::
-->
**Output**
**Output**
::: danger STOP
::: danger STOP
Danger zone, do not proceed
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
## 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:
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**
**Input**
````
````
```js
```js
export default {
export default {
name: 'MyComponent',
name: 'MyComponent',
// ...
// ...
@ -243,12 +187,9 @@ export default {
**Input**
**Input**
````
````
```html
```html
<ul>
<ul>
<li
<liv-for="todo in todos":key="todo.id">
v-for="todo in todos"
:key="todo.id"
>
{{ todo.text }}
{{ todo.text }}
</li>
</li>
</ul>
</ul>
@ -259,10 +200,7 @@ export default {
```html
```html
<ul>
<ul>
<li
<liv-for="todo in todos":key="todo.id">
v-for="todo in todos"
:key="todo.id"
>
{{ todo.text }}
{{ todo.text }}
</li>
</li>
</ul>
</ul>
@ -275,7 +213,7 @@ A [list of valid languages](https://prismjs.com/#languages-list) is available on
**Input**
**Input**
````
````
```js{4}
```js{4}
export default {
export default {
data () {
data () {
return {
return {
@ -307,7 +245,7 @@ In addition to a single line, you can also specify multiple single lines, ranges
**Input**
**Input**
````
````
```js{1,4,6-7}
```js{1,4,6-7}
export default { // Highlighted
export default { // Highlighted
data () {
data () {
return {
return {
@ -350,96 +288,40 @@ module.exports = {
}
}
```
```
<!-- TODO Support line numbers for specific fence block -->
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):
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`:
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`:
Kia King Ishii
5 years ago