feat: add plugin-markdown-ext (#278)

.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",

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,

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',

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',

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:*",

docs/plugins/markdown/markdown-ext.md

@@ -0,0 +1,238 @@
+# markdown-ext
+
+<NpmBadge package="@vuepress/plugin-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 <Badge text="Recommended" type="tip" />:
+
+  ````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 `<label>` to wrap text
+     *
+     * @default true
+     */
+    label?: boolean
+  }
+  ```
+
+- Default: `false`
+- Enabled in GFM: Yes
+- Details:
+
+  Whether to enable tasklist format support. You can pass an object to config tasklist.
+
+### breaks
+
+- Type: `boolean`
+- Default: `false`
+- Enabled in GFM: Yes
+- Details: Whether convert `\n` in paragraphs into `<br>`s
+
+### linkify
+
+- Type: `boolean`
+- Default: `false`
+- Enabled in GFM: Yes
+- Details: Whether convert URL-like text into links
+
+### component
+
+- Type: `boolean`
+- Default: `false`
+- Details: Whether to enable component fence support
+
+### vPre
+
+- Type: `boolean`
+- Default: `false`
+- Details: Whether to enable v-pre wrapper.