Markdown 扩展

信息

与 Hexo 不同，Valaxy 在框架层面实现了一些 Markdown 扩展（如 Container、数学公式）等，而无需主题开发者再次实现。

这与 VitePress 许多功能类似，Valaxy 从 VitePress 中借鉴了许多，并复用了 mdit-vue 的插件。但也存在一些不同之处，Valaxy 默认使用 KaTeX（渲染速度快），同时也支持 MathJax（对齐 VitePress，SVG 输出无需外部 CSS/字体）。

注意：features.katex 与 math 请勿同时开启，两者使用不同的渲染引擎，同时启用可能导致公式重复渲染或样式冲突。启用 math（MathJax）时，features.katex 会被自动忽略。

valaxy.config.ts

export default defineValaxyConfig({
  // KaTeX（默认开启）
  features: { katex: true },

  // 或切换到 MathJax（需先安装：pnpm add markdown-it-mathjax3）
  // math: true,
})

当然，你仍然可以在 Valaxy 中通过添加 MarkdownIt 插件来实现更多功能。

在 Markdown 中使用 Vue

可以直接在 Markdown 文件中导入和使用 Vue 组件。

例如在 components 目录下创建一个 Vue 组件 CustomVueDemo.vue：

components/CustomVueDemo.vue

vue

<script setup lang="ts">
import { onMounted, ref } from 'vue'

const num = ref(100)

/**
 * 如果你需要操作 DOM 元素，可以在 onMounted 钩子中执行
 */
onMounted(() => {
  setTimeout(() => {
    document.title = 'Custom Vue Demo'
  }, 3000)
})
</script>

<template>
  <div class="font-bold text-red custom-style">
    {{ num }}
  </div>
</template>

<style>
.custom-style {
  font-size: 20px;
}
</style>

pages/posts/xxx.md

---
title: 在 Markdown 中使用 Vue
---

<!-- 在 markdown 中直接使用即可： -->
<CustomVueDemo />

Emoji 表情支持 🎉

输入

:tada: :100:

输出

🎉 💯

这是一个我们所支持的 Emoji 列表。

代码行高亮

```js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

输出

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

输入

```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'
```

输出

// 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'

代码块的增减色块标识

在一行上添加 // [!code --] 或者 // [!code ++] 注释将创建该行代码的增减标识，同时保持代码块的颜色。

输入

请注意，在 !code后面只需要一个空格，这里有两个空格以防被渲染。

```js
export default {
  data () {
    return {
      msg: 'Removed' // [!code --]
      msg: 'Added' // [!code ++]
    }
  }
}
```

输出

export default {
  data() {
    return {
      msg: 'Removed', 
      msg: 'Added', 
    }
  }
}

代码块中的错误和警告

在一行代码后中添加 // [!code warning] 或者 // [!code error] 注释将会使改行代码呈现指定颜色块。

输入

请注意，在 !code后面只需要一个空格，这里有两个空格以防被渲染。

```js
export default {
  data () {
    return {
      msg: 'Error', // [!code error]
      msg: 'Warning' // [!code warning]
    }
  }
}
```

输出

export default {
  data() {
    return {
      msg: 'Error', 
      msg: 'Warning'
    }
  }
}

导入代码片段

您可以通过以下语法从现有文件中导入代码片段：

<<< @/filepath

它还支持行高亮:

<<< @/filepath{highlightLines}

输入

<<< @/snippets/snippet.js{2}

代码文件

snippet.js

export default function () {
  // ..
}

输出

snippet.js

export default function () {
  // ..
}

提示

@ 的值与源根相对应。默认情况下是博客根目录，除非配置了 srcDir 。另外，你也可以从相对路径导入：

<<< ../snippets/snippet.js

您也可以使用 VS Code region 只包含代码文件的相应部分。您可以在文件路径后的 # 后提供自定义区域名称：

输入

<<< @/snippets/snippet-with-region.js#snippet{1}

代码文件

snippet-with-region.js

// #region snippet
function foo() {
  // ..
}
// #endregion snippet

export default foo

输出

snippet-with-region.js

function foo() {
  // ..
}

您也可以像这样在大括号（{}）内指定语言：

<<< @/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}

代码分组

您可以像这样对多个代码块进行分组：

输入

::: 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
```

:::

输出

config.jsconfig.ts

/**
 * @type {import('valaxy').UserConfig}
 */
const config = {
  // ...
}

export default config

import type { UserConfig } from 'valaxy'

const config: UserConfig = {
  // ...
}

export default config

你也可以在代码组中导入代码片段。

输入

::: 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]

:::

输出

snippet.jssnippet with region

export default function () {
  // ..
}

function foo() {
  // ..
}

容器

通过对 markdownIt 进行配置，你可以自由设置自定义块区域的文字以及图标及图标的颜色。

提示

tip

注意

warning

警告

danger

信息

info

:::

::: tip

tip

:::

::: warning

warning

:::

::: danger

danger

:::

::: info

info

:::

Click to expand

Details Content

::: details Click to expand

Details Content

:::

你也可以自定义新的容器名称。

::: custom

I am a custom block.

:::

valaxy.config.ts

import { defineValaxyConfig } from 'valaxy'

export default defineValaxyConfig({
  markdown: {
    blocks: {
      custom: {
        icon: 'i-ri:info-i',
        text: 'CUSTOM',
      },
    }
  }
})

添加代码块标题与图标

提示

有关更多代码块图标的示例可以在此处找到。

它基于 vitepress-plugin-group-icons 实现，内置了一些常用图标，你可以如下自定义更多图标。

valaxy.config.ts

import { defineValaxyConfig } from 'valaxy'
import { localIconLoader } from 'vitepress-plugin-group-icons'

export default defineValaxyConfig({
  groupIcons: {
    customIcon: {
      // valaxy: 'https://valaxy.site/favicon.svg',
      valaxy: localIconLoader(import.meta.url, './public/favicon.svg'),
      nodejs: 'vscode-icons:file-type-node',
      playwright: 'vscode-icons:file-type-playwright',
      typedoc: 'vscode-icons:file-type-typedoc',
      eslint: 'vscode-icons:file-type-eslint',
      dockerfile: 'vscode-icons:file-type-docker',
    },
  }
})

此时，使用以下语法：

```ts [valaxy.config.ts]
import { defineValaxyConfig } from 'valaxy'

export default defineValaxyConfig({}) 
```
```dockerfile [sample.dockerfile]
FROM ubuntu

ENV PATH /opt/conda/bin:$PATH
```

我们将会得到带有 valaxy.config.ts 标题与 Valaxy 图标的代码块：

valaxy.config.ts

import { defineValaxyConfig } from 'valaxy'

export default defineValaxyConfig({})

还会得到带有 sample.dockerfile 标题与 Docker 图标的代码块：

sample.dockerfile

dockerfile

FROM ubuntu

ENV PATH /opt/conda/bin:$PATH

数学公式

提示

有关更多数学公式的信息可以在此处找到。

输入

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?_                                                                                 |

输出

当 $a \neq 0$ 时， $(a x^{2} + b x + c = 0)$ 有两个解，他们是

x = \frac{- b \pm \sqrt{b^{2} - 4 a c}}{2 a}

麦克斯韦方程：

equation	description
$\nabla \cdot \vec{B} = 0$	divergence of $\vec{B}$ is zero
$\nabla \times \vec{E} + \frac{1}{c} \frac{\partial \vec{B}}{\partial t} = \vec{0}$	curl of $\vec{E}$ is proportional to the rate of change of $\vec{B}$
$\nabla \times \vec{B} - \frac{1}{c} \frac{\partial \vec{E}}{\partial t} = \frac{4 π}{c} \vec{j} \nabla \cdot \vec{E} = 4 π ρ$	wha?

自定义 KaTeX 选项

KaTeX选项

valaxy.config.ts

export default defineValaxyConfig({
  markdown: {
    /**
     * KaTeX options
     * @see https://katex.org/docs/options.html
     */
    katex: {
      strict: false
    }
  }
})

包含 MarkDown 文件

提示

You can also prefix the markdown path with @, it will act as the source root. By default, it’s the Valaxy project root.

输入

your-file.md

## Docs

<!--@include: @/TEST.md-->
<!--@include: ./parts/basics.md-->

部分文件

parts/basics.mdTEST.md

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

I'm a TEST.

等效代码

## Docs

I'm a TEST.
Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

它还支持选择行范围：

输入

## Docs

<!--@include: @/TEST.md-->
<!--@include: ./parts/basics.md{3,}-->

部分文件

parts/basics.mdTEST.md

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

I'm a TEST.

等效代码

## Docs

I'm a TEST.
### Configuration

Can be created using `.foorc.json`.

所选行范围的格式可以是： {3,}, {,10}, {1,10}

注意

请注意，如果文件不存在，该功能不会出错。因此，在使用此功能时，请确保内容已按预期渲染。

UnoCSS

我们集成了 UnoCSS，因此您可以在 Markdown 文件中直接使用它。

自由控制你的布局！

更多配置见 UnoCSS Options | 配置。

pages/posts/your-post.md

html

<div class="flex flex-col">

<div class="flex grid-cols-3">
  <div>

  ![image](https://www.yunyoujun.cn/images/avatar.jpg)
  </div>

  <div>

  ![image](https://www.yunyoujun.cn/images/avatar.jpg)
  </div>

  <div>

  ![image](https://www.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://cdn.yunyoujun.cn/img/bg/astronaut.webp)

</div>

</div>

Mermaid

Mermaid 已迁移到官方可选插件 valaxy-addon-mermaid。使用图表的站点需要安装并启用；不使用的站点无需安装。原有 Markdown 代码块保持不变。 Mermaid addon

bash

pnpm add valaxy-addon-mermaid

// valaxy.config.ts
import { defineValaxyConfig } from 'valaxy'
import { addonMermaid } from 'valaxy-addon-mermaid'

export default defineValaxyConfig({
  addons: [addonMermaid()],
})

Rendering diagram…

txt

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

More examples see: Mermaid

PlantUML

PlantUML 未内置于核心，因为它需要外部服务器渲染。你可以通过 markdown.transforms 自行配置：

valaxy.config.ts

import { Buffer } from 'node:buffer'
import { defineValaxyConfig } from 'valaxy'

const PLANTUML_SERVER = 'https://www.plantuml.com/plantuml'

export default defineValaxyConfig({
  markdown: {
    transforms: {
      before(code) {
        return code.replace(
          /^```plantuml\n([\s\S]+?)\n```/gm,
          (_, uml: string) => {
            const encoded = Buffer.from(uml.trim()).toString('hex')
            return `<img src="${PLANTUML_SERVER}/svg/~h${encoded}" loading="lazy" alt="PlantUML diagram">`
          },
        )
      },
    },
  },
})

然后在 Markdown 中使用：

txt

```plantuml
Alice -> Bob: Hello
Bob --> Alice: Hi!
```

提示

默认使用 PlantUML 官方服务器，你可以将 PLANTUML_SERVER 替换为自己的服务器地址。

大多数场景下，可使用 Mermaid：安装并启用官方插件后，在浏览器本地渲染图表，无需外部服务。

脚注

你可以使用 [^1] 或 [^footnote] 来添加脚注，例如：

这是一个脚注[^1-zh]。

这是一段脚注[^2-zh]。

[^1-zh]: 这是一个脚注。

[^2-zh]: 这是一段脚注。

  正确缩进的脚注段落会被自动附加。

使用 `^[content]` 可以创建方便的内联脚注^[比如这个！]。

这是一个脚注^[1]。

这是一段脚注^[2]。

正确缩进的脚注段落会被自动附加。

使用 ^[content] 可以创建方便的内联脚注^[3]。

脚注预览

借助 Floating Vue, 添加的脚注链接在鼠标悬停时会显示脚注内容。你可以在本页面的脚注链接上试一试！

如果你想要自定义脚注的样式，可以参考 Floating Vue 文档中的 config 设置 site.config.ts 中的 floatingVue，你也可以修改组件 ValaxyFootnoteTooltip 来达到这一点。

自定义

自定义 Markdown 容器 Class

你可以在 Markdown 文件的 frontmatter 中添加 markdownClass 来自定义 Markdown 容器的 Class。

---
markdownClass: 'markdown-body custom-markdown-class'
---

这是一个脚注。 ↩︎
这是一段脚注。 ↩︎
比如这个！ ↩︎

To Be Continued.

Markdown 扩展

在 Markdown 中使用 Vue ​

Emoji 表情支持 🎉 ​

目录 ​

代码行高亮 ​

代码块的增减色块标识 ​

代码块中的错误和警告 ​

导入代码片段 ​

代码分组 ​

容器 ​

添加代码块标题与图标 ​

数学公式 ​

自定义 KaTeX 选项 ​

包含 MarkDown 文件​

UnoCSS ​

Mermaid ​

PlantUML ​

脚注 ​

脚注预览 ​

自定义 ​

自定义 Markdown 容器 Class ​

贡献者

在 Markdown 中使用 Vue

Emoji 表情支持 🎉

目录

代码行高亮

代码块的增减色块标识

代码块中的错误和警告

导入代码片段

代码分组

容器

添加代码块标题与图标

数学公式

自定义 KaTeX 选项

包含 MarkDown 文件

UnoCSS

Mermaid

PlantUML

脚注

脚注预览

自定义

自定义 Markdown 容器 Class