gitea-yuany3721/vuepress-theme-plume
1
0
Fork 1
mirror of https://github.com/pengzhanbo/vuepress-theme-plume.git synced 2026-04-23 10:58:13 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: optimize and completion docs (#766)

Browse Source
This commit is contained in:
pengzhanbo 2025-12-01 11:30:33 +08:00 committed by GitHub
parent c97a5af473
commit db8a46eb4c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
24 changed files with 3457 additions and 443 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/.vuepress/collections/en/theme-guide.ts
View File

@ -41,12 +41,17 @@ export const themeGuide: ThemeCollectionItem = defineCollection({
items: [ items: [
'basic', 'basic',
'extensions', 'extensions',
'attrs',
'emoji',
'math',
'table', 'table',
'icons', 'icons',
'mark', 'mark',
'plot', 'plot',
'abbr', 'abbr',
'annotation', 'annotation',
'container',
'github-alerts',
'card', 'card',
'steps', 'steps',
'file-tree', 'file-tree',
@ -144,6 +149,7 @@ export const themeGuide: ThemeCollectionItem = defineCollection({
'replace-assets', 'replace-assets',
'seo', 'seo',
'sitemap', 'sitemap',
'llmstxt',
], ],
}, },
{ {

6
docs/.vuepress/collections/zh/theme-guide.ts
View File

@ -41,12 +41,17 @@ export const themeGuide: ThemeCollectionItem = defineCollection({
items: [ items: [
'basic', 'basic',
'extensions', 'extensions',
'attrs',
'emoji',
'math',
'table', 'table',
'icons', 'icons',
'mark', 'mark',
'plot', 'plot',
'abbr', 'abbr',
'annotation', 'annotation',
'container',
'github-alerts',
'card', 'card',
'steps', 'steps',
'file-tree', 'file-tree',
@ -144,6 +149,7 @@ export const themeGuide: ThemeCollectionItem = defineCollection({
'replace-assets', 'replace-assets',
'seo', 'seo',
'sitemap', 'sitemap',
'llmstxt',
], ],
}, },
{ {

87
docs/.vuepress/themes/components/EmojiList.vue Normal file
View File

@ -0,0 +1,87 @@
<script setup lang="ts">
import { useClipboard } from '@vueuse/core'
import { computed } from 'vue'
const { list } = defineProps<{
list: Record<string, string>
}>()
const emojiList = computed(() => {
return Object.entries(list).map(([key, value]) => ({
source: `:${key}:`,
rendered: value,
}))
})
const { copy, copied, text } = useClipboard()
</script>
<template>
<div class="emoji-wrapper">
<ul>
<li
v-for="{ source, rendered } in emojiList" :key="source"
:class="{ copied: copied && text === source }"
>
<Abbreviation @click="copy(source)">
{{ rendered }}
<template #tooltip>
{{ source }}
</template>
</Abbreviation>
</li>
</ul>
</div>
</template>
<style scoped>
.emoji-wrapper ul {
display: flex;
flex-wrap: wrap;
gap: 8px;
align-items: center;
justify-content: flex-start;
padding: 0;
list-style: none;
}
.emoji-wrapper ul li {
display: flex;
align-items: center;
justify-content: center;
width: 54px;
height: 54px;
margin: 0;
font-size: 28px;
cursor: pointer;
border: solid 1px var(--vp-c-divider);
border-radius: 4px;
transition: border-color var(--vp-t-color);
}
.emoji-wrapper ul li.copied {
position: relative;
border-color: var(--vp-c-brand);
}
.emoji-wrapper ul li.copied::after {
position: absolute;
right: 0;
bottom: 0;
display: inline-block;
width: 14px;
height: 14px;
font-size: 14px;
line-height: 14px;
color: var(--vp-c-success-1);
text-align: center;
vertical-align: -0.125em;
content: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24'%3E%3Cpath fill='%23000' d='M21 7L9 19l-5.5-5.5l1.41-1.41L9 16.17L19.59 5.59z'/%3E%3C/svg%3E");
background-color: var(--vp-c-success-soft);
}
.emoji-wrapper ul li .vp-abbr {
text-decoration: none;
cursor: inherit;
}
</style>

1925
docs/.vuepress/themes/composables/emoji.ts Normal file
View File

File diff suppressed because it is too large Load Diff

113
docs/en/guide/features/llmstxt.md Normal file
View File

@ -0,0 +1,113 @@
---
title: LLMs txt
icon: ri:ai
createTime: 2025/12/01 10:46:46
permalink: /en/features/llmstxt/
---
## Overview
Add [llms.txt](https://llmstxt.org/) to your site to provide LLM-friendly content.
**Related Plugin**: [@vuepress/plugin-llms](https://ecosystem.vuejs.press/plugins/ai/llms.html)
## Why llms.txt?
Large Language Models increasingly rely on website information but face a key limitation:
their context window is too small to fully process most websites.
Converting complex HTML pages containing navigation, ads, and JavaScript into LLM-friendly plain text is both difficult and imprecise.
While websites serve both human readers and LLMs, the latter benefit from more concise,
expert-level information collected in one accessible location.
This is particularly important for use cases like development environments where LLMs need quick access to programming documentation and APIs.
Add a `/llms.txt` Markdown file to your website to provide LLM-friendly content.
This file provides brief background information, guidelines, and links to detailed Markdown files.
## Features
The plugin retrieves all Markdown files from your documentation source directory and converts them into LLM-friendly plain text files.
::: file-tree
- .vuepress/dist
- llms.txt
- llms-full.txt
- markdown-examples.html
- markdown-examples.md
- …
:::
Click the links below to view the llms.txt files for this documentation site:
- [llms.txt](/llms.txt){.no-icon}
- [llms-full.txt](/llms-full.txt){.no-icon}
::: tip
The plugin only generates `llms.txt` files and other LLM-friendly documentation files during
production builds, i.e., when executing the `vuepress build` command, and outputs them to the `.vuepress/dist` directory.
:::
[View the complete feature description in the **Plugin Official Documentation**](https://ecosystem.vuejs.press/plugins/ai/llms.html#%E6%8F%92%E4%BB%B6%E5%8A%9F%E8%83%BD){.read-more}
## Configuration
This feature is not enabled by default in the theme. You can enable it through the `llmstxt` configuration option:
```ts title=".vuepress/config.ts"
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
// Use the theme's built-in default configuration
// llmstxt: true,
// Use custom configuration
llmstxt: {
locale: '/',
// ...other configurations
},
// Can also configure via `plugins.llmstxt`, but not recommended
plugins: {
llmstxt: true
}
}),
})
```
[View the complete configuration options in the **Plugin Official Documentation**](https://ecosystem.vuejs.press/plugins/ai/llms.html#options){.read-more}
## Components
To further enhance interaction between your documentation site and LLMs,
you can add the `<PageContextMenu />` component to your documentation site.
This component is not built-in but is implemented as an additional feature of the theme.
Therefore, you need to manually import it and place it in an appropriate location through [component slots](../../guide/custom/slots.md):
```ts title=".vuepress/client.ts"
import { defineAsyncComponent, h } from 'vue'
import { Layout } from 'vuepress-theme-plume/client'
import PageContextMenu from 'vuepress-theme-plume/features/PageContextMenu.vue' // [!code ++]
import { defineClientConfig } from 'vuepress/client'
export default defineClientConfig({
layouts: {
Layout: h(Layout, null, {
// Add PageContextMenu to the doc-title-after slot, i.e., to the right of the article title
'doc-title-after': () => h(PageContextMenu), // [!code ++]
}),
},
})
```
You can experience this component's functionality to the right of the current page's title.
::: important
This component relies entirely on the `@vuepress/plugin-llms` plugin and can only be used when you have enabled this plugin's functionality.
Therefore, the functionality provided by this component **is only available in the built production package**.
:::

187
docs/en/guide/markdown/attrs.md Normal file
View File

@ -0,0 +1,187 @@
---
title: Attribute Support
icon: ic:outline-data-object
createTime: 2025/11/30 18:02:41
permalink: /en/guide/markdown/attrs/
---
## Overview
Add classes, identifiers, and attributes to your Markdown.
**This feature is enabled by default.**
## Syntax
Use `{ }` after Markdown tokens to add class names, identifiers, or attributes.
```md
markdown content{.classname #id attr1=value attr2="value with spaces"}
```
### `.classname`
Start with `.` to add a class.
**Input:**
```md
__bold__{.bolder}
```
**Output:**
```html
<strong class="bolder">bold</strong>
```
### `#id`
Start with `#` to add an ID.
**Input:**
```md
## Heading{#header-1}
```
**Output:**
```html
<h2 id="header-1">Heading</h2>
```
:::tip This is commonly used for customizing anchor links for headings.
:::
### `attr=value`
**Input:**
```md
[link](https://example.com){target=_blank}
[link](https://example.com){rel="noopener noreferrer"}
```
**Output:**
```html
<a href="https://example.com" target="_blank">link</a>
<a href="https://example.com" rel="noopener noreferrer">link</a>
```
### Combined Usage
**Input:**
```md
[link](https://example.com){.link #linkId target=_blank rel="noopener noreferrer"}
```
**Output:**
```html
<a href="https://example.com" class="link" id="linkId" target="_blank" rel="noopener noreferrer">link</a>
```
### On Block-Level Tokens
Add attributes on the next line after block-level tokens.
For example, using with an unordered list:
**Input:**
```md
- list item **bold**
{.red}
```
**Output:**
```html
<ul class="red">
<li class="red">list item <strong>bold</strong></li>
</ul>
```
For example, using with a table:
**Input:**
```md
| header1 | header2 |
| ------- | ------- |
| column1 | column2 |
{.special} <!-- Note: an empty line is required before this -->
```
**Output:**
```html
<table class="special">
<thead>
<tr>
<th>header1</th>
<th>header2</th>
</tr>
</thead>
<tbody>
<tr>
<td>column1</td>
<td>column2</td>
</tr>
</tbody>
</table>
```
Table cells can also use attributes, commonly for cell merging:
**Input:**
```md
| A | B | C | D |
| ----------------------- | --- | --- | ---------------- |
| 1 | 11 | 111 | 1111 {rowspan=3} |
| 2 {colspan=2 rowspan=2} | 22 | 222 | 2222 |
| 3 | 33 | 333 | 3333 |
```
**Output:**
```html
<table border="1">
<thead>
<tr>
<th>A</th>
<th>B</th>
<th>C</th>
<th>D</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>11</td>
<td>111</td>
<td rowspan="3">1111</td>
</tr>
<tr>
<td colspan="2" rowspan="2">2</td>
<td>22</td>
</tr>
<tr>
<td>3</td>
</tr>
</tbody>
</table>
```
**Result:**
| A | B | C | D |
| ----------------------- | --- | --- | ---------------- |
| 1 | 11 | 111 | 1111 {rowspan=3} |
| 2 {colspan=2 rowspan=2} | 22 | 222 | 2222 |
| 3 | 33 | 333 | 3333 |

99
docs/en/guide/markdown/container.md Normal file
View File

@ -0,0 +1,99 @@
---
title: container
icon: mdi:message-text-outline
createTime: 2025/11/29 14:53:21
permalink: /en/guide/markdown/container/
---
::: tip Tip containers help you highlight important information in your documentation, making the content hierarchy clearer.
:::
Tip containers define different information display styles through type, title, and content.
## Default Title Styles
**Input Example:**
```md
::: note
This is a note container
:::
::: info
This is an info container
:::
::: tip
This is a tip container
:::
::: warning
This is a warning container
:::
::: caution
This is a danger warning container
:::
::: details
This is a details collapsible container
:::
```
**Actual Effect:**
::: note
This is a note container
:::
::: info
This is an info container
:::
::: tip
This is a tip container
:::
::: warning
This is a warning container
:::
::: caution
This is a danger warning container
:::
::: details
This is a details collapsible container
:::
## Custom Title Settings
You can easily set custom titles by adding text after the container type.
**Input Example:**
````md
::: caution STOP
Danger zone, do not proceed
:::
::: details Click to view code
```js
console.log('Hello, VitePress!')
```
:::
````
**Actual Effect:**
::: caution STOP
Danger zone, do not proceed
:::
::: details Click to view code
```js
console.log('Hello, VuePress Plume!')
```
:::

66
docs/en/guide/markdown/emoji.md Normal file
View File

@ -0,0 +1,66 @@
---
title: emoji
icon: mdi:emoji-outline
createTime: 2025/11/29 14:03:43
permalink: /en/guide/markdown/emoji/
---
<script setup>
import EmojiList from '~/components/EmojiList.vue'
import { people, nature, foods, places, activities, symbols, objects, flags } from '~/composables/emoji'
</script>
## Quick Start
在 Markdown 中使用表情符号非常简单，只需用冒号包裹表情代码即可：
**Input：**
```md
:tada: :100:
```
**Output：**
:tada: :100:
## Full Emoji List
We provide complete emoji support based on the [markdown-it-emoji](https://github.com/markdown-it/markdown-it-emoji) plugin.
[To view all available emoji codes, visit: **📋Complete Emoji Code List**](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs){.read-more}
::: tip Click the emoji to copy the emoji symbol to the clipboard.
:::
### People
<EmojiList :list="people" />
### Nature
<EmojiList :list="nature" />
### Foods
<EmojiList :list="foods" />
### Place
<EmojiList :list="places" />
### Activity
<EmojiList :list="activities" />
### Symbol
<EmojiList :list="symbols" />
### Object
<EmojiList :list="objects" />
### Flag
<EmojiList :list="flags" />

209
docs/en/guide/markdown/extensions.md
View File

@ -26,7 +26,9 @@ This allows linking to the header as `#my-anchor` instead of the default `#using
Internal and external links are specially processed. Internal and external links are specially processed.
The theme automatically generates a new link for each md file and stores it in the `permalink` of the corresponding md file's frontmatter. You can modify these links at any time. You can also disable this feature via the `theme.autoFrontmatter` option, reverting to VuePress's default behavior. The theme automatically generates a new link for each md file and stores it in the `permalink` of the corresponding md file's frontmatter.
You can modify these links at any time.
You can also disable this feature via the `theme.autoFrontmatter` option, reverting to VuePress's default behavior.
### Internal Links ### Internal Links
@ -34,7 +36,8 @@ There are three ways to use internal links:
- Use the generated `permalink` as the target for the internal link. - Use the generated `permalink` as the target for the internal link.
- Use the relative path of the md file as the target for the internal link. - Use the relative path of the md file as the target for the internal link.
- Use the absolute path of the md file as the target for the internal link. The absolute path `/` indicates starting from the `${sourceDir}` directory. - Use the absolute path of the md file as the target for the internal link.
The absolute path `/` indicates starting from the `${sourceDir}` directory.
```md ```md
[Markdown](/guide/markdown/) [Markdown](/guide/markdown/)
@ -74,20 +77,6 @@ External links have `target="_blank" rel="noreferrer"`:
| col 2 is | centered | $12 | | col 2 is | centered | $12 |
| zebra stripes | are neat | $1 | | zebra stripes | are neat | $1 |
## Emoji :tada:
**Input:**
```md
:tada: :100:
```
**Output:**
:tada: :100:
You can find the [list of all supported emojis](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs ) here.
## Table of Contents ## Table of Contents
**Input:** **Input:**
@ -100,168 +89,6 @@ You can find the [list of all supported emojis](https://github.com/markdown-it/m
[[TOC]] [[TOC]]
## Custom Containers
Custom containers can be defined by their type, title, and content.
### Default Title
**Input:**
```md
::: note
This is a note box
:::
::: info
This is an info box.
:::
::: tip
This is a tip.
:::
::: warning
This is a warning.
:::
::: caution
This is a dangerous warning.
:::
::: details
This is a details block.
:::
```
**Output:**
::: note
This is a note box
:::
::: info
This is an info box.
:::
::: tip
This is a tip.
:::
::: warning
This is a warning.
:::
::: caution
This is a dangerous warning.
:::
::: details
This is a details block.
:::
### Custom Title
You can set a custom title by appending text after the container's "type".
**Input:**
````md
::: caution STOP
Danger zone, do not proceed
:::
::: details Click to view code
```js
console.log('Hello, VitePress!')
```
:::
````
**Output:**
::: caution STOP
Danger zone, do not proceed
:::
::: details Click to view code
```js
console.log('Hello, VitePress!')
```
:::
## GitHub-Style Alerts
The theme also supports rendering [GitHub-style alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts ). They are rendered in the same way as [custom containers](#custom-containers).
**Input:**
```md
> [!NOTE]
> Emphasizes important information that users should know even when skimming the document.
> [!TIP]
> Advisory information that helps users achieve their goals more smoothly.
> [!IMPORTANT]
> Information crucial for users to achieve their goals.
> [!WARNING]
> Key content that requires immediate user attention due to potential risks.
> [!CAUTION]
> Negative impacts of certain actions.
```
**Output:**
> [!NOTE]
> Emphasizes important information that users should know even when skimming the document.
> [!TIP]
> Advisory information that helps users achieve their goals more smoothly.
> [!IMPORTANT]
> Information crucial for users to achieve their goals.
> [!WARNING]
> Key content that requires immediate user attention due to potential risks.
> [!CAUTION]
> Negative impacts of certain actions.
## Mathematical Equations
**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 $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?_ |
## Superscripts and Subscripts ## Superscripts and Subscripts
- Use `^ ^` for superscript notation. - Use `^ ^` for superscript notation.
@ -311,32 +138,6 @@ Centered content
Right-aligned content Right-aligned content
::: :::
## Attribute Support
You can use special syntax to add attributes to Markdown elements.
**Adding attributes to an image:**
This adds a class attribute named `full-width` and a `width` attribute with the value `100%` to the image.
```md
![](/plume.png){.full-width width="100%"}
```
Other attributes are also supported:
```md
A paragraph with text. {#p .a .b align=center customize-attr="content with spaces"}
```
This will be rendered as:
```html
<p id="p" class="a b" align="center" customize-attr="content with spaces">
A paragraph with text.
</p>
```
## Task Lists ## Task Lists
**Input:** **Input:**

47
docs/en/guide/markdown/github-alerts.md Normal file
View File

@ -0,0 +1,47 @@
---
title: github-alerts
createTime: 2025/11/29 21:20:21
permalink: /en/guide/markdown/github-alerts/
---
## GitHub-Style Alerts
The theme supports rendering
[GitHub-style alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
through callouts. They are rendered in the same way as [hint containers](./container.md).
**Input:**
```md
> [!NOTE]
> Highlights information that users should take note of even when skimming.
> [!TIP]
> Optional information to help users be more successful.
> [!IMPORTANT]
> Crucial information necessary for users to succeed.
> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.
> [!CAUTION]
> Advises about negative outcomes from specific actions.
```
**Output:**
> [!NOTE]
> Highlights information that users should take note of even when skimming.
> [!TIP]
> Optional information to help users be more successful.
> [!IMPORTANT]
> Crucial information necessary for users to succeed.
> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.
> [!CAUTION]
> Advises about negative outcomes from specific actions.

17
docs/en/guide/markdown/icons.md
View File

@ -3,9 +3,6 @@ title: Icons
createTime: 2025/10/08 14:49:39 createTime: 2025/10/08 14:49:39
icon: grommet-icons:emoji icon: grommet-icons:emoji
permalink: /en/guide/markdown/icon/ permalink: /en/guide/markdown/icon/
badge:
text: Changed
type: warning
--- ---
<script setup> <script setup>
@ -29,20 +26,6 @@ useScriptTag(
) )
</script> </script>
::: warning Breaking Change in `1.0.0-rc.144`
The `:[collect:name size/color]:` syntax has been deprecated. Please use `::collect:name =size /color::` instead.
The theme plans to support icon libraries such as `iconfont`, `fontawesome`, and `lucide` in future versions.
The original syntax was insufficient for these new extensions, making this breaking change necessary.
The old syntax remains supported in recent versions but is no longer recommended and will be removed in the future.
The theme detects if the old syntax is used. If so, it will output warning messages and modification
suggestions in the console. Please adjust according to these suggestions.
:::
## Overview ## Overview
The theme supports icons from the following sources in Markdown files: The theme supports icons from the following sources in Markdown files:

148
docs/en/guide/markdown/math.md Normal file
View File

@ -0,0 +1,148 @@
---
title: Mathematical Formulas
icon: tabler:math
createTime: 2025/11/29 21:36:22
permalink: /en/guide/markdown/math/
---
## Overview
The theme has built-in support for mathematical formulas.
This feature is powered by [@vuepress/plugin-markdown-math](https://ecosystem.vuejs.press/zh/plugins/markdown/markdown-math.html).
You can choose to render mathematical formulas in markdown using the following methods:
- `katex` (default)
- `mathjax`
## Usage
```ts title=".vuepress/config.ts"
export default defineUserConfig({
theme: plumeTheme({
markdown: {
math: {
type: 'katex', // 'katex' | 'mathjax'
// ... Other configuration options
}
},
})
})
```
When you choose to use `mathjax`, you also need to install the dependency by running the following command:
::: npm-to
```sh
npm i @mathjax/src
```
:::
## Syntax
### Inline Syntax
Use `$` to wrap mathematical formulas *(i.e., write the mathematical formula between two `$` symbols)*
::: demo markdown title="Inline Mode" expanded
```md
Euler's identity $e^{i\pi}+1=0$ is a beautiful formula in $\mathbb{R}^2$.
```
:::
### Block Syntax
Use `$$` to wrap mathematical formulas *(i.e., write the mathematical formula between two `$$` symbols)*
```md /$$/
<!-- Write the mathematical formula between two `$$` symbols, rendered in a separate block -->
$$xxx$$
<!-- The two `$$` symbols can each occupy a separate line, with the mathematical formula between them -->
$$
xxx
$$
```
:::demo markdown title="Block Mode" expanded
```md
$$
\frac {\partial^r} {\partial \omega^r} \left(\frac {y^{\omega}} {\omega}\right)
= \left(\frac {y^{\omega}} {\omega}\right) \left\{(\log y)^r + \sum_{i=1}^r \frac {(-1)^ Ir \cdots (r-i+1) (\log y)^{ri}} {\omega^i} \right\}
$$
```
:::
## Related Tutorials
### TeX
[TeX Tutorial](https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes){.readmore}
[TeX Cheat Sheet](https://mdit-plugins.github.io/zh/tex.html#tex-tutorial){.readmore}
### KaTeX
[KaTeX Supported Features](https://katex.org/docs/supported.html){.readmore}
[KaTeX Support Table](https://katex.org/docs/support_table.html){.readmore}
### MathJax
[Supported TeX / KaTeX Commands](https://docs.mathjax.org/en/latest/input/tex/macros/index.html#tex-commands){.readmore}
## Configuration Options
:::: field-group
::: field name="type" type="'katex' | 'mathjax'" default="'katex'"
Package used to render $\TeX$ content.
- `'katex'`: Use [KaTeX](https://katex.org/)
- `'mathjax'`: Use [MathJax](https://www.mathjax.org/)
:::
:::field name="delimiters" type="'brackets' | 'dollars' | 'all'" default="'dollars'" optional
Enabled math delimiter syntax.
- `"brackets"`: Use `\(...\)` for inline math and `\[...\]` for display mode math (LaTeX style)
- `"dollars"`: Use `$...$` for inline math and `$$...$$` for display mode math (common Markdown style)
- `"all"`: Enable both bracket and dollar sign syntax
:::
::::
### Using KaTeX
When using KaTeX, any other options will be passed to KaTeX as `KatexOptions`. For all available options, refer to the [KaTeX documentation](https://katex.org/docs/options.html).
Additionally, 2 special options are supported:
:::: field-group
::: field name="copy" type="boolean" optional default="false"
Whether to enable the copy extension.
:::
::: field name="mhchem" type="boolean" optional default="false"
Whether to enable the mhchem extension.
:::
::::
### Using MathJax
When using MathJax, you can set:
:::: field-group
:::field name="tex" type="object" optional
Options passed to the TeX input parser.
:::
::: field name="output" type="'svg' | 'chtml'" default="'svg'" optional
Output format, either SVG or Common HTML.
:::
::: field name="chtml" type="object" optional
Options passed to the Common HTML output parser.
:::
::: field name="svg" type="object" optional
Options passed to the SVG output parser.
:::
::::

56
docs/en/guide/markdown/table.md
View File

@ -290,6 +290,8 @@ Built-in `type` support: `tip`, `note`, `info`, `success`, `warning`, `danger`,
### Table Cell Highlighting ### Table Cell Highlighting
#### Method One
**Input:** **Input:**
```md ```md
@ -314,6 +316,34 @@ Built-in `type` support: `tip`, `note`, `info`, `success`, `warning`, `danger`,
::: :::
#### Method Two
Using the [Attribute Support](./attrs.md) syntax
**Input:**
```md
::: table title="This is the Table Title"
| (1,1) {.danger} | (1,2) | (1,3) | (1,4) {.warning} |
| ------------------ | ------------------ | ---------------- | ----------------- |
| (2,1) | (2,2) {.danger} | (2,3) {.warning} | (2,4) |
| (3,1) | (3,2) {.important} | (3,3) {.danger} | (3,4) |
| (4,1) {.important} | (4,2) | (4,3) | (4,4) {.danger} |
:::
```
**Output:**
::: table title="This is the Table Title"
| (1,1) {.danger} | (1,2) | (1,3) | (1,4) {.warning} |
| ------------------ | ------------------ | ---------------- | ----------------- |
| (2,1) | (2,2) {.danger} | (2,3) {.warning} | (2,4) |
| (3,1) | (3,2) {.important} | (3,3) {.danger} | (3,4) |
| (4,1) {.important} | (4,2) | (4,3) | (4,4) {.danger} |
:::
## Custom Highlight Types ## Custom Highlight Types
In [Custom CSS Styles](../custom/style.md), custom highlight types can be defined using the following format: In [Custom CSS Styles](../custom/style.md), custom highlight types can be defined using the following format:
@ -363,3 +393,29 @@ This custom type can then be used in tables:
| Cell 4 | Cell 5 | Cell 6 | | Cell 4 | Cell 5 | Cell 6 |
::: :::
## Table Cell Merging
Table cell merging is implemented through the attribute syntax supported by [markdown-it-attrs](https://github.com/arve0/markdown-it-attrs).
Therefore, it does not need to be used within the `:::table` container; you can use it in any table.
Inside a table cell, add `rowspan=rows` or `colspan=cols` (or a combination) using
the attribute syntax `{}` at the end of the cell content to achieve table cell merging.
**Input:**
```md
| A | B | C | D |
| ----------------------- | --- | --- | ---------------- |
| 1 | 11 | 111 | 1111 {rowspan=3} |
| 2 {colspan=2 rowspan=2} | 22 | 222 | 2222 |
| 3 | 33 | 333 | 3333 |
```
**Output:**
| A | B | C | D |
| ----------------------- | --- | --- | ---------------- |
| 1 | 11 | 111 | 1111 {rowspan=3} |
| 2 {colspan=2 rowspan=2} | 22 | 222 | 2222 |
| 3 | 33 | 333 | 3333 |

4
docs/en/guide/quick-start/usage.md
View File

@ -10,10 +10,10 @@ tags:
## Environment Requirements ## Environment Requirements
- [Node.js](https://nodejs.org/): **^20.6.0 or >= 22.0.0** [+node-versions] - [Node.js](https://nodejs.org/): **^20.19.0 or >= 22.0.0** [+node-versions]
- Package Manager: [npm 8+](https://www.npmjs.com/), [pnpm 8+](https://pnpm.io/), or [Yarn 2+](https://yarnpkg.com/) - Package Manager: [npm 8+](https://www.npmjs.com/), [pnpm 8+](https://pnpm.io/), or [Yarn 2+](https://yarnpkg.com/)
[+node-versions]: **^20.6.0:** Versions `20.6.0` and above but below `21.0.0` [+node-versions]: **^20.19.0:** Versions `20.19.0` and above but below `21.0.0`
[+node-versions]: **>= 22.0.0:** Versions `22.0.0` and above [+node-versions]: **>= 22.0.0:** Versions `22.0.0` and above
:::: details How to Install Environment Dependencies? :::: details How to Install Environment Dependencies?

105
docs/guide/features/llmstxt.md Normal file
View File

@ -0,0 +1,105 @@
---
title: LLMs txt
icon: ri:ai
createTime: 2025/12/01 10:45:29
permalink: /guide/features/llmstxt/
---
## 概述
为站点添加 [llms.txt](https://llmstxt.org/)，以提供对 LLM 友好的内容。
**关联插件**： [@vuepress/plugin-llms](https://ecosystem.vuejs.press/zh/plugins/ai/llms.html)
## 为什么需要 llms.txt？
大型语言模型越来越依赖网站信息，但面临一个关键限制：上下文窗口太小，无法完整处理大多数网站。将包含导航、广告和 JavaScript 的复杂 HTML 页面转换为适合 LLM 的纯文本既困难又不精确。
虽然网站同时为人类读者和 LLM 服务，但后者受益于在一个可访问的位置收集的更简洁、专家级的信息。这对于开发环境等使用案例尤其重要，因为 LLM 需要快速访问编程文档和 API。
向网站添加 `/llms.txt` Markdown 文件，以提供对 LLM 友好的内容。此文件提供了简短的背景信息、指南和指向详细 Markdown 文件的链接。
## 功能
插件通过检索你的文档源目录中的所有 Markdown 文件，并将其转换为 LLM 友好的纯文本文件。
::: file-tree
- .vuepress/dist
- llms.txt
- llms-full.txt
- markdown-examples.html
- markdown-examples.md
- …
:::
点击以下链接查看本文档站点的 llms.txt 文件：
- [llms.txt](/llms.txt){.no-icon}
- [llms-full.txt](/llms-full.txt){.no-icon}
::: tip
插件仅在生产构建时，即执行 `vuepress build` 命令时，生成 `llms.txt` 文件，以及其它 LLM 友好的文档文件，并将它们输出到 `.vuepress/dist` 目录中。
:::
[完整功能说明请查看 **插件官方文档**](https://ecosystem.vuejs.press/zh/plugins/ai/llms.html#%E6%8F%92%E4%BB%B6%E5%8A%9F%E8%83%BD){.read-more}
## 配置
主题默认不启用此功能，你可以通过 `llmstxt` 配置项启用它：
```ts title=".vuepress/config.ts"
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
// 使用主题内置的默认配置
// llmstxt: true,
// 使用自定义配置
llmstxt: {
locale: '/',
// ...其它配置
},
// 也可以在 `plugins.llmstxt` 配置，但不推荐
plugins: {
llmstxt: true
}
}),
})
```
[完整配置项说明请查看 **插件官方文档**](https://ecosystem.vuejs.press/zh/plugins/ai/llms.html#options){.read-more}
## 组件
为进一步增强 文档站点 与 LLMs 的互动，你可以在文档站点中添加 `<PageContextMenu />` 组件。
该组件不作为内置组件，而是主题额外的 `features` 实现，因此你需要手动引入它，
并在合适的位置，通过 [组件插槽](../../guide/custom/slots.md) 添加到文档站点中：
```ts title=".vuepress/client.ts"
import { defineAsyncComponent, h } from 'vue'
import { Layout } from 'vuepress-theme-plume/client'
import PageContextMenu from 'vuepress-theme-plume/features/PageContextMenu.vue' // [!code ++]
import { defineClientConfig } from 'vuepress/client'
export default defineClientConfig({
layouts: {
Layout: h(Layout, null, {
// 将 PageContextMenu 添加到 doc-title-after 插槽，即文章标题的右侧
'doc-title-after': () => h(PageContextMenu), // [!code ++]
}),
},
})
```
你可以在当前页面的标题的右侧，体验该组件的功能。
::: important
此组件完全依赖于 `@vuepress/plugin-llms` 插件，仅当你启用了此插件功能后，才能使用它。
因此，此组件提供的功能 **仅在构建后的生产包中才可用** 。
:::

187
docs/guide/markdown/attrs.md Normal file
View File

@ -0,0 +1,187 @@
---
title: 属性支持
icon: ic:outline-data-object
createTime: 2025/11/30 18:02:41
permalink: /guide/markdown/attrs/
---
## 概述
为你的Markdown添加类、标识符和属性。
**此功能默认启用。**
## 语法
在 Markdown 的标记后使用 `{ }` 添加 类名、标识符 或 属性。
```md
markdown 语句{.classname #id attr1=value attr2="带空格的值"}
```
### `.classname`
以 `.` 作为起始，添加一个类型
**输入：**
```md
__加粗__{.bolder}
```
**输出：**
```html
<strong class="bolder">加粗</strong>
```
### `#id`
以 `#` 作为起始，添加一个 ID
**输入：**
```md
## 标题{#header-1}
```
**输出：**
```html
<h2 id="header-1">标题</h2>
```
:::tip 此技巧常用于自定义标题的锚点链接
:::
### `attr=value`
**输入：**
```md
[链接](https://example.com){target=_blank}
[链接](https://example.com){rel="noopener noreferrer"}
```
**输出：**
```html
<a href="https://example.com" target="_blank">链接</a>
<a href="https://example.com" rel="noopener noreferrer">链接</a>
```
### 组合使用
**输入：**
```md
[链接](https://example.com){.link #linkId target=_blank rel="noopener noreferrer"}
```
**输出：**
```html
<a href="https://example.com" class="link" id="linkId" target="_blank" rel="noopener noreferrer">链接</a>
```
### 在块级标记上
在块级标记的下一行添加属性。
比如在 无序列表 上使用
**输入：**
```md
- list item **bold**
{.red}
```
**输出：**
```html
<ul class="red">
<li class="red">list item <strong>bold</strong></li>
</ul>
```
比如在 表格 上使用
**输入：**
```md
| header1 | header2 |
| ------- | ------- |
| column1 | column2 |
{.special} <!-- 注意在这之前需要空一行 -->
```
**输出：**
```html
<table class="special">
<thead>
<tr>
<th>header1</th>
<th>header2</th>
</tr>
</thead>
<tbody>
<tr>
<td>column1</td>
<td>column2</td>
</tr>
</tbody>
</table>
```
表格中的单元格也可以使用，常见于 合并单元格：
**输入：**
```md
| A | B | C | D |
| ----------------------- | --- | --- | ---------------- |
| 1 | 11 | 111 | 1111 {rowspan=3} |
| 2 {colspan=2 rowspan=2} | 22 | 222 | 2222 |
| 3 | 33 | 333 | 3333 |
```
**输出：**
```html
<table border="1">
<thead>
<tr>
<th>A</th>
<th>B</th>
<th>C</th>
<th>D</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>11</td>
<td>111</td>
<td rowspan="3">1111</td>
</tr>
<tr>
<td colspan="2" rowspan="2">2</td>
<td>22</td>
</tr>
<tr>
<td>3</td>
</tr>
</tbody>
</table>
```
**效果：**
| A | B | C | D |
| ----------------------- | --- | --- | ---------------- |
| 1 | 11 | 111 | 1111 {rowspan=3} |
| 2 {colspan=2 rowspan=2} | 22 | 222 | 2222 |
| 3 | 33 | 333 | 3333 |

99
docs/guide/markdown/container.md Normal file
View File

@ -0,0 +1,99 @@
---
title: 提示容器
icon: mdi:message-text-outline
createTime: 2025/11/29 14:42:46
permalink: /guide/markdown/container/
---
::: tip 提示容器能够帮助你在文档中突出显示重要信息，让内容层次更加清晰。
:::
提示容器通过类型、标题和内容来定义不同的信息展示样式。
## 默认标题样式
**输入示例：**
```md
::: note
这是一个注释框
:::
::: info
这是一个信息框
:::
::: tip
这是一个提示框
:::
::: warning
这是一个警告框
:::
::: caution
这是一个危险警告框
:::
::: details
这是一个详情折叠框
:::
```
**实际效果：**
::: note
这是一个注释框
:::
::: info
这是一个信息框
:::
::: tip
这是一个提示框
:::
::: warning
这是一个警告框
:::
::: caution
这是一个危险警告框
:::
::: details
这是一个详情折叠框
:::
## 自定义标题设置
通过在容器类型后添加文本，可以轻松设置自定义标题。
**输入示例：**
````md
::: caution STOP
危险区域，请勿继续
:::
::: details 点我查看代码
```js
console.log('Hello, VitePress!')
```
:::
````
**实际效果：**
::: caution STOP
危险区域，请勿继续
:::
::: details 点我查看代码
```js
console.log('Hello, VuePress Plume!')
```
:::

66
docs/guide/markdown/emoji.md Normal file
View File

@ -0,0 +1,66 @@
---
title: emoji
icon: mdi:emoji-outline
createTime: 2025/11/29 14:03:43
permalink: /guide/markdown/emoji/
---
<script setup>
import EmojiList from '~/components/EmojiList.vue'
import { people, nature, foods, places, activities, symbols, objects, flags } from '~/composables/emoji'
</script>
## 快速上手
在 Markdown 中使用表情符号非常简单，只需用冒号包裹表情代码即可：
**输入示例：**
```md
:tada: :100:
```
**渲染效果：**
:tada: :100:
## 完整表情库
我们基于 [markdown-it-emoji](https://github.com/markdown-it/markdown-it-emoji) 插件提供完整的表情符号支持。
[如需查看所有可用的表情代码，请访问：**📋完整表情代码列表**](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs){.read-more}
::: tip 点击 emoji 表情即可复制表情符号到剪贴板。
:::
### 人物
<EmojiList :list="people" />
### 自然
<EmojiList :list="nature" />
### 食物
<EmojiList :list="foods" />
### 地点
<EmojiList :list="places" />
### 活动
<EmojiList :list="activities" />
### 符号
<EmojiList :list="symbols" />
### 物品
<EmojiList :list="objects" />
### 旗帜
<EmojiList :list="flags" />

202
docs/guide/markdown/extensions.md
View File

@ -75,20 +75,6 @@ tags:
| col 2 is | centered | $12 | | col 2 is | centered | $12 |
| zebra stripes | are neat | $1 | | zebra stripes | are neat | $1 |
## Emoji :tada:
**输入：**
```md
:tada: :100:
```
**输出：**
:tada: :100:
这里可以找到 [所有支持的 emoji 列表](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs)。
## 目录表 ## 目录表
**输入：** **输入：**
@ -101,168 +87,6 @@ tags:
[[TOC]] [[TOC]]
## 自定义容器
自定义容器可以通过它们的类型、标题和内容来定义。
### 默认标题
**输入：**
```md
::: note
This is a note box
:::
::: info
This is an info box.
:::
::: tip
This is a tip.
:::
::: warning
This is a warning.
:::
::: caution
This is a dangerous warning.
:::
::: details
This is a details block.
:::
```
**输出：**
::: note
This is a note box
:::
::: info
This is an info box.
:::
::: tip
This is a tip.
:::
::: warning
This is a warning.
:::
::: caution
This is a dangerous warning.
:::
::: details
This is a details block.
:::
### 自定义标题
可以通过在容器的 "type" 之后附加文本来设置自定义标题。
**输入：**
````md
::: caution STOP
危险区域，请勿继续
:::
::: details 点我查看代码
```js
console.log('Hello, VitePress!')
```
:::
````
**输出：**
::: caution STOP
危险区域，请勿继续
:::
::: details 点我查看代码
```js
console.log('Hello, VitePress!')
```
:::
## GitHub 风格的警报
主题 同样支持以标注的方式渲染 [GitHub 风格的警报](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)。它们和[自定义容器](#自定义容器)的渲染方式相同。
**输入：**
```md
> [!NOTE]
> 强调用户在快速浏览文档时也不应忽略的重要信息。
> [!TIP]
> 有助于用户更顺利达成目标的建议性信息。
> [!IMPORTANT]
> 对用户达成目标至关重要的信息。
> [!WARNING]
> 因为可能存在风险，所以需要用户立即关注的关键内容。
> [!CAUTION]
> 行为可能带来的负面影响。
```
**输出：**
> [!NOTE]
> 强调用户在快速浏览文档时也不应忽略的重要信息。
> [!TIP]
> 有助于用户更顺利达成目标的建议性信息。
> [!IMPORTANT]
> 对用户达成目标至关重要的信息。
> [!WARNING]
> 因为可能存在风险，所以需要用户立即关注的关键内容。
> [!CAUTION]
> 行为可能带来的负面影响。
## 数学方程
**输入：**
````
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?_ |
````
**输出：**
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?_ |
## 上下角标 ## 上下角标
- 使用 `^ ^` 进行上角标标注。 - 使用 `^ ^` 进行上角标标注。
@ -312,32 +136,6 @@ $$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
右对齐的内容 右对齐的内容
::: :::
## 属性支持
你可以使用特殊标记为 Markdown 元素添加属性。
**为图片添加属性：**
这将为图片添加 一个 名为 `full-width` 的 class 属性，以及一个 `width` 属性，值为 `100%`。
```md
![](/plume.png){.full-width width="100%"}
```
同时也支持其他属性:
```md
一个包含文字的段落。 {#p .a .b align=center customize-attr="content with spaces"}
```
这将被渲染为：
```html
<p id="p" class="a b" align="center" customize-attr="content with spaces">
一个包含文字的段落。
</p>
```
## 任务列表 ## 任务列表
**输入：** **输入：**

46
docs/guide/markdown/github-alerts.md Normal file
View File

@ -0,0 +1,46 @@
---
title: Github 警报
icon: mdi:alert-outline
createTime: 2025/11/29 19:59:45
permalink: /guide/markdown/github-alerts/
---
## GitHub 风格的警报
主题支持以标注的方式渲染 [GitHub 风格的警报](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)。它们和[提示容器](./container.md)的渲染方式相同。
**输入：**
```md
> [!NOTE]
> 强调用户在快速浏览文档时也不应忽略的重要信息。
> [!TIP]
> 有助于用户更顺利达成目标的建议性信息。
> [!IMPORTANT]
> 对用户达成目标至关重要的信息。
> [!WARNING]
> 因为可能存在风险，所以需要用户立即关注的关键内容。
> [!CAUTION]
> 行为可能带来的负面影响。
```
**输出：**
> [!NOTE]
> 强调用户在快速浏览文档时也不应忽略的重要信息。
> [!TIP]
> 有助于用户更顺利达成目标的建议性信息。
> [!IMPORTANT]
> 对用户达成目标至关重要的信息。
> [!WARNING]
> 因为可能存在风险，所以需要用户立即关注的关键内容。
> [!CAUTION]
> 行为可能带来的负面影响。

16
docs/guide/markdown/icons.md
View File

@ -3,9 +3,6 @@ title: 图标
createTime: 2024/09/30 14:49:39 createTime: 2024/09/30 14:49:39
icon: grommet-icons:emoji icon: grommet-icons:emoji
permalink: /guide/markdown/icon/ permalink: /guide/markdown/icon/
badge:
text: 变更
type: warning
--- ---
<script setup> <script setup>
@ -29,19 +26,6 @@ useScriptTag(
) )
</script> </script>
::: warning 图标语法糖在 `1.0.0-rc.144` 版本中进行了破坏性变更。
`:[collect:name size/color]:` 语法糖已弃用，请使用 `::collect:name =size /color::` 代替。
主题计划在未来的版本中，支持如 `iconfont` / `fontawesome` / `lucide` 等图标库的图标，原有语法糖
不足以支持新的扩展，因此此破坏性变更是必要的。
旧的语法在近期的版本中依然支持，但不再推荐使用，且在未来会删除。
主题会检测是否使用旧的语法，如果使用，会在控制台输出警告信息和修改建议，请根据修改建议进行调整。
:::
## 概述 ## 概述
主题支持在 Markdown 文件中以下来源的图标： 主题支持在 Markdown 文件中以下来源的图标：

147
docs/guide/markdown/math.md Normal file
View File

@ -0,0 +1,147 @@
---
title: 数学公式
icon: tabler:math
createTime: 2025/11/29 21:36:22
permalink: /guide/markdown/math/
---
## 概述
主题内置了对 数学公式 的支持。
该功能由 [@vuepress/plugin-markdown-math](https://ecosystem.vuejs.press/zh/plugins/markdown/markdown-math.html) 提供支持。你可以选择在 markdown 中使用以下方式渲染数学公式:
- `katex` (默认)
- `mathjax`
## 使用
```ts title=".vuepress/config.ts"
export default defineUserConfig({
theme: plumeTheme({
markdown: {
math: {
type: 'katex', // 'katex' | 'mathjax'
// ... 其它配置项
}
},
})
})
```
当你选择使用 `mathjax` 时，还需要执行以下命令安装依赖：
::: npm-to
```sh
npm i @mathjax/src
```
:::
## 语法
### 内联语法
使用 `$` 包裹数学公式 _（即在两个 `$` 之间编写数学公式）_
::: demo markdown title="内联模式" expanded
```md
Euler's identity $e^{i\pi}+1=0$ is a beautiful formula in $\mathbb{R}^2$.
```
:::
### 块级语法
使用 `$$` 包裹数学公式 _（即在两个 `$$` 之间编写数学公式）_
```md /$$/
<!-- 在两个 `$$` 之间编写数学公式，在单独的块中渲染 -->
$$xxx$$
<!-- 两个 `$$` 可以单独占一行，数学公式在它们之间 -->
$$
xxx
$$
```
:::demo markdown title="块级模式" expanded
```md
$$
\frac {\partial^r} {\partial \omega^r} \left(\frac {y^{\omega}} {\omega}\right)
= \left(\frac {y^{\omega}} {\omega}\right) \left\{(\log y)^r + \sum_{i=1}^r \frac {(-1)^ Ir \cdots (r-i+1) (\log y)^{ri}} {\omega^i} \right\}
$$
```
:::
## 相关教程
### TeX
[TeX 教程](https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes){.readmore}
[TeX 速查表](https://mdit-plugins.github.io/zh/tex.html#tex-tutorial){.readmore}
### KateX
[KateX 支持功能](https://katex.org/docs/supported.html){.readmore}
[KateX 支持列表](https://katex.org/docs/support_table.html){.readmore}
### Mathjax
[支持的 TeX / KateX 命令](https://docs.mathjax.org/en/latest/input/tex/macros/index.html#tex-commands){.readmore}
## 配置项
:::: field-group
::: field name="type" type="'katex' | 'mathjax'" default="'katex'"
用于渲染 $\TeX$ 内容的包。
- `'katex'`：使用 [KaTeX](https://katex.org/)
- `'mathjax'`：使用 [MathJax](https://www.mathjax.org/)
:::
:::field name="delimiters" type="'brackets' | 'dollars' | 'all'" default="'dollars'" optional
启用的数学分隔符语法。
- `"brackets"`: 使用 `\(...\)` 表示内联数学，使用 `\[...\]` 表示显示模式数学（LaTeX 风格）
- `"dollars"`: 使用 `$...$` 表示内联数学，使用 `$$...$$` 表示显示模式数学（常见 Markdown 风格）
- `"all"`: 启用括号和美元符号两种语法
:::
::::
### 使用 KaTeX
使用 KaTeX 时，任何其他选项都将作为 `KatexOptions` 传递给 KaTeX。有关所有可用选项，请参阅 [KaTeX 文档](https://katex.org/docs/options.html)。
此外，还支持 2 个特殊选项：
:::: field-group
::: field name="copy" type="boolean" optional default="false"
是否启用复制扩展。
:::
::: field name="mhchem" type="boolean" optional default="false"
是否启用 mhchem 扩展。
:::
::::
### 使用 MathJax
使用 MathJax 时，你可以设置：
:::: field-group
:::field name="tex" type="object" optional
传递给 TeX 输入解析器的选项。
:::
::: field name="output" type="'svg' | 'chtml'" default="'svg'" optional
输出格式，SVG 或通用 HTML。
:::
::: field name="chtml" type="object" optional
传递给通用 HTML 输出解析器的选项。
:::
::: field name="svg" type="object" optional
传递给 SVG 输出解析器的选项。
:::
::::

58
docs/guide/markdown/table.md
View File

@ -287,6 +287,10 @@ export default defineUserConfig({
### 表格单元格高亮 ### 表格单元格高亮
#### 方式一
在表格容器上使用 `hl-cells="type:(row,col)"` 的格式，可以使用 `;` 组合多个 type cell。
**输入：** **输入：**
```md ```md
@ -311,6 +315,34 @@ export default defineUserConfig({
::: :::
#### 方式二
使用 [属性支持](./attrs.md) 语法
**输入：**
```md
::: table title="这是表格标题"
| (1,1) {.danger} | (1,2) | (1,3) | (1,4) {.warning} |
| ------------------ | ------------------ | ---------------- | ----------------- |
| (2,1) | (2,2) {.danger} | (2,3) {.warning} | (2,4) |
| (3,1) | (3,2) {.important} | (3,3) {.danger} | (3,4) |
| (4,1) {.important} | (4,2) | (4,3) | (4,4) {.danger} |
:::
```
**输出：**
::: table title="这是表格标题"
| (1,1) {.danger} | (1,2) | (1,3) | (1,4) {.warning} |
| ------------------ | ------------------ | ---------------- | ----------------- |
| (2,1) | (2,2) {.danger} | (2,3) {.warning} | (2,4) |
| (3,1) | (3,2) {.important} | (3,3) {.danger} | (3,4) |
| (4,1) {.important} | (4,2) | (4,3) | (4,4) {.danger} |
:::
## 自定义高亮类型 ## 自定义高亮类型
在 [自定义 CSS 样式](../custom/style.md) 中，通过以下格式可以自定义高亮类型： 在 [自定义 CSS 样式](../custom/style.md) 中，通过以下格式可以自定义高亮类型：
@ -360,3 +392,29 @@ export default defineUserConfig({
| Cell 4 | Cell 5 | Cell 6 | | Cell 4 | Cell 5 | Cell 6 |
::: :::
## 表格单元格合并
表格单元格合并由 [markdown-it-attrs](https://github.com/arve0/markdown-it-attrs) 属性支持语法提供实现。
因此它不需要在 `:::table` 容器中使用，你可以在何人表格中使用它。
在表格单元格内，末尾部分使用 属性支持语法 `{}` 中，添加 `rowspan=rows` 或者 `{colspan=cols}` ，或组合使用，
即可实现表格单元格合并。
**输入：**
```md
| A | B | C | D |
| ----------------------- | --- | --- | ---------------- |
| 1 | 11 | 111 | 1111 {rowspan=3} |
| 2 {colspan=2 rowspan=2} | 22 | 222 | 2222 |
| 3 | 33 | 333 | 3333 |
```
**输出：**
| A | B | C | D |
| ----------------------- | --- | --- | ---------------- |
| 1 | 11 | 111 | 1111 {rowspan=3} |
| 2 {colspan=2 rowspan=2} | 22 | 222 | 2222 |
| 3 | 33 | 333 | 3333 |

4
docs/guide/quick-start/usage.md
View File

@ -10,10 +10,10 @@ tags:
## 环境要求 ## 环境要求
- [Node.js](https://nodejs.org/)：**^20.6.0 或 >= 22.0.0** [+node-versions] - [Node.js](https://nodejs.org/)：**^20.19.0 或 >= 22.0.0** [+node-versions]
- 包管理器：[npm 8+](https://www.npmjs.com/)、[pnpm 8+](https://pnpm.io/zh/) 或 [Yarn 2+](https://yarnpkg.com/) - 包管理器：[npm 8+](https://www.npmjs.com/)、[pnpm 8+](https://pnpm.io/zh/) 或 [Yarn 2+](https://yarnpkg.com/)
[+node-versions]: **^20.6.0：** `20.6.0` 及以上但低于 `21.0.0` 的版本 [+node-versions]: **^20.19.0：** `20.19.0` 及以上但低于 `21.0.0` 的版本
[+node-versions]: **>= 22.0.0：** `22.0.0` 及以上的版本 [+node-versions]: **>= 22.0.0：** `22.0.0` 及以上的版本
:::: details 如何安装环境依赖？ :::: details 如何安装环境依赖？