Appearance
Markdown
Markdown 是一种轻量级标记语言,创始人为約翰·格魯伯(John Gruber)。 它允许人们“使用易读易写的纯文本格式编写文档,然后转换成有效的XHTML(或者HTML)文档”。
John Gruber 在 2004 年创造了 Markdown 语言,在语法上有很大一部分是跟 Aaron Swartz 共同合作的。这个语言的目的是希望大家使用“易于阅读、易于撰写的纯文字格式,并选择性的转换成有效的 XHTML (或是HTML)”。 其中最重要的设计是可读性,也就是说这个语言应该要能直接在字面上的被阅读,而不用被一些格式化指令标记 (像是 RTF 与 HTML)。 因此,它是现行电子邮件标记格式的惯例,虽然它也借镜了很多早期的标记语言,如:setext、Texile、reStructuredText。 许多网站都使用 Markdown 或是其变种,例如:GitHub、reddit、Diaspora、Stack Exchange、OpenStreetMap 与 SourceForge 让用户更利于讨论。
Github MarkDown
Markdown 标记转成HTML的样式每个网站有自己的风格, 但整体的标记格式是统一的. 我们以github来保存相关的文档, 所以我们以github的为样式为标准.
标题
使用#
,可表示1-6级标题。
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
效果:
一级标题
二级标题
三级标题
四级标题
五级标题
六级标题
文字修饰符
看一下粗体字, 斜体字的标记.
*This text will be italic*
_This will also be italic_
**This text will be bold**
__This will also be bold__
~~This text will be delete~~
_You **can** combine them_
效果:
This text will be italic
This will also be italic
This text will be bold
This will also be bold
This text will be delete
You can combine them
列表
列表分为无序列表和有序列表.
无序列表
主要使用-
和*
来标记无序列表
- George Washington
- John Adams
* Thomas Jefferson
效果:
- George Washington
- John Adams
- Thomas Jefferson
有序列表
1. James Madison
2. James Monroe
3. John Quincy Adams
效果:
- James Madison
- James Monroe
- John Quincy Adams
1. James Madison
1. James Monroe
1. John Quincy Adams
效果:
- James Madison
- James Monroe
- John Quincy Adams
1. Make my changes
1. Fix bug
2. Improve formatting
* Make the headings bigger
2. Push my commits to GitHub
3. Open a pull request
* Describe my changes
* Mention all the members of my team
* Ask for feedback
效果:
- Make my changes
- Fix bug
- Improve formatting * Make the headings bigger
- Push my commits to GitHub
- Open a pull request
- Describe my changes
- Mention all the members of my team
- Ask for feedback
任务列表
- [x] Finish my changes
- [ ] Push my commits to GitHub
- [ ] Open a pull request
效果:
- [x] Finish my changes
- [ ] Push my commits to GitHub
- [ ] Open a pull request
段落
段落的前后要有空行,所谓的空行是指没有文字内容。若想在段内强制换行的方式是使用两个以上空格加上回车(引用中换行省略回车)。
区块引用
在段落的每行或者只在第一行使用符号>
,还可使用多个嵌套引用,如:
> 区块引用
>> 嵌套引用
效果:
区块引用
嵌套引用
链接
[github](http://github.com)
效果:
图片
If you want to embed images, this is how you do it:
![Image of Yaktocat](https://octodex.github.com/images/yaktocat.png)
效果:
If you want to embed images, this is how you do it:
整体样式
# Structured documents
Sometimes it's useful to have different levels of headings to structure your documents. Start lines with a `#` to create headings. Multiple `##` in a row denote smaller heading sizes.
### This is a third-tier heading
You can use one `#` all the way up to `######` six for different heading sizes.
If you'd like to quote someone, use the > character before the line:
> Coffee. The finest organic suspension ever devised... I beat the Borg with it.
> - Captain Janeway
效果:
Structured documents
Sometimes it's useful to have different levels of headings to structure your documents. Start lines with a #
to create headings. Multiple ##
in a row denote smaller heading sizes.
This is a third-tier heading
You can use one #
all the way up to ######
six for different heading sizes.
If you'd like to quote someone, use the > character before the line:
Coffee. The finest organic suspension ever devised... I beat the Borg with it.
- Captain Janeway
代码块
md
```c
#include <stdio.h>
int main(void){
printf("hello world!");
return 0;
}
```
效果:
c
#include <stdio.h>
int main(void){
printf("hello world!");
return 0;
}
支持Emoji表情
@octocat :+1: This PR looks great - it's ready to merge! :shipit:
效果:
@octocat 👍 This PR looks great - it's ready to merge! :shipit:
表格
标题 | 内容 | 备注
-----|------|-----
今天 | 很热 | 少穿
昨天 | 下雨 | 打伞
效果:
标题 | 内容 | 备注 |
---|---|---|
今天 | 很热 | 少穿 |
昨天 | 下雨 | 打伞 |
Markdown Extensions
VitePress comes with built in Markdown Extensions.
Header Anchors
Headers automatically get anchor links applied. Rendering of anchors can be configured using the markdown.anchor
option.
Custom anchors
To specify a custom anchor tag for a heading instead of using the auto-generated one, add a suffix to the heading:
# Using custom anchors {#my-anchor}
This allows you to link to the heading as #my-anchor
instead of the default #using-custom-anchors
.
Links
Both internal and external links gets special treatments.
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](/) <!-- sends the user to the root index.md -->
[foo](/foo/) <!-- sends the user to index.html of directory foo -->
[foo heading](./#heading) <!-- anchors user to a heading in the foo index file -->
[bar - three](../bar/three) <!-- you can omit extension -->
[bar - three](../bar/three.md) <!-- you can append .md -->
[bar - four](../bar/four.html) <!-- or you can append .html -->
Page Suffix
Pages and internal links get generated with the .html
suffix by default.
External Links
Outbound links automatically get target="_blank" rel="noreferrer"
:
Frontmatter
YAML 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.
For more details, see Frontmatter.
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 🎉
Input
:tada: :100:
Output
🎉 💯
A list of all emojis is available.
Table of Contents
Input
[[toc]]
Output
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
::: info
This is an info box.
:::
::: tip
This is a tip.
:::
::: warning
This is a warning.
:::
::: danger
This is a dangerous warning.
:::
::: details
This is a details block.
:::
Output
INFO
This is an info box.
TIP
This is a tip.
WARNING
This is a warning.
DANGER
This is a dangerous warning.
Details
This is a details block.
Custom Title
You may set custom title by appending the text right after the "type" of the container.
Input
md
::: danger STOP
Danger zone, do not proceed
:::
::: details Click me to view the code
```js
console.log('Hello, VitePress!')
```
:::
Output
STOP
Danger zone, do not proceed
Click me to view the code
js
console.log('Hello, VitePress!')
raw
This is a special container that can be used to prevent style and router conflicts with VitePress. This is especially useful when you're documenting component libraries. You might also wanna check out whyframe for better isolation.
Syntax
md
::: raw
Wraps in a <div class="vp-raw">
:::
vp-raw
class can be directly used on elements too. Style isolation is currently opt-in:
Details
Install required deps with your preferred package manager:
sh$ npm install -D postcss postcss-prefix-selector
Create a file named
docs/.postcssrc.cjs
and add this to it:jsmodule.exports = { plugins: { 'postcss-prefix-selector': { prefix: ':not(:where(.vp-raw *))', includeFiles: [/vp-doc\.css/], transform(prefix, _selector) { const [selector, pseudo = ''] = _selector.split(/(:\S*)$/) return selector + prefix + pseudo } } } }
Syntax Highlighting in Code Blocks
VitePress uses Shiki to highlight language syntax in Markdown code blocks, using coloured text. Shiki 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
md
```js
export default {
name: 'MyComponent',
// ...
}
```
```html
<ul>
<li v-for="todo in todos" :key="todo.id">
{{ todo.text }}
</li>
</ul>
```
Output
js
export default {
name: 'MyComponent'
// ...
}
html
<ul>
<li v-for="todo in todos" :key="todo.id">
{{ todo.text }}
</li>
</ul>
A list of valid languages is available on Shiki's repository.
You may also customize syntax highlight theme in app config. Please see markdown
options for more details.
Line Highlighting in Code Blocks
Input
```js{4}
export default {
data () {
return {
msg: 'Highlighted!'
}
}
}
```
Output
js
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-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'
}
}
}
```
Output
js
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',
}
}
}
Alternatively, it's possible to highlight directly in the line by using the // [!code hl]
comment.
Input
```js
export default {
data () {
return {
msg: 'Highlighted!' // [!code hl]
}
}
}
```
Output
js
export default {
data() {
return {
msg: 'Highlighted!'
}
}
}
Focus in Code Blocks
Adding the // [!code focus]
comment on a line will focus it and blur the other parts of the code.
Additionally, you can define a number of lines to focus using // [!code focus:<lines>]
.
Input
Note that only one space is required after !code
, here are two to prevent processing.
```js
export default {
data () {
return {
msg: 'Focused!' // [!code focus]
}
}
}
```
Output
js
export default {
data() {
return {
msg: 'Focused!'
}
}
}
Colored Diffs in Code Blocks
Adding the // [!code --]
or // [!code ++]
comments on a line will create a diff of that line, while keeping the colors of the codeblock.
Input
Note that only one space is required after !code
, here are two to prevent processing.
```js
export default {
data () {
return {
msg: 'Removed' // [!code --]
msg: 'Added' // [!code ++]
}
}
}
```
Output
js
export default {
data () {
return {
msg: 'Removed'
msg: 'Added'
}
}
}
Errors and Warnings in Code Blocks
Adding the // [!code warning]
or // [!code error]
comments on a line will color it accordingly.
Input
Note that only one space is required after !code
, here are two to prevent processing.
```js
export default {
data () {
return {
msg: 'Error', // [!code error]
msg: 'Warning' // [!code warning]
}
}
}
```
Output
js
export default {
data() {
return {
msg: 'Error',
msg: 'Warning'
}
}
}
Line Numbers
You can enable line numbers for each code blocks via config:
js
export default {
markdown: {
lineNumbers: true
}
}
Please see markdown
options for more details.
You can add :line-numbers
/ :no-line-numbers
mark in your fenced code blocks to override the value set in config.
Input
md
```ts {1}
// line-numbers is disabled by default
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
```ts:line-numbers {1}
// line-numbers is enabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
Output
ts
// line-numbers is disabled by default
const line2 = 'This is line 2'
const line3 = 'This is line 3'
ts
// line-numbers is enabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
Import Code Snippets
You can import code snippets from existing files via following syntax:
md
<<< @/filepath
It also supports line highlighting:
md
<<< @/filepath{highlightLines}
Input
md
<<< @/code/snippets/snippet.js{2}
Code file
js
export default {
data () {
return {
msg: `Highlighted!
This line isn't highlighted,
but this and the next 2 are.`,
motd: 'VitePress is awesome',
lorem: 'ipsum'
}
}
}
Output
js
export default {
data () {
return {
msg: `Highlighted!
This line isn't highlighted,
but this and the next 2 are.`,
motd: 'VitePress is awesome',
lorem: 'ipsum'
}
}
}
TIP
The value of @
corresponds to the source root. By default it's the VitePress project root, unless srcDir
is configured. Alternatively, you can also import from relative paths:
md
<<< @/code/snippets/snippet.js
You can also use a VS Code region to only include the corresponding part of the code file. You can provide a custom region name after a #
following the filepath:
Input
md
<<< @/code/snippets/snippet-with-region.js#snippet{1}
Code file
js
export default { // Highlighted
data () {
return {
name: 'MyComponent',
msg: `Highlighted!
This line isn't highlighted,
but this and the next 2 are.`,
motd: 'VitePress is awesome',
lorem: 'ipsum'
}
}
}
Output
js
export default { // Highlighted
data () {
return {
name: 'MyComponent',
msg: `Highlighted!
This line isn't highlighted,
but this and the next 2 are.`,
motd: 'VitePress is awesome',
lorem: 'ipsum'
}
}
}
You can also specify the language inside the braces ({}
) like this:
md
<<< @/code/snippets/snippet.cs{c#}
<!-- with line highlighting: -->
<<< @/code/snippets/snippet.cs{1,2,4-6 c#}
<!-- with line numbers: -->
<<< @/code/snippets/snippet.cs{1,2,4-6 c#:line-numbers}
This is helpful if source language cannot be inferred from your file extension.
Code Groups
You can group multiple code blocks like this:
Input
md
::: code-group
```js [config.js]
/**
* @type {import('vitepress').UserConfig}
*/
const config = {
// ...
}
export default config
```
```ts [config.ts]
import type { UserConfig } from 'vitepress'
const config: UserConfig = {
// ...
}
export default config
```
:::
Output
js
/**
* @type {import('vitepress').UserConfig}
*/
const config = {
// ...
}
export default config
ts
import type { UserConfig } from 'vitepress'
const config: UserConfig = {
// ...
}
export default config
You can also import snippets in code groups:
Input
md
::: code-group
<!-- filename is used as title by default -->
<<< @/code/snippets/snippet.js
<!-- you can provide a custom one too -->
<<< @/code/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
:::
Output
js
export default {
data () {
return {
msg: `Highlighted!
This line isn't highlighted,
but this and the next 2 are.`,
motd: 'VitePress is awesome',
lorem: 'ipsum'
}
}
}
ts
export default { // Highlighted
data () {
return {
name: 'MyComponent',
msg: `Highlighted!
This line isn't highlighted,
but this and the next 2 are.`,
motd: 'VitePress is awesome',
lorem: 'ipsum'
}
}
}
Markdown File Inclusion
You can include a markdown file in another markdown file, even nested.
TIP
You can also prefix the markdown path with @
, it will act as the source root. By default, it's the VitePress project root, unless srcDir
is configured.
For example, you can include a relative markdown file using this:
Input
md
# Docs
## Basics
<!--@include: ./parts/basics.md-->
Part file (parts/basics.md
)
md
Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.
Equivalent code
md
# Docs
## Basics
Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.
It also supports selecting a line range:
Input
md
# Docs
## Basics
<!--@include: ./parts/basics.md{3,}-->
Part file (parts/basics.md
)
md
Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.
Equivalent code
md
# Docs
## Basics
### Configuration
Can be created using `.foorc.json`.
The format of the selected line range can be: {3,}
, {,10}
, {1,10}
WARNING
Note that this does not throw errors if your file is not present. Hence, when using this feature make sure that the contents are being rendered as expected.
Advanced Configuration
VitePress uses 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
const anchor = require('markdown-it-anchor')
module.exports = {
markdown: {
// options for markdown-it-anchor
// https://github.com/valeriangalliat/markdown-it-anchor#usage
anchor: {
permalink: anchor.permalink.headerLink()
},
// options for @mdit-vue/plugin-toc
// https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
toc: { level: [1, 2] },
config: (md) => {
// use more markdown-it plugins!
md.use(require('markdown-it-xxx'))
}
}
}
markdown configurable
- Type:
MarkdownOption
Configure Markdown parser options. VitePress uses Markdown-it as the parser, and Shiki to highlight language syntax. Inside this option, you may pass various Markdown related options to fit your needs.
js
export default {
markdown: {
theme: 'material-theme-palenight',
lineNumbers: true,
// adjust how header anchors are generated,
// useful for integrating with tools that use different conventions
anchor: {
slugify(str) {
return encodeURIComponent(str)
}
}
}
}
Below are all the options that you can have in this object:
ts
interface MarkdownOptions extends MarkdownIt.Options {
// Custom theme for syntax highlighting.
// You can use an existing theme.
// See: https://github.com/shikijs/shiki/blob/main/docs/themes.md#all-themes
// Or add your own theme.
// See: https://github.com/shikijs/shiki/blob/main/docs/themes.md#loading-theme
theme?:
| Shiki.IThemeRegistration
| { light: Shiki.IThemeRegistration; dark: Shiki.IThemeRegistration }
// Enable line numbers in code block.
lineNumbers?: boolean
// Add support for your own languages.
// https://github.com/shikijs/shiki/blob/main/docs/languages.md#supporting-your-own-languages-with-shiki
languages?: Shiki.ILanguageRegistration
// markdown-it-anchor plugin options.
// See: https://github.com/valeriangalliat/markdown-it-anchor#usage
anchor?: anchorPlugin.AnchorOptions
// markdown-it-attrs plugin options.
// See: https://github.com/arve0/markdown-it-attrs
attrs?: {
leftDelimiter?: string
rightDelimiter?: string
allowedAttributes?: string[]
disable?: boolean
}
// specify default language for syntax highlighter
defaultHighlightLang?: string
// @mdit-vue/plugin-frontmatter plugin options.
// See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-frontmatter#options
frontmatter?: FrontmatterPluginOptions
// @mdit-vue/plugin-headers plugin options.
// See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-headers#options
headers?: HeadersPluginOptions
// @mdit-vue/plugin-sfc plugin options.
// See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-sfc#options
sfc?: SfcPluginOptions
// @mdit-vue/plugin-toc plugin options.
// See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
toc?: TocPluginOptions
// Configure the Markdown-it instance.
config?: (md: MarkdownIt) => void
}
数学公式mathjs的用例
md
$\sqrt{3x-1}+(1+x)^2$
The Quadratic Formula
md
$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$
Cauchy's Integral Formula
md
$f(a) = \frac{1}{2\pi i} \oint\frac{f(z)}{z-a}dz$
Angle Sum Formula for Cosines
md
$\cos(\theta+\phi)=\cos(\theta)\cos(\phi)−\sin(\theta)\sin(\phi)$
Gauss' Divergence Theorem
md
$int_D ({\nabla\cdot} F)dV=\int_{\partial D} F\cdot ndS$
Curl of a Vector Field
md
$\vec{\nabla} \times \vec{F} = \left( \frac{\partial F_z}{\partial y} - \frac{\partial F_y}{\partial z} \right) \mathbf{i} + \left( \frac{\partial F_x}{\partial z} - \frac{\partial F_z}{\partial x} \right) \mathbf{j} + \left( \frac{\partial F_y}{\partial x} - \frac{\partial F_x}{\partial y} \right) \mathbf{k}$
Standard Deviation
md
$sigma = \sqrt{ \frac{1}{N} \sum_{i=1}^N (x_i -\mu)^2}$
Definition of Christoffel Symbols
md
$(\nabla_X Y)^k = X^i (\nabla_i Y)^k = X^i \left( \frac{\partial Y^k}{\partial x^i} + \Gamma_{im}^k Y^m \right)$
demo
md
$$\begin{array}{c}
\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &
= \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\
\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\
\nabla \cdot \vec{\mathbf{B}} & = 0
\end{array}$$