From 9734a373f5eb159164369577e78668d0e928f403 Mon Sep 17 00:00:00 2001 From: Mister-Hope Date: Thu, 24 Oct 2024 20:44:05 +0800 Subject: [PATCH 01/35] feat: add plugin-markdown-ext (#278) --- .vscode/settings.json | 4 +- docs/.vuepress/config.ts | 11 +- docs/.vuepress/configs/sidebar/en.ts | 1 + docs/.vuepress/configs/sidebar/zh.ts | 1 + docs/package.json | 2 +- docs/plugins/markdown/markdown-ext.md | 238 ++++++++++++++++++ docs/zh/plugins/markdown/markdown-ext.md | 238 ++++++++++++++++++ .../markdown/plugin-markdown-ext/package.json | 60 +++++ .../plugin-markdown-ext/rollup.config.ts | 10 + .../plugin-markdown-ext/src/node/index.ts | 3 + .../src/node/markdown-it-plugins/component.ts | 67 +++++ .../src/node/markdown-it-plugins/index.ts | 2 + .../src/node/markdown-it-plugins/utils.ts | 3 + .../src/node/markdown-it-plugins/vPre.ts | 10 + .../src/node/markdownExtPlugin.ts | 38 +++ .../plugin-markdown-ext/src/node/options.ts | 77 ++++++ .../plugin-markdown-ext/src/node/utils.ts | 5 + .../node/__snapshots__/component.spec.ts.snap | 11 + .../tests/node/component.spec.ts | 95 +++++++ .../tests/node/vPre.spec.ts | 14 ++ .../plugin-markdown-ext/tsconfig.build.json | 8 + pnpm-lock.yaml | 75 +++++- tsconfig.build.json | 3 + 23 files changed, 966 insertions(+), 10 deletions(-) create mode 100644 docs/plugins/markdown/markdown-ext.md create mode 100644 docs/zh/plugins/markdown/markdown-ext.md create mode 100644 plugins/markdown/plugin-markdown-ext/package.json create mode 100644 plugins/markdown/plugin-markdown-ext/rollup.config.ts create mode 100644 plugins/markdown/plugin-markdown-ext/src/node/index.ts create mode 100644 plugins/markdown/plugin-markdown-ext/src/node/markdown-it-plugins/component.ts create mode 100644 plugins/markdown/plugin-markdown-ext/src/node/markdown-it-plugins/index.ts create mode 100644 plugins/markdown/plugin-markdown-ext/src/node/markdown-it-plugins/utils.ts create mode 100644 plugins/markdown/plugin-markdown-ext/src/node/markdown-it-plugins/vPre.ts create mode 100644 plugins/markdown/plugin-markdown-ext/src/node/markdownExtPlugin.ts create mode 100644 plugins/markdown/plugin-markdown-ext/src/node/options.ts create mode 100644 plugins/markdown/plugin-markdown-ext/src/node/utils.ts create mode 100644 plugins/markdown/plugin-markdown-ext/tests/node/__snapshots__/component.spec.ts.snap create mode 100644 plugins/markdown/plugin-markdown-ext/tests/node/component.spec.ts create mode 100644 plugins/markdown/plugin-markdown-ext/tests/node/vPre.spec.ts create mode 100644 plugins/markdown/plugin-markdown-ext/tsconfig.build.json diff --git a/.vscode/settings.json b/.vscode/settings.json index b2b10e18e6..0914fe961c 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -33,9 +33,10 @@ "globby", "gtag", "jsonld", + "katex", "lazyload", "lightmode", - "katex", + "linkify", "mathjax", "mdit", "nord", @@ -48,6 +49,7 @@ "shiki", "shikijs", "slugify", + "tasklist", "tsbuildinfo", "twikoo", "umami", diff --git a/docs/.vuepress/config.ts b/docs/.vuepress/config.ts index 4c9454a4b1..ec603a0792 100644 --- a/docs/.vuepress/config.ts +++ b/docs/.vuepress/config.ts @@ -1,5 +1,4 @@ import process from 'node:process' -import { footnote } from '@mdit/plugin-footnote' import { viteBundler } from '@vuepress/bundler-vite' import { webpackBundler } from '@vuepress/bundler-webpack' import { getRealPath } from '@vuepress/helper' @@ -8,6 +7,7 @@ import { catalogPlugin } from '@vuepress/plugin-catalog' import { commentPlugin } from '@vuepress/plugin-comment' import { docsearchPlugin } from '@vuepress/plugin-docsearch' import { feedPlugin } from '@vuepress/plugin-feed' +import { markdownExtPlugin } from '@vuepress/plugin-markdown-ext' import { markdownImagePlugin } from '@vuepress/plugin-markdown-image' import { markdownMathPlugin } from '@vuepress/plugin-markdown-math' import { redirectPlugin } from '@vuepress/plugin-redirect' @@ -73,10 +73,6 @@ export default defineUserConfig({ }, }, - extendsMarkdown: (md) => { - md.use(footnote) - }, - // configure default theme theme, @@ -91,6 +87,11 @@ export default defineUserConfig({ json: true, rss: true, }), + markdownExtPlugin({ + gfm: true, + component: true, + vPre: true, + }), markdownImagePlugin({ figure: true, mark: true, diff --git a/docs/.vuepress/configs/sidebar/en.ts b/docs/.vuepress/configs/sidebar/en.ts index f9c25a813d..14cecbd128 100644 --- a/docs/.vuepress/configs/sidebar/en.ts +++ b/docs/.vuepress/configs/sidebar/en.ts @@ -99,6 +99,7 @@ export const sidebarEn: SidebarOptions = { '/plugins/markdown/': [ 'append-date', 'markdown-container', + 'markdown-ext', 'markdown-image', 'markdown-hint', 'markdown-math', diff --git a/docs/.vuepress/configs/sidebar/zh.ts b/docs/.vuepress/configs/sidebar/zh.ts index 88c71831cf..41c807fc1a 100644 --- a/docs/.vuepress/configs/sidebar/zh.ts +++ b/docs/.vuepress/configs/sidebar/zh.ts @@ -99,6 +99,7 @@ export const sidebarZh: SidebarOptions = { '/zh/plugins/markdown/': [ 'append-date', 'markdown-container', + 'markdown-ext', 'markdown-image', 'markdown-hint', 'markdown-math', diff --git a/docs/package.json b/docs/package.json index 3e8ae3002c..5d3e203adf 100644 --- a/docs/package.json +++ b/docs/package.json @@ -9,7 +9,6 @@ "docs:serve": "http-server -a localhost .vuepress/dist" }, "dependencies": { - "@mdit/plugin-footnote": "0.13.1", "@vuepress/bundler-vite": "2.0.0-rc.18", "@vuepress/bundler-webpack": "2.0.0-rc.18", "@vuepress/plugin-back-to-top": "workspace:*", @@ -19,6 +18,7 @@ "@vuepress/plugin-copy-code": "workspace:*", "@vuepress/plugin-docsearch": "workspace:*", "@vuepress/plugin-feed": "workspace:*", + "@vuepress/plugin-markdown-ext": "workspace:*", "@vuepress/plugin-markdown-image": "workspace:*", "@vuepress/plugin-markdown-math": "workspace:*", "@vuepress/plugin-markdown-tab": "workspace:*", diff --git a/docs/plugins/markdown/markdown-ext.md b/docs/plugins/markdown/markdown-ext.md new file mode 100644 index 0000000000..0b1ba788ce --- /dev/null +++ b/docs/plugins/markdown/markdown-ext.md @@ -0,0 +1,238 @@ +# markdown-ext + + + +Add basic GFM support to VuePress with useful features. + +## Usage + +```bash +npm i -D @vuepress/plugin-markdown-ext@next +``` + +```ts +import { markdownExtPlugin } from '@vuepress/plugin-markdown-ext' + +export default { + plugins: [ + markdownExtPlugin({ + // options + }), + ], +} +``` + +## Syntax + +### Footnote + +- Use `[^Anchor text]` in Markdown to define a footnote + +- Use `[^Anchor text]: ...` to describe footnote content + +- If there are multiple paragraphs in footnote, the paragraph show be double indented + +::: details Demo + +Footnote 1 link[^first]. + +Footnote 2 link[^second]. + +Inline footnote^[Text of inline footnote] definition. + +Duplicated footnote reference[^second]. + +[^first]: Footnote **can have markup** + + and multiple paragraphs. + +[^second]: Footnote text. + +```md +Footnote 1 link[^first]. + +Footnote 2 link[^second]. + +Inline footnote^[Text of inline footnote] definition. + +Duplicated footnote reference[^second]. + +[^first]: Footnote **can have markup** + + and multiple paragraphs. + +[^second]: Footnote text. +``` + +::: + +### Task list + +- Use `- [ ] some text` to render an unchecked task item. +- Use `- [x] some text` to render a checked task item. (Capital `X` is also supported) + +::: details Demo + +- [ ] Plan A +- [x] Plan B + +```md +- [ ] Plan A +- [x] Plan B +``` + +::: + +### Component + +You can use component fence block to add a component into your markdown content. Both YAML and JSON format props data are supported: + +- YAML : + + ````md + ```component ComponentName + # component data here + ``` + ```` + +- JSON: + + ````md + ```component ComponentName + { + // component data here + } + ``` + ```` + +::: details Demo + +```component Badge +text: Mr.Hope +type: tip +``` + +```component Badge +{ + "text": "Mr.Hope", + "type": "tip" +} +``` + +````md +```component Badge +text: Mr.Hope +type: tip +``` + +```component Badge +{ + "text": "Mr.Hope", + "type": "tip" +} +``` +```` + +::: + +### v-pre + +You can use any mustache syntax as raw text in `v-pre` container: + +:::: details Demo + +::: v-pre + +{{ abc }} + +::: + +```md +::: v-pre + +{{ abc }} + +::: +``` + +:::: + +## Options + +### gfm + +- Type: `boolean` + +- Details: + + Whether tweaks the behavior and features to be more similar to GitHub Flavored Markdown. + + `markdown-it` already supports tables and strike through by default. If this option is `true`, the following new features will be enabled: + + - Auto link (named `linkify` in `markdown-it`) + - Hard breaks + - Footnote + - Task list + + Note, all behavior is not exactly the same as GitHub Flavored Markdown. + +### footnote + +- Type: `boolean` +- Default: `false` +- Enabled in GFM: Yes +- Details: Whether to enable footnote format support. + +### tasklist + +- Type: `TaskListOptions | boolean` + + ```ts + interface TaskListOptions { + /** + * Whether disable checkbox + * + * @default true + */ + disabled?: boolean + + /** + * Whether use `