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

脚注预览

脚注默认使用 Reka UI Popover 提供非模态预览，支持链接和多段 Markdown 内容。鼠标悬停在脚注编号上即可预览，点击编号仍会跳转到文末脚注。触屏和键盘用户可以通过编号旁的 ⋯ 按钮打开预览，按 Escape 或关闭按钮退出。

你可以查看脚注预览示例。即使禁用 JavaScript，文末脚注及其锚点链接仍然可用。

主题可以通过 .va-footnote-popover、.va-footnote-preview、.va-footnote-arrow 自定义外观，并使用 Valaxy 的颜色变量（--va-c-bg、--va-c-text、--va-c-primary）。也可以覆盖 ValaxyFootnoteTooltip 组件，其默认插槽和 #popper 插槽保持不变。

从 Floating Vue 迁移

过渡期仍保留全局 v-tooltip 指令、Floating Vue 组件、样式和 siteConfig.floatingVue 配置。站点或主题显式设置了 floatingVue 时，会自动沿用旧版脚注预览并输出迁移提示，避免已有设置静默失效。

准备迁移时，在 site.config.ts 中显式选择 Reka：

export default defineSiteConfig({
  footnote: { preview: 'reka' },
})

floatingVue 配置和 .v-popper__* 样式不会作用于 Reka 预览。请将脚注样式迁移到上述类名，需要自定义行为时覆盖 ValaxyFootnoteTooltip。其他旧提示仍可继续使用 floatingVue 配置；如果需要临时回退脚注实现，可以设置 footnote: { preview: 'floating-vue' }。

自定义

自定义 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 ​

脚注 ​

脚注预览 ​

从 Floating Vue 迁移 ​

自定义 ​

自定义 Markdown 容器 Class ​

贡献者

在 Markdown 中使用 Vue

Emoji 表情支持 🎉

目录

代码行高亮

代码块的增减色块标识

代码块中的错误和警告

导入代码片段

代码分组

容器

添加代码块标题与图标

数学公式

自定义 KaTeX 选项

包含 MarkDown 文件

UnoCSS

Mermaid

PlantUML

脚注

脚注预览

从 Floating Vue 迁移

自定义

自定义 Markdown 容器 Class