Markdown Extensions
INFO信息
与 Hexo
不同,Valaxy
在框架层面实现了一些 Markdown 扩展(如 Container、数学公式)等,而无需主题开发者再次实现。
这与 VitePress
许多功能类似,Valaxy
从 VitePress
中借鉴了许多,并复用了 mdit-vue 的插件。 但也存在一些不同之处,此前当 Valaxy
实现数学公式时 VitePress
尚未支持,目前 Valaxy
默认的数学公式基于 KaTeX,而 VitePress
基于 MathJax。
KaTeX 相对于 MathJax 有更快的渲染速度,MathJax 则拥有更多的功能。
当然,你仍然可以在 Valaxy 中通过添加 MarkdownIt 插件来实现更多功能。
Emoji 🎉
Emoji 表情支持 🎉
Input
输入
:tada: :100:
Output
输出
🎉 💯
A list of all emojis is available.
这是一个我们所 支持的 Emoji 列表 。
Table of Contents
目录
Input
输入
[[toc]]
Output
输出
Rendering of the TOC can be configured using the markdown.toc
option.
可以使用 markdown.toc
选项配置 TOC 的渲染。
Line of Code Highlighting
代码行高亮
Input
```js{4}
export default {
data () {
return {
msg: 'Highlighted!'
}
}
}
```
Output
输出
export default {
data () {
return {
msg: 'Highlighted!'
}
}
}
Input
输入
```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'
```
```ts:line-numbers=2 {1}
// line-numbers is enabled and start from 2
const line3 = 'This is line 3'
const line4 = 'This is line 4'
```
Output
输出
// line-numbers is disabled by default
const line2 = 'This is line 2'
const line3 = 'This is line 3'
// line-numbers is enabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
// line-numbers is enabled and start from 2
const line3 = 'This is line 3'
const line4 = 'This is line 4'
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.
在一行上添加 // [!code --]
或者 // [!code ++]
注释将创建该行代码的增减标识,同时保持代码块的颜色。
Input
输入
请注意,在 !code
后面只需要一个空格,这里有两个空格以防被渲染。
Note that only one space is needed after !code
, there are two spaces here in case it is rendered.
```js
export default {
data () {
return {
msg: 'Removed' // [!code --]
msg: 'Added' // [!code ++]
}
}
}
```
Output
输出
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.
在一行代码后中添加 // [!code warning]
或者 // [!code error]
注释将会使改行代码呈现指定颜色块。
Input
输入
Note that only one space is needed after !code
, there are two spaces here in case it is rendered.
请注意,在 !code
后面只需要一个空格,这里有两个空格以防被渲染。
```js
export default {
data () {
return {
msg: 'Error', // [!code error]
msg: 'Warning' // [!code warning]
}
}
}
```
Output
输出
export default {
data() {
return {
msg: 'Error',
msg: 'Warning'
}
}
}
Import Code Snippets
导入代码片段
You can import code snippets from existing files via following syntax:
您可以通过以下语法从现有文件中导入代码片段:
<<< @/filepath
It also supports line highlighting:
它还支持 行高亮:
<<< @/filepath{highlightLines}
Input
输入
<<< @/snippets/snippet.js{2}
Code file
代码文件
export default function () {
// ..
}
Output
输出
export default function () {
// ..
}
TIP提示
<<< ../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:
您也可以使用 VS Code region 只包含代码文件的相应部分。您可以在文件路径后的 #
后提供自定义区域名称:
Input
输入
<<< @/snippets/snippet-with-region.js#snippet{1}
Code file
代码文件
// #region snippet
function foo() {
// ..
}
// #endregion snippet
export default foo
Output
输出
function foo() {
// ..
}
You can also specify the language inside the braces ({}
) like this:
您也可以像这样在大括号({}
)内指定语言:
<<< @/snippets/snippet.cs{c#}
<!-- with line highlighting: -->
<<< @/snippets/snippet.cs{1,2,4-6 c#}
<!-- with line numbers: -->
<<< @/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
输入
::: code-group
```js [config.js]
/**
* @type {import('valaxy').UserConfig}
*/
const config = {
// ...
}
export default config
```
```ts [config.ts]
import type { UserConfig } from 'valaxy'
const config: UserConfig = {
// ...
}
export default config
```
:::
Output
输出
/**
* @type {import('valaxy').UserConfig}
*/
const config = {
// ...
}
export default config
import type { UserConfig } from 'valaxy'
const config: UserConfig = {
// ...
}
export default config
You can also import snippets in code groups:
你也可以在代码组中 导入代码片段 。
Input
输入
::: code-group
<!-- filename is used as title by default -->
<<< @/snippets/snippet.js
<!-- you can provide a custom one too -->
<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
:::
Output
输出
export default function () {
// ..
}
function foo() {
// ..
}
Container
容器
通过对 markdownIt
进行配置,你可以自由设置自定义块区域的文字以及图标及图标的颜色。
By configuring markdownIt
, you can set the text and icon (and its color) for custom block.
TIP提示
tip
WARNING注意
warning
DANGER警告
danger
INFO信息
info
:::
::: tip
tip
:::
::: warning
warning
:::
::: danger
danger
:::
::: info
info
:::
Click to expand
Details Content
::: details Click to expand
Details Content
:::
KaTeX
KaTeX 语法支持
Input
输入
When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
**Maxwell's equations:**
| equation | description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| $\nabla \cdot \vec{\mathbf{B}} = 0$ | divergence of $\vec{\mathbf{B}}$ is zero |
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
| $\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$ | _wha?_ |
Output When , there are two solutions to and they are
Maxwell’s equations:
输出
当 时, 有两个解,他们是
麦克斯韦方程:
equation | description |
---|---|
divergence of is zero | |
curl of is proportional to the rate of change of | |
wha? |
Custom KaTeX Options
自定义 KaTeX 选项
// valaxy.config.ts
export default defineValaxyConfig({
markdown: {
/**
* KaTeX options
* @see https://katex.org/docs/options.html
*/
katex: {
strict: false
}
}
})
Markdown File Inclusion
包含 MarkDown 文件
TIP提示
You can also prefix the markdown path with @
, it will act as the source root. By default, it’s the Valaxy project root.
Input
输入
## Docs
<!--@include: @/TEST.md-->
<!--@include: ./parts/basics.md-->
Part file
部分文件
Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.
I'm a TEST.
Equivalent code
等效代码
## Docs
I'm a TEST.
Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.
It also supports selecting a line range:
它还支持选择行范围:
Input
输入
## Docs
<!--@include: @/TEST.md-->
<!--@include: ./parts/basics.md{3,}-->
Part file
部分文件
Some getting started stuff.
### Configuration
Can be created using `.foorc.json`.
I'm a TEST.
Equivalent code
等效代码
## Docs
I'm a TEST.
### Configuration
Can be created using `.foorc.json`.
The format of the selected line range can be: {3,}
, {,10}
, {1,10}
所选行范围的格式可以是: {3,}
, {,10}
, {1,10}
WARNING注意
UnoCSS
We integrated UnoCSS, so you can use it in your markdown file.
我们集成了 UnoCSS,因此您可以在 Markdown 文件中直接使用它。
Freedom to control your layout!
自由控制你的布局!
更多配置见 UnoCSS | 扩展配置。
<div class="flex flex-col">
<div class="flex grid-cols-3">
<div>
![image](https://yunyoujun.cn/images/avatar.jpg)
</div>
<div>
![image](https://yunyoujun.cn/images/avatar.jpg)
</div>
<div>
![image](https://yunyoujun.cn/images/avatar.jpg)
</div>
</div>
<div class="flex grid-cols-2 justify-center items-center">
![image](https://cdn.yunyoujun.cn/img/bg/stars-timing-1.jpg)
![image](https://fastly.jsdelivr.net/gh/YunYouJun/cdn/img/bg/astronaut.webp)
</div>
</div>
Mermaid
Based on mermaid, you can use it in your markdown file directly.
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
More examples see: Mermaid
To Be Continued.