create-vuepress-theme-plume 1.0.0-rc.149 → 1.0.0-rc.151

package/lib/index.js

@@ -13,7 +13,7 @@ import handlebars from "handlebars";
 import { osLocale } from "os-locale";
 
 //#region package.json
-var version = "1.0.0-rc.148";
+var version = "1.0.0-rc.150";
 
 //#endregion
 //#region src/constants.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-vuepress-theme-plume",
   "type": "module",
-  "version": "1.0.0-rc.149",
+  "version": "1.0.0-rc.151",
   "description": "The cli for create vuepress-theme-plume's project",
   "author": "pengzhanbo <q942450674@outlook.com> (https://github.com/pengzhanbo/)",
   "license": "MIT",

package/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.{{#if useTs}}ts{{else}}js{{/if}}` 文件中配置
+ *
+ * 特别的，请不要在两个配置文件中重复配置相同的项，当前文件的配置项会被覆盖
+ */
+
 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)

package/templates/.vuepress/navbar.ts.handlebars

@@ -1,3 +1,9 @@
+/**
+ * @see https://theme-plume.vuejs.press/config/navigation/ 查看文档了解配置详情
+ *
+ * Navbar 配置文件，它在 `.vuepress/plume.config.{{#if useTs}}ts{{else}}js{{/if}}` 中被导入。
+ */
+
 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/' },

package/templates/.vuepress/notes.ts.handlebars

@@ -1,3 +1,24 @@
+/**
+ * @see https://theme-plume.vuejs.press/guide/document/ 查看文档了解配置详情。
+ *
+ * Notes 配置文件，它在 `.vuepress/plume.config.{{#if useTs}}ts{{else}}js{{/if}}` 中被导入。
+ *
+ * 请注意，你应该先在这里配置好 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],

package/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.{{#if useTs}}ts{{else}}js{{/if}}` 文件中配置
+ *
+ * 特别的，请不要在两个配置文件中重复配置相同的项，当前文件的配置项会覆盖 `.vuepress/config.{{#if useTs}}ts{{else}}js{{/if}}` 文件中的配置
+ */
+
 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}}
 
 /**