From 2ced06b72933eb9ed0e1c940ad029521c7ad7e4d Mon Sep 17 00:00:00 2001 From: pengzhanbo Date: Mon, 19 May 2025 21:13:30 +0800 Subject: [PATCH] feat(cli): improve template --- cli/templates/.vuepress/config.ts.handlebars | 13 +++++- cli/templates/.vuepress/navbar.ts.handlebars | 8 +++- cli/templates/.vuepress/notes.ts.handlebars | 45 ++++++++++++++++++- .../.vuepress/plume.config.ts.handlebars | 16 ++++++- 4 files changed, 77 insertions(+), 5 deletions(-) diff --git a/cli/templates/.vuepress/config.ts.handlebars b/cli/templates/.vuepress/config.ts.handlebars index 889ea84d..1d7be565 100644 --- a/cli/templates/.vuepress/config.ts.handlebars +++ b/cli/templates/.vuepress/config.ts.handlebars @@ -1,3 +1,14 @@ +/** + * 查看以下文档了解主题配置 + * - @see https://theme-plume.vuejs.press/config/intro/ 配置说明 + * - @see https://theme-plume.vuejs.press/config/theme/ 主题配置项 + * + * 请注意，对此文件的修改都会重启 vuepress 服务。 + * 部分配置项的更新没有必要重启 vuepress 服务，建议请在 `.vuepress/config.{{ useTs ? 'ts' : 'js' }}` 文件中配置 + * + * 特别的，请不要在两个配置文件中重复配置相同的项，当前文件的配置项会被覆盖 + */ + import { {{ bundler }}Bundler } from '@vuepress/bundler-{{ bundler }}' import { defineUserConfig } from 'vuepress' import { plumeTheme } from 'vuepress-theme-plume' @@ -118,7 +129,7 @@ export default defineUserConfig({ // youtube: true, // 启用嵌入 youtube视频 语法 @[youtube](video_id) // artPlayer: true, // 启用嵌入 artPlayer 本地视频 语法 @[artPlayer](url) // audioReader: true, // 启用嵌入音频朗读功能 语法 @[audioReader](url) - // icons: true, // 启用内置图标语法 ::icon-name:: + // icon: { provider: 'iconify' }, // 启用内置图标语法 ::icon-name:: // codepen: true, // 启用嵌入 codepen 语法 @[codepen](user/slash) // replit: true, // 启用嵌入 replit 语法 @[replit](user/repl-name) // codeSandbox: true, // 启用嵌入 codeSandbox 语法 @[codeSandbox](id) diff --git a/cli/templates/.vuepress/navbar.ts.handlebars b/cli/templates/.vuepress/navbar.ts.handlebars index 6f3cace0..ef1513db 100644 --- a/cli/templates/.vuepress/navbar.ts.handlebars +++ b/cli/templates/.vuepress/navbar.ts.handlebars @@ -1,3 +1,9 @@ +/** + * @see https://theme-plume.vuejs.press/config/navigation/ 查看文档了解配置详情 + * + * Navbar 配置文件，它在 `.vuepress/plume.config.{{ useTs ? 'ts' : 'js' }}` 中被导入。 + */ + import { defineNavbarConfig } from 'vuepress-theme-plume' {{#if multiLanguage}} @@ -15,7 +21,7 @@ export const {{prefix}}Navbar = defineNavbarConfig([ {{/each}} {{else}} -export const navbar = defineNavbarConfig([ +export default defineNavbarConfig([ { text: '{{#if isEn}}Home{{else}}首页{{/if}}', link: '/' }, { text: '{{#if isEn}}Blog{{else}}博客{{/if}}', link: '/blog/' }, { text: '{{#if isEn}}Tags{{else}}标签{{/if}}', link: '/blog/tags/' }, diff --git a/cli/templates/.vuepress/notes.ts.handlebars b/cli/templates/.vuepress/notes.ts.handlebars index b5e4118a..88d11477 100644 --- a/cli/templates/.vuepress/notes.ts.handlebars +++ b/cli/templates/.vuepress/notes.ts.handlebars @@ -1,3 +1,24 @@ +/** + * @see https://theme-plume.vuejs.press/guide/document/ 查看文档了解配置详情。 + * + * Notes 配置文件，它在 `.vuepress/plume.config.{{ useTs ? 'ts' : 'js' }}` 中被导入。 + * + * 请注意，你应该先在这里配置好 Notes，然后再启动 vuepress，主题会在启动 vuepress 时， + * 读取这里配置的 Notes，然后在与 Note 相关的 Markdown 文件中，自动生成 permalink。 + * + * 如果你发现 侧边栏没有显示，那么请检查你的配置是否正确，以及 Markdown 文件中的 permalink + * 是否是以对应的 note 配置的 link 的前缀开头。 是否展示侧边栏是根据 页面链接 的前缀 与 `note.link` + * 的前缀是否匹配来决定。 + */ + +/** + * 在受支持的 IDE 中会智能提示配置项。 + * + * - `defineNoteConfig` 是用于定义单个 note 配置的帮助函数 + * - `defineNotesConfig` 是用于定义 notes 集合的帮助函数 + * + * 通过 `defineNoteConfig` 定义的 note 配置，应该填入 `defineNotesConfig` 的 notes 数组中 + */ import { defineNoteConfig, defineNotesConfig } from 'vuepress-theme-plume' {{#if multiLanguage}} @@ -6,10 +27,21 @@ import { defineNoteConfig, defineNotesConfig } from 'vuepress-theme-plume' const {{ prefix }}DemoNote = defineNoteConfig({ dir: 'demo', + // `dir` 所指向的目录中的所有 markdown 文件，其 permalink 需要以 `link` 配置作为前缀 + // 如果 前缀不一致，则无法生成侧边栏。 + // 所以请确保 markdown 文件的 permalink 都以 `link` 开头 link: '/demo', + // 手动配置侧边栏结构 sidebar: ['', 'foo', 'bar'], + // 根据文件结构自动生成侧边栏 + // sidebar: 'auto', }) +/** + * 导出所有的 note + * 每一个 note 都应该填入到 `notes.notes` 数组中 + * （{{ prefix }}DemoNote 为参考示例，如果不需要它，请删除） + */ export const {{ prefix }}Notes = defineNotesConfig({ dir: '{{ removeLeadingSlash path }}notes', link: '{{ path }}', @@ -20,11 +52,22 @@ export const {{ prefix }}Notes = defineNotesConfig({ {{else}} const demoNote = defineNoteConfig({ dir: 'demo', + // `dir` 所指向的目录中的所有 markdown 文件，其 permalink 需要以 `link` 配置作为前缀 + // 如果 前缀不一致，则无法生成侧边栏。 + // 所以请确保 markdown 文件的 permalink 都以 `link` 开头 link: '/demo', + // 手动配置侧边栏结构 sidebar: ['', 'foo', 'bar'], + // 根据文件结构自动生成侧边栏 + // sidebar: 'auto', }) -export const notes = defineNotesConfig({ +/** + * 导出所有的 note + * 每一个 note 都应该填入到 `notes.notes` 数组中 + * （DemoNote 为参考示例，如果不需要它，请删除） + */ +export default defineNotesConfig({ dir: 'notes', link: '/', notes: [demoNote], diff --git a/cli/templates/.vuepress/plume.config.ts.handlebars b/cli/templates/.vuepress/plume.config.ts.handlebars index 1c72a646..cf25aea2 100644 --- a/cli/templates/.vuepress/plume.config.ts.handlebars +++ b/cli/templates/.vuepress/plume.config.ts.handlebars @@ -1,10 +1,22 @@ +/** + * 查看以下文档了解主题配置 + * - @see https://theme-plume.vuejs.press/config/intro/ 配置说明 + * - @see https://theme-plume.vuejs.press/config/theme/ 主题配置项 + * + * 请注意，对此文件的修改不会重启 vuepress 服务，而是通过热更新的方式生效 + * 但同时部分配置项不支持热更新，请查看文档说明 + * 对于不支持热更新的配置项，请在 `.vuepress/config.{{ useTs ? 'ts' : 'js' }}` 文件中配置 + * + * 特别的，请不要在两个配置文件中重复配置相同的项，当前文件的配置项会覆盖 `.vuepress/config.{{ useTs ? 'ts' : 'js' }}` 文件中的配置 + */ + import { defineThemeConfig } from 'vuepress-theme-plume' {{#if multiLanguage}} import { enNavbar, zhNavbar } from './navbar' import { enNotes, zhNotes } from './notes' {{else}} -import { navbar } from './navbar' -import { notes } from './notes' +import navbar from './navbar' +import notes from './notes' {{/if}} /**