yuany3721/vuepress-theme-plume
1
0
Fork 0
forked from gitea-yuany3721/vuepress-theme-plume
Code Pull Requests Activity

docs: update skills usage doc

Browse Source
This commit is contained in:
pengzhanbo 2026-03-06 16:40:02 +08:00
parent f14d663bb5
commit 17646708b1
2 changed files with 287 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

155
skills/README.md
View File

@ -10,20 +10,24 @@ The `skills` directory currently provides the following skills:
| Skill Name | Description | Key Features |
| ---------- | ----------- | ------------ |
| **vuepress-plume-config** | Theme Configuration Generator | • Generates `config.ts`, `plume.config.ts`<br>• Manages `themeConfig`, `navbar`, `sidebar`<br>• Supports `locales` and `plugins` configuration |
| **vuepress-plume-markdown** | Markdown Writing Assistant | • Provides syntax for Plume's Markdown extensions<br>• Supports Charts (Mermaid, ECharts, etc.)<br>• Supports Embeds (YouTube, Bilibili, PDF) |
| **vuepress-plume-config** | Theme Configuration Generator | • Generates `config.ts`, `plume.config.ts`<br>• Manages `collections`, `navbar`, `sidebar`, `locales`<br>• Supports `plugins`, `markdown`, `codeHighlighter`<br>• Configures `encrypt`, `bulletin`, `copyright`, `llmstxt`<br>• Supports `search`, `comment`, `watermark` |
| **vuepress-plume-markdown** | Markdown Writing Assistant | • Provides syntax for Plume's Markdown extensions<br>• Supports Containers (hint, alert, details, etc.)<br>• Supports Charts (Mermaid, ECharts, Chart.js, etc.)<br>• Supports Embeds (YouTube, Bilibili, PDF, CodePen, etc.)<br>• Code block features (highlight, focus, diff, etc.)<br>• LLMs txt markup (`<llm-only>`, `<llm-exclude>`) |
### 🔍 Selection Guide
- **Use `vuepress-plume-config` when:**
- You are initializing a new VuePress Plume project.
- You need to update the theme configuration, navbar, or sidebar.
- You want to configure complex settings like locales or plugins.
- You need to update the theme configuration, navbar, sidebar, or collections.
- You want to configure complex settings like locales, plugins, or markdown extensions.
- You need to set up encryption, comments, search, or other advanced features.
- You want to enable LLMs txt generation for AI assistant integration.
- **Use `vuepress-plume-markdown` when:**
- You are writing content in Markdown files.
- You want to use advanced features like containers, code groups, or diagrams.
- You need to embed media or external content.
- You want to use advanced features like containers, code groups, tabs, or diagrams.
- You need to embed media (videos, PDFs) or external content (CodePen, CodeSandbox).
- You want to add code block features like line highlighting, diff, or focus.
- You need to create charts (Mermaid, ECharts) or mind maps (Markmap).
---
@ -38,7 +42,7 @@ You can install these skills into your project or globally using the `skills` CL
### Installation Steps
1. **Install specific skills from this repository:**
1. **Install skills from this repository:**
```bash
# Install into your current project (recommended for teams)
@ -109,17 +113,41 @@ If Trae doesn't recognize the skill, ensure the `SKILL.md` file is valid and con
### 🛠️ Using `vuepress-plume-config`
**Scenario:** Initialize a new configuration file.
#### Example 1: Initialize a Blog Configuration
**Prompt:**
> "Generate a `config.ts` for my VuePress Plume site with a blog setup, English and Chinese locales, and the filesystem cache enabled."
**Outcome:**
The agent will use the skill to create a `src/.vuepress/config.ts` file with the requested configuration structure.
The agent will use the skill to create a `.vuepress/config.ts` file with the requested configuration structure.
#### Example 2: Configure Collections
**Prompt:**
> "Add a post collection for my blog at `blog/` directory with tags, categories, and archives enabled."
**Outcome:**
The agent will generate the appropriate `collections` configuration.
#### Example 3: Enable Encryption
**Prompt:**
> "Configure partial encryption for all pages under `/secret/` directory with password 'mypassword'."
**Outcome:**
The agent will add the `encrypt` configuration with the specified rules.
#### Example 4: Setup Comments with Giscus
**Prompt:**
> "Configure Giscus comments for my VuePress Plume site with repo 'user/repo' and category 'Announcements'."
**Outcome:**
The agent will add the `comment` configuration with Giscus provider settings.
### 📝 Using `vuepress-plume-markdown`
**Scenario:** Add a complex diagram to a documentation page.
#### Example 1: Add a Timeline
**Prompt:**
> "I want to add a timeline of VuePress release history to my markdown file using the Plume timeline extension."
@ -128,15 +156,91 @@ The agent will use the skill to create a `src/.vuepress/config.ts` file with the
The agent will reference the `vuepress-plume-markdown` skill to provide the correct syntax:
```markdown
::: timeline 2024
2024-01-01: **VuePress Plume v1.0.0 Released**
The first official release.
::: timeline
- Node 1
time=2025-03-20 type=success
2024-06-01: **Feature Update**
Added support for new markdown extensions.
Content
- Node 2
time=2025-02-21 type=warning
Content
- Node 3
time=2025-01-22 type=danger
Content
:::
```
#### Example 2: Code Block with Features
**Prompt:**
> "Show me how to create a code block with line numbers, title, and highlighted lines 2-4."
**Outcome:**
The agent will provide the syntax:
````markdown
```ts title="example.ts":line-numbers {2-4}
const line1 = 'normal'
const line2 = 'highlighted'
const line3 = 'highlighted'
const line4 = 'highlighted'
const line5 = 'normal'
```
````
#### Example 3: Embed a Bilibili Video
**Prompt:**
> "How do I embed a Bilibili video with BV ID 'BV1xx411c7mD' in my markdown?"
**Outcome:**
The agent will provide the embed syntax:
```markdown
@[bilibili](BV1xx411c7mD)
```
#### Example 4: Create a Mermaid Diagram
**Prompt:**
> "Create a flowchart using Mermaid showing the build process of VuePress."
**Outcome:**
The agent will provide:
````markdown
```mermaid
flowchart TD
A[Source Files] --> B[Markdown Processing]
B --> C[Vue Components]
C --> D[Webpack/Vite Build]
D --> E[Static HTML]
E --> F[Deploy]
```
````
#### Example 5: Use LLMs txt Markup
**Prompt:**
> "How can I add content that's only visible in LLM-generated files?"
**Outcome:**
The agent will provide:
```markdown
<llm-only>
## Additional Context for AI
This section only appears in the LLM-friendly version of the documentation.
</llm-only>
```
---
## 5. Best Practices
@ -150,7 +254,28 @@ Added support for new markdown extensions.
npx skills update
```
- **Feature Enablement:** Most markdown extensions need to be enabled in `.vuepress/config.ts`. Ensure you have the required features enabled before using them.
### Performance & Security
- **Review Changes:** Always review the configuration files generated by the `vuepress-plume-config` skill before deploying.
- **Safe Execution:** These skills primarily generate text/code. They do not execute system commands directly without user confirmation in most agent environments.
- **Encryption:** When using the `encrypt` feature, ensure your site is served over HTTPS for partial content encryption to work properly.
- **Cache Management:** When enabling cache, remember to remove `--clean-cache` from your dev script to benefit from caching.
---
## 6. Resources
### Documentation Links
- [Theme Configuration](https://theme-plume.vuejs.press/config/theme/)
- [Collections Configuration](https://theme-plume.vuejs.press/config/collections/)
- [Markdown Extensions](https://theme-plume.vuejs.press/guide/markdown/extensions/)
- [Code Features](https://theme-plume.vuejs.press/guide/code/features/)
- [Plugins](https://theme-plume.vuejs.press/config/plugins/)
### Related Projects
- [VuePress](https://v2.vuepress.vuejs.org/)
- [VuePress Theme Plume](https://github.com/pengzhanbo/vuepress-theme-plume)

162
skills/README.zh-CN.md
View File

@ -10,20 +10,24 @@
| 技能名称 | 描述 | 主要特性 |
| ---------- | ----------- | ------------ |
| **vuepress-plume-config** | 主题配置生成器 | • 生成 `config.ts`, `plume.config.ts`<br>• 管理 `themeConfig`, `navbar`, `sidebar`<br>• 支持 `locales` 和 `plugins` 配置 |
| **vuepress-plume-markdown** | Markdown 写作助手 | • 提供 Plume Markdown 扩展语法<br>• 支持图表 (Mermaid, ECharts 等)<br>• 支持嵌入 (YouTube, Bilibili, PDF) |
| **vuepress-plume-config** | 主题配置生成器 | • 生成 `config.ts`、`plume.config.ts`<br>• 管理 `collections`、`navbar`、`sidebar`、`locales`<br>• 支持 `plugins`、`markdown`、`codeHighlighter`<br>• 配置 `encrypt`、`bulletin`、`copyright`、`llmstxt`<br>• 支持 `search`、`comment`、`watermark` |
| **vuepress-plume-markdown** | Markdown 写作助手 | • 提供 Plume Markdown 扩展语法<br>• 支持容器（hint、alert、details 等）<br>• 支持图表（Mermaid、ECharts、Chart.js 等）<br>• 支持嵌入（YouTube、Bilibili、PDF、CodePen 等）<br>• 代码块特性（highlight、focus、diff 等）<br>• LLMs txt 标记（`<llm-only>`、`<llm-exclude>`） |
### 🔍 选择指南
- **使用 `vuepress-plume-config` 的场景：**
- 初始化一个新的 VuePress Plume 项目。
- 需要更新主题配置、导航栏或侧边栏。
- 需要配置复杂设置，如多语言或插件。
- 需要更新主题配置、导航栏、侧边栏或集合。
- 需要配置复杂设置，如多语言、插件或 Markdown 扩展。
- 需要设置加密、评论、搜索或其他高级功能。
- 想要启用 LLMs txt 生成以集成 AI 助手。
- **使用 `vuepress-plume-markdown` 的场景：**
- 编写 Markdown 内容文件。
- 需要使用高级功能，如容器、代码组或图表。
- 需要嵌入媒体或外部内容。
- 需要使用高级功能，如容器、代码组、标签页或图表。
- 需要嵌入媒体（视频、PDF）或外部内容（CodePen、CodeSandbox）。
- 想要添加代码块特性，如行高亮、diff 或焦点。
- 需要创建图表（Mermaid、ECharts）或思维导图（Markmap）。
---
@ -38,7 +42,7 @@
### 安装步骤
1. **从本仓库安装特定技能：**
1. **从本仓库安装技能：**
```bash
# 安装到当前项目（团队协作推荐）
@ -109,18 +113,45 @@ Trae 是一个强大的 IDE，可以利用这些技能更好地协助您。
### 🛠️ 使用 `vuepress-plume-config`
**场景：** 初始化一个新的配置文件。
#### 示例 1：初始化博客配置
**提示词：**
> "Generate a `config.ts` for my VuePress Plume site with a blog setup, English and Chinese locales, and the filesystem cache enabled."
> （"为我的 VuePress Plume 站点生成一个 `config.ts`，包含博客设置、中英文多语言支持，并启用文件系统缓存。"）
**结果：**
代理将使用技能创建一个包含请求配置结构的 `src/.vuepress/config.ts` 文件。
代理将使用技能创建一个包含请求配置结构的 `.vuepress/config.ts` 文件。
#### 示例 2：配置集合
**提示词：**
> "Add a post collection for my blog at `blog/` directory with tags, categories, and archives enabled."
> （"为我的博客添加一个 post 集合，目录为 `blog/`，并启用标签、分类和归档功能。"）
**结果：**
代理将生成相应的 `collections` 配置。
#### 示例 3：启用加密
**提示词：**
> "Configure partial encryption for all pages under `/secret/` directory with password 'mypassword'."
> （"为 `/secret/` 目录下的所有页面配置部分加密，密码为 'mypassword'。"）
**结果：**
代理将添加包含指定规则的 `encrypt` 配置。
#### 示例 4：配置 Giscus 评论
**提示词：**
> "Configure Giscus comments for my VuePress Plume site with repo 'user/repo' and category 'Announcements'."
> （"为我的 VuePress Plume 站点配置 Giscus 评论，仓库为 'user/repo'，分类为 'Announcements'。"）
**结果：**
代理将添加包含 Giscus 提供者设置的 `comment` 配置。
### 📝 使用 `vuepress-plume-markdown`
**场景：** 向文档页面添加复杂图表。
#### 示例 1：添加时间轴
**提示词：**
> "I want to add a timeline of VuePress release history to my markdown file using the Plume timeline extension."
@ -130,15 +161,95 @@ Trae 是一个强大的 IDE，可以利用这些技能更好地协助您。
代理将引用 `vuepress-plume-markdown` 技能提供正确的语法：
```markdown
::: timeline 2024
2024-01-01: **VuePress Plume v1.0.0 Released**
The first official release.
::: timeline
- 节点一
time=2025-03-20 type=success
2024-06-01: **Feature Update**
Added support for new markdown extensions.
正文内容
- 节点二
time=2025-02-21 type=warning
正文内容
- 节点三
time=2025-01-22 type=danger
正文内容
:::
```
#### 示例 2：带特性的代码块
**提示词：**
> "Show me how to create a code block with line numbers, title, and highlighted lines 2-4."
> （"展示如何创建一个带行号、标题和高亮第 2-4 行的代码块。"）
**结果：**
代理将提供语法：
````markdown
```ts title="example.ts":line-numbers {2-4}
const line1 = 'normal'
const line2 = 'highlighted'
const line3 = 'highlighted'
const line4 = 'highlighted'
const line5 = 'normal'
```
````
#### 示例 3：嵌入 Bilibili 视频
**提示词：**
> "How do I embed a Bilibili video with BV ID 'BV1xx411c7mD' in my markdown?"
> （"如何在 Markdown 中嵌入 BV ID 为 'BV1xx411c7mD' 的 Bilibili 视频？"）
**结果：**
代理将提供嵌入语法：
```markdown
@[bilibili](BV1xx411c7mD)
```
#### 示例 4：创建 Mermaid 图表
**提示词：**
> "Create a flowchart using Mermaid showing the build process of VuePress."
> （"使用 Mermaid 创建一个展示 VuePress 构建流程的流程图。"）
**结果：**
代理将提供：
````markdown
```mermaid
flowchart TD
A[Source Files] --> B[Markdown Processing]
B --> C[Vue Components]
C --> D[Webpack/Vite Build]
D --> E[Static HTML]
E --> F[Deploy]
```
````
#### 示例 5：使用 LLMs txt 标记
**提示词：**
> "How can I add content that's only visible in LLM-generated files?"
> （"如何添加仅在 LLM 生成文件中可见的内容？"）
**结果：**
代理将提供：
```markdown
<llm-only>
## Additional Context for AI
This section only appears in the LLM-friendly version of the documentation.
</llm-only>
```
---
## 5. 最佳实践
@ -152,7 +263,28 @@ Added support for new markdown extensions.
npx skills update
```
- **功能启用：** 大多数 Markdown 扩展需要在 `.vuepress/config.ts` 中启用。在使用前请确保已启用所需功能。
### 性能与安全
- **审查更改：** 在部署之前，始终审查由 `vuepress-plume-config` 技能生成的配置文件。
- **安全执行：** 这些技能主要生成文本/代码。在大多数代理环境中，未经用户确认，它们不会直接执行系统命令。
- **加密：** 使用 `encrypt` 功能时，请确保您的站点通过 HTTPS 提供服务，以便部分内容加密正常工作。
- **缓存管理：** 启用缓存时，请记得从开发脚本中移除 `--clean-cache` 以便从缓存中受益。
---
## 6. 资源
### 文档链接
- [主题配置](https://theme-plume.vuejs.press/config/theme/)
- [集合配置](https://theme-plume.vuejs.press/config/collections/)
- [Markdown 扩展](https://theme-plume.vuejs.press/guide/markdown/extensions/)
- [代码特性](https://theme-plume.vuejs.press/guide/code/features/)
- [插件](https://theme-plume.vuejs.press/config/plugins/)
### 相关项目
- [VuePress](https://v2.vuepress.vuejs.org/)
- [VuePress Theme Plume](https://github.com/pengzhanbo/vuepress-theme-plume)