diff --git a/skills/README.md b/skills/README.md index ff26feda..41b60e4f 100644 --- a/skills/README.md +++ b/skills/README.md @@ -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`
• Manages `themeConfig`, `navbar`, `sidebar`
• Supports `locales` and `plugins` configuration | -| **vuepress-plume-markdown** | Markdown Writing Assistant | • Provides syntax for Plume's Markdown extensions
• Supports Charts (Mermaid, ECharts, etc.)
• Supports Embeds (YouTube, Bilibili, PDF) | +| **vuepress-plume-config** | Theme Configuration Generator | • Generates `config.ts`, `plume.config.ts`
• Manages `collections`, `navbar`, `sidebar`, `locales`
• Supports `plugins`, `markdown`, `codeHighlighter`
• Configures `encrypt`, `bulletin`, `copyright`, `llmstxt`
• Supports `search`, `comment`, `watermark` | +| **vuepress-plume-markdown** | Markdown Writing Assistant | • Provides syntax for Plume's Markdown extensions
• Supports Containers (hint, alert, details, etc.)
• Supports Charts (Mermaid, ECharts, Chart.js, etc.)
• Supports Embeds (YouTube, Bilibili, PDF, CodePen, etc.)
• Code block features (highlight, focus, diff, etc.)
• LLMs txt markup (``, ``) | ### 🔍 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 + + +## Additional Context for AI + +This section only appears in the LLM-friendly version of the documentation. + + +``` + --- ## 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) diff --git a/skills/README.zh-CN.md b/skills/README.zh-CN.md index 2a0ea031..2e5ec18a 100644 --- a/skills/README.zh-CN.md +++ b/skills/README.zh-CN.md @@ -10,20 +10,24 @@ | 技能名称 | 描述 | 主要特性 | | ---------- | ----------- | ------------ | -| **vuepress-plume-config** | 主题配置生成器 | • 生成 `config.ts`, `plume.config.ts`
• 管理 `themeConfig`, `navbar`, `sidebar`
• 支持 `locales` 和 `plugins` 配置 | -| **vuepress-plume-markdown** | Markdown 写作助手 | • 提供 Plume Markdown 扩展语法
• 支持图表 (Mermaid, ECharts 等)
• 支持嵌入 (YouTube, Bilibili, PDF) | +| **vuepress-plume-config** | 主题配置生成器 | • 生成 `config.ts`、`plume.config.ts`
• 管理 `collections`、`navbar`、`sidebar`、`locales`
• 支持 `plugins`、`markdown`、`codeHighlighter`
• 配置 `encrypt`、`bulletin`、`copyright`、`llmstxt`
• 支持 `search`、`comment`、`watermark` | +| **vuepress-plume-markdown** | Markdown 写作助手 | • 提供 Plume Markdown 扩展语法
• 支持容器（hint、alert、details 等）
• 支持图表（Mermaid、ECharts、Chart.js 等）
• 支持嵌入（YouTube、Bilibili、PDF、CodePen 等）
• 代码块特性（highlight、focus、diff 等）
• LLMs txt 标记（``、``） | ### 🔍 选择指南 - **使用 `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 + + +## Additional Context for AI + +This section only appears in the LLM-friendly version of the documentation. + + +``` + --- ## 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)