feat(plugin-notice): add markdown format support for notice content, close #376 (#382)

Author: pengzhanbo

docs/plugins/features/notice.md

@@ -33,7 +33,12 @@ Each notice options needs to contain a `path` or `match` option, which is used t
 A notice configuration item includes:
 
 - `title`: Notice title, support both text and HTMLString
-- `content`: Notice content, support both text and HTMLString
+- `content`: Notice content, support both text, HTMLString and Markdown
+
+  - When using `Markdown` as content, the `contentType` should be set to `markdown`.
+
+  - You can also use `contentFile` to specify the absolute path of a file, with the file format being `.md` or `.html`, to read the notice content from the file.
+
 - `actions`: Notice actions
 
   Should be an array of objects containing:
@@ -51,6 +56,7 @@ Here is an example:
 
 ```ts
 import { noticePlugin } from '@vuepress/plugin-notice'
+import { path } from 'vuepress/utils'
 
 export default {
   plugins: [
@@ -72,7 +78,21 @@ export default {
         {
           path: '/zh/',
           title: 'Notice Title',
-          content: 'Notice Content',
+          contentType: 'markdown',
+          content: '**Notice Content** [link](https://example.com)',
+          actions: [
+            {
+              text: 'Primary Action',
+              link: 'https://theme-hope.vuejs.press/',
+              type: 'primary',
+            },
+            { text: 'Default Action' },
+          ],
+        },
+        {
+          path: '/example/',
+          title: 'Notice Title',
+          contentFile: path.resolve(__dirname, 'notice.md'),
           actions: [
             {
               text: 'Primary Action',
@@ -132,7 +152,20 @@ However, if you want users to confirm the notice, you can set `confirm: true`, s
     /**
      * Notice content
      */
-    content: string
+    content?: string
+
+    /**
+     * Notice content type
+     * @default 'html'
+     */
+    contentType?: 'html' | 'markdown'
+
+    /**
+     * Notice content file absolute path, file format should be `.md` or `.html`.
+     * Prioritize using the file content as `content`.
+     * @example '/path/to/notice.md'
+     */
+    contentFile?: string
 
     /**
      * Notice key

docs/zh/plugins/features/notice.md

@@ -33,7 +33,11 @@ export default {
 一个公告配置包括:
 
 - `title`: 通知标题，支持文本和 HTMLString
-- `content`: 通知内容，支持文本和 HTMLString
+- `content`: 通知内容，支持文本、HTMLString 和 Markdown
+
+  - 使用 `Markdown` 作为内容时，应设置 `contentType` 为 `markdown`
+  - 还可以使用 `contentFile` 指定文件绝对路径，文件格式为 `.md` 或 `.html`，从文件中读取通知内容。
+
 - `actions`: 通知操作
 
   应该是包含以下内容的对象数组:
@@ -51,6 +55,7 @@ export default {
 
 ```ts
 import { noticePlugin } from '@vuepress/plugin-notice'
+import { path } from 'vuepress/utils'
 
 export default {
   plugins: [
@@ -72,7 +77,21 @@ export default {
         {
           path: '/zh/',
           title: 'Notice Title',
-          content: 'Notice Content',
+          contentType: 'markdown',
+          content: '**Notice Content** [link](https://example.com)',
+          actions: [
+            {
+              text: 'Primary Action',
+              link: 'https://theme-hope.vuejs.press/',
+              type: 'primary',
+            },
+            { text: 'Default Action' },
+          ],
+        },
+        {
+          path: '/example/',
+          title: 'Notice Title',
+          contentFile: path.resolve(__dirname, 'notice.md'),
           actions: [
             {
               text: 'Primary Action',
@@ -134,6 +153,19 @@ export default {
      */
     content: string
 
+    /**
+     * 通知内容类型
+     * @default 'html'
+     */
+    contentType?: 'html' | 'markdown'
+
+    /**
+     * 通知内容文件绝对路径, 文件格式支持 `.md` 或 `.html`
+     * 优先使用文件内容作为 `content`
+     * @example '/path/to/notice.md'
+     */
+    contentFile?: string
+
     /**
      * Notice 的 key
      *

e2e/docs/.vuepress/config.ts

@@ -256,6 +256,19 @@ export default defineUserConfig({
           ],
           fullscreen: true,
         },
+        {
+          match: /^\/notice\/file\.html$/,
+          title: 'Notice Title',
+          contentFile: path.resolve(__dirname, './notice.md'),
+          actions: [
+            {
+              text: 'Primary Action',
+              link: 'https://example.com/',
+              type: 'primary',
+            },
+            { text: 'Default Action' },
+          ],
+        },
       ],
     }),
     photoSwipePlugin(),

e2e/docs/.vuepress/notice.md

@@ -0,0 +1 @@
+**Notice Content** [link](https://example.com)

e2e/docs/notice/file.md

@@ -0,0 +1 @@
+# Load Notice Content From File

e2e/tests/plugin-notice/notice.spec.ts

@@ -34,4 +34,19 @@ test.describe('notice', () => {
 
     await expect(page.locator('.vp-notice-wrapper')).toHaveCount(0)
   })
+
+  test('load notice content from markdown file', async ({ page }) => {
+    await page.goto('notice/file.html')
+
+    await expect(page.locator('.vp-notice-wrapper')).toHaveCount(1)
+
+    await expect(page.locator('.vp-notice-content strong')).toHaveText(
+      'Notice Content',
+    )
+
+    await expect(page.locator('.vp-notice-content a')).toHaveAttribute(
+      'href',
+      'https://example.com',
+    )
+  })
 })

plugins/features/plugin-notice/package.json

@@ -40,6 +40,7 @@
   "dependencies": {
     "@vuepress/helper": "workspace:*",
     "@vueuse/core": "^12.7.0",
+    "chokidar": "^3.6.0",
     "vue": "^3.5.13"
   },
   "peerDependencies": {

plugins/features/plugin-notice/src/client/components/Notice.ts

@@ -1,6 +1,5 @@
 import { isLinkAbsolute, isLinkHttp, startsWith } from '@vuepress/helper/client'
 import { watchImmediate } from '@vueuse/core'
-import type { PropType } from 'vue'
 import {
   TransitionGroup,
   computed,
@@ -10,38 +9,23 @@ import {
   ref,
 } from 'vue'
 import { useRoutePath, useRouter } from 'vuepress/client'
-import type { NoticeItemOptions } from '../../shared/index.js'
+import { useNoticeOptions } from '../composables/index.js'
 import { CloseIcon } from './CloseIcon.js'
 
 import '../styles/notice.css'
 
-type NoticeClientOption = Omit<NoticeItemOptions, 'key'> & {
-  noticeKey?: string
-} & ({ match: string } | { path: string })
-
 export const Notice = defineComponent({
   name: 'Notice',
 
-  props: {
-    /**
-     * Notice locales settings
-     *
-     * 通知的多语言设置
-     */
-    config: {
-      type: Array as PropType<NoticeClientOption[]>,
-      required: true,
-    },
-  },
-
-  setup(props) {
+  setup() {
     const router = useRouter()
     const routePath = useRoutePath()
+    const noticeOptions = useNoticeOptions()
 
     const isVisible = ref(false)
 
     const matchedConfig = computed(() => {
-      const option = props.config.find((item) =>
+      const option = noticeOptions.value.find((item) =>
         'match' in item
           ? new RegExp(item.match).test(routePath.value)
           : startsWith(routePath.value, item.path),

plugins/features/plugin-notice/src/client/composables/index.ts

@@ -0,0 +1 @@
+export * from './useNoticeOptions.js'

plugins/features/plugin-notice/src/client/composables/useNoticeOptions.ts

@@ -0,0 +1,20 @@
+import { NOTICE_OPTIONS } from '@internal/noticeOptions'
+import type { Ref } from 'vue'
+import { ref } from 'vue'
+import type { NoticeAttrOptions } from '../../shared/index.js'
+
+declare const __VUE_HMR_RUNTIME__: Record<string, unknown>
+
+export type NoticeOptionsRef = Ref<NoticeAttrOptions[]>
+
+export const noticeOptions: NoticeOptionsRef = ref(
+  NOTICE_OPTIONS,
+) as NoticeOptionsRef
+
+export const useNoticeOptions = (): NoticeOptionsRef => noticeOptions
+
+if (__VUEPRESS_DEV__ && (import.meta.webpackHot || import.meta.hot)) {
+  __VUE_HMR_RUNTIME__.updateNoticeOptions = (data: NoticeAttrOptions[]) => {
+    noticeOptions.value = data
+  }
+}

plugins/features/plugin-notice/src/client/config.ts

@@ -1,12 +1,9 @@
 import { h } from 'vue'
 import { defineClientConfig } from 'vuepress/client'
-import type { NoticeAttrOptions } from '../shared/index.js'
 import { Notice } from './components/index.js'
 
 import './styles/vars.css'
 
-declare const __NOTICE_OPTIONS__: NoticeAttrOptions[]
-
 export default defineClientConfig({
-  rootComponents: [() => h(Notice, { config: __NOTICE_OPTIONS__ })],
+  rootComponents: [() => h(Notice)],
 })

plugins/features/plugin-notice/src/client/index.ts

@@ -1 +1,2 @@
 export * from './components/index.js'
+export * from './composables/index.js'

plugins/features/plugin-notice/src/client/noticeOptions.d.ts

@@ -0,0 +1,5 @@
+declare module '@internal/noticeOptions' {
+  import type { NoticeAttrOptions } from '../shared/index.js'
+
+  export const NOTICE_OPTIONS: NoticeAttrOptions[]
+}

plugins/features/plugin-notice/src/node/getNoticeOptions.ts

@@ -4,7 +4,7 @@ export const getNoticeOptions = (
   options: NoticeOptions[] = [],
 ): NoticeAttrOptions[] =>
   options
-    .map(({ key, ...item }) =>
+    .map(({ key, contentType, contentFile, ...item }) =>
       'match' in item
         ? {
             ...item,

plugins/features/plugin-notice/src/node/noticePlugin.ts

@@ -1,8 +1,11 @@
 import type { Plugin } from 'vuepress/core'
-import { getDirname, logger, path } from 'vuepress/utils'
-import { getNoticeOptions } from './getNoticeOptions.js'
-import { PLUGIN_NAME } from './logger.js'
+import { getDirname, path } from 'vuepress/utils'
+import { PLUGIN_NAME, logger } from './logger.js'
 import type { NoticePluginOptions } from './options.js'
+import {
+  prepareNoticeOptions,
+  watchNoticeOptions,
+} from './prepareNoticeOptions.js'
 
 const __dirname = import.meta.dirname || getDirname(import.meta.url)
 
@@ -14,8 +17,12 @@ export const noticePlugin =
     return {
       name: PLUGIN_NAME,
 
-      define: {
-        __NOTICE_OPTIONS__: getNoticeOptions(options.config),
+      onPrepared: async () => {
+        await prepareNoticeOptions(app, options.config)
+      },
+
+      onWatched: (_, watchers) => {
+        watchers.push(watchNoticeOptions(app, options.config))
       },
 
       clientConfigFile: path.resolve(__dirname, '../client/config.js'),