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:
您可以通过以下语法从现有文件中导入代码片段：
<<< @/filepathIt also supports line highlighting:
它还支持 行高亮:
<<< @/filepath{highlightLines}Input
输入
<<< @/snippets/snippet.js{2}Code file
代码文件
export default function () {
// ..
}Output
输出
export default function () {
// ..
}TIP提示
<<< ../snippets/snippet.jsYou 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 fooOutput
输出
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 configimport type { UserConfig } from 'valaxy'
const config: UserConfig = {
// ...
}
export default configYou 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!
More configurations see UnoCSS Options.
自由控制你的布局！
更多配置见 UnoCSS Options | 配置。
<div class="flex flex-col">
<div class="flex grid-cols-3">
<div>
</div>
<div>
</div>
<div>
</div>
</div>
<div class="flex grid-cols-2 justify-center items-center">
</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
脚注
Footnote
你可以使用 [^1] 或 [^footnote] 来添加脚注，例如：
这是一个脚注[^1-zh]。
这是一段脚注[^2-zh]。
[^1-zh]: 这是一个脚注。
[^2-zh]: 这是一段脚注。
正确缩进的脚注段落会被自动附加。
使用 `^[content]` 可以创建方便的内联脚注^[比如这个！]。这是一个脚注
。这是一段脚注
。正确缩进的脚注段落会被自动附加。
使用 ^[content] 可以创建方便的内联脚注
You can use [^1] or [^footnote] to add footnotes, for example:
This is a footnote[^1-en].
This is a paragraph of footnote[^2-en].
[^1-en]: This is a footnote.
[^2-en]: This is a paragraph of footnote.
Footnote paragraphs with correct indentation will be automatically attached.
Use `^[content]` to create convenient inline footnotes^[like this!].This is a footnote
.This is a paragraph of footnote
.Footnote paragraphs with correct indentation will be automatically attached.
Use ^[content] to create convenient inline footnotes
脚注预览
Footnote Preview
借助 Floating Vue, 添加的脚注链接在鼠标悬停时会显示脚注内容。你可以在本页面的脚注链接上试一试！
如果你想要自定义脚注的样式，可以参考 Floating Vue 文档 中的 config 设置 site.config.ts 中的 floatingVue，你也可以修改组件 ValaxyFootnoteTooltip 来达到这一点。
With Floating Vue, the added footnote links will display the footnote content when hovering over them. You can try it with the footnote links on this page!
If you want to customize the style of the footnote, you can refer to config in the Floating Vue documentation and change the floatingVue option in site.config.ts accordingly. You can also modify the ValaxyFootnoteTooltip component to achieve this.
自定义
Custom
自定义 Markdown 容器 Class
Custom Markdown Container Class
你可以在 Markdown 文件的 frontmatter 中添加 markdownClass 来自定义 Markdown 容器的 Class。
You can add markdownClass in the frontmatter of the markdown file to customize the Class of the Markdown container.
---
markdownClass: 'markdown-body custom-markdown-class'
---To Be Continued.