feat: support remark-attributes extension (#104)

Author: JounQin

.changeset/grumpy-apricots-relax.md

@@ -0,0 +1,5 @@
+---
+"@alauda/doom": minor
+---
+
+feat: support remark-attributes extension

docs/en/usage/markdown.md

@@ -1,21 +1,21 @@
 ---
 weight: 3
-sourceSHA: 11b29e882a00a517992fb910421ae98617ad987f086fe05f7794e443e5129a82
+sourceSHA: cefdfa4ab48a0034a890ff42657bbf4837b19667ee1b8182b8af5e337dbd0f33
 ---
 
 # Markdown
 
-In addition to the standard [gfm](https://github.github.com/gfm) syntax, Doom has some built-in extended Markdown features.
+In addition to the standard [gfm](https://github.github.com/gfm) syntax, Doom has built-in some extra Markdown extension features.
 
 ## Callouts
 
 Source code annotation component
 
 ::: note
 
-1. Please use inline code comments according to the actual language, such as `;`, `%`, `#`, `//`, `/** */`, `--`, and `<!-- -->`.
-2. If you need to treat it as a code comment, use `[\!code callout]` for escaping.
-3. Sometimes, `:::callouts` may display incorrectly due to nested indentation; you can use `<div class="doom-callouts">` or `<Callouts>` component instead.
+1. Please use inline code comments according to the actual language, such as `;`, `%`, `#`, `//`, `/** */`, `--`, and `<!-- -->`, etc.
+2. If you want to treat them as code comments, please escape with `[\!code callout]`
+3. Sometimes, `:::callouts` may display abnormally due to nested indentation; you can use `<div class="doom-callouts">` or the `<Callouts>` component instead
 
 :::
 
@@ -61,7 +61,7 @@ Memory overhead per virtual machine ≈ (1.002 × requested memory) \
 
 :::
 
-For more source code conversion features, please refer to [Shiki Transformers](https://shiki.style/packages/transformers#transformers).
+For more source code transformation features, please refer to [Shiki Transformers](https://shiki.style/packages/transformers#transformers).
 
 ## [Mermaid](https://mermaid.js.org)
 
@@ -85,4 +85,16 @@ graph TD;
     C-->D;
 ```
 
-Combined with [Markdown Preview Mermaid](https://github.com/mjbvz/vscode-markdown-mermaid), you can preview in real-time within VSCode.
+With [Markdown Preview Mermaid](https://github.com/mjbvz/vscode-markdown-mermaid), you can preview in real time in VSCode.
+
+## Attribute Extensions {#attributes}
+
+:::warning
+Currently only supported in `.md` files, see [related issue](https://github.com/web-infra-dev/rspress/issues/2215#issuecomment-3018371927)
+:::
+
+```md
+![](/logo.svg){width="100" height="100"}
+```
+
+![](/logo.svg){width="100" height="100"}

docs/zh/usage/markdown.md

@@ -85,3 +85,15 @@ graph TD;
 ```
 
 配合 [Markdown Preview Mermaid](https://github.com/mjbvz/vscode-markdown-mermaid) 可以在 VSCode 中实时预览。
+
+## 属性扩展 \{#attributes}
+
+:::warning
+当前仅支持在 `.md` 文件中使用，参考[相关 issue](https://github.com/web-infra-dev/rspress/issues/2215#issuecomment-3018371927)
+:::
+
+```md
+![](/logo.svg){width="100" height="100"}
+```
+
+![](/logo.svg){width="100" height="100"}

package.json

@@ -83,6 +83,7 @@
     "eslint-plugin-mdx": "^3.5.0",
     "globals": "^16.2.0",
     "html-tag-names": "^2.1.0",
+    "md-attr-parser": "^1.3.0",
     "mdast-util-mdx": "^3.0.0",
     "mdast-util-mdx-jsx": "^3.2.0",
     "mermaid": "^11.6.0",
@@ -108,6 +109,7 @@
     "type-fest": "^4.41.0",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.34.1",
+    "unified": "^11.0.5",
     "x-fetch": "^0.2.6",
     "yaml": "^2.8.0",
     "yoctocolors": "^2.1.1"
@@ -120,6 +122,7 @@
     "@swc/core": "1.12.2",
     "@types/cli-progress": "^3.11.6",
     "@types/ejs": "^3.1.5",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.15.32",
     "@types/picomatch": "^4.0.0",
     "@types/react": "^19.1.8",

shim.d.ts

@@ -21,3 +21,11 @@ declare module 'doom-@permission-functionResourcesMap' {
 declare module 'doom-@permission-roleTemplatesMap' {
   export default roleTemplatesMap
 }
+
+declare module 'md-attr-parser' {
+  const parseAttrs: (value?: string | null) => {
+    prop: Record<string, string>
+    eaten: string
+  }
+  export = parseAttrs
+}

src/cli/load-config.ts

@@ -31,6 +31,7 @@ import { difference } from 'es-toolkit'
 import { globSync } from 'tinyglobby'
 import { cyan } from 'yoctocolors'
 
+import { attributesPlugin } from '../plugins/attributes/index.js'
 import {
   apiPlugin,
   autoSidebarPlugin,
@@ -293,6 +294,7 @@ const getCommonConfig = async ({
       apiPlugin({
         localBasePath,
       }),
+      attributesPlugin(),
       autoSidebarPlugin({ export: export_, ignore }),
       autoTocPlugin(),
       directivesPlugin(),

src/plugins/attributes/index.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from '@rspress/core'
+
+import { remarkAttributes } from './remark-attributes/index.js'
+
+export const attributesPlugin = (): Plugin => {
+  return {
+    name: 'doom-attributes',
+    markdown: {
+      remarkPlugins: [remarkAttributes],
+    },
+  }
+}

src/plugins/attributes/remark-attributes/attributes-transformer.ts

@@ -0,0 +1,93 @@
+import parseAttrs from 'md-attr-parser'
+import type { Node, Parent, Root } from 'mdast'
+import { visit } from 'unist-util-visit'
+
+export interface Attrs extends Node {
+  type: 'attrs'
+  value?: string | null
+}
+
+declare module 'mdast' {
+  interface PhrasingContentMap {
+    attrs: Attrs
+  }
+
+  interface RootContentMap {
+    attrs: Attrs
+  }
+}
+
+export function attributesTransformer(root: Root): void {
+  visit(root, 'paragraph', (node, _, parent) => {
+    if (
+      'children' in node &&
+      node.children.length === 1 &&
+      node.children[0].type === 'attrs'
+    ) {
+      const children = parent!.children
+      const index = children.indexOf(node)
+      children[index] = node.children[0]
+    }
+  })
+
+  visit(
+    root,
+    (node, _, parent) =>
+      node.type === 'paragraph' && parent?.type === 'listItem',
+    (node, _, parent) => {
+      const { children } = node as Parent
+
+      const ids = Object.entries(children)
+        .filter(([, child]) => child.type === 'attrs')
+        .map(([id, node]) => [Number.parseInt(id, 10), node] as [number, Attrs])
+
+      if (ids.length === 0) {
+        return
+      }
+
+      for (const [index, attrNode] of ids) {
+        const sibling = children[index - 1]
+        if (sibling.type === 'text') {
+          const data = parent!.data
+          parent!.data = {
+            ...data,
+            hProperties: {
+              ...data?.hProperties,
+              ...parseAttrs(attrNode.value).prop,
+            },
+          }
+          children.splice(index, 1)
+        }
+      }
+    },
+  )
+
+  visit(root, 'attrs', (node, index, parent) => {
+    if (index == null || parent == null || parent.children.length <= 1) {
+      return
+    }
+
+    const { children } = parent
+
+    const sibling = children.at(index - 1)
+    if (!sibling || sibling.type === 'text') {
+      parent.data = {
+        ...parent.data,
+        hProperties: {
+          ...parent.data?.hProperties,
+          ...parseAttrs(node.value).prop,
+        },
+      }
+    } else {
+      sibling.data = {
+        ...sibling.data,
+        hProperties: {
+          ...sibling.data?.hProperties,
+          ...parseAttrs(node.value).prop,
+        },
+      }
+    }
+
+    children.splice(index, 1)
+  })
+}

src/plugins/attributes/remark-attributes/index.ts

@@ -0,0 +1,30 @@
+import type { Root } from 'mdast'
+import type { Extension as FromMarkdownExtension } from 'mdast-util-from-markdown'
+import type { Plugin } from 'unified'
+
+import { attributesTransformer } from './attributes-transformer.js'
+import { mdastAttributes } from './mdast-attributes.js'
+import { micromarkAttributes } from './micromark-attributes.js'
+import type { AttributesExtension } from './types.js'
+
+export interface AttributesData {
+  micromarkExtensions?: AttributesExtension[]
+  fromMarkdownExtensions?: FromMarkdownExtension[]
+}
+
+export const remarkAttributes: Plugin<[], Root> = function () {
+  const data = this.data() as AttributesData
+
+  function add<K extends keyof AttributesData>(
+    key: K,
+    value: NonNullable<AttributesData[K]>[number],
+  ) {
+    data[key] ||= []
+    data[key].unshift(value)
+  }
+
+  add('micromarkExtensions', micromarkAttributes())
+  add('fromMarkdownExtensions', mdastAttributes())
+
+  return attributesTransformer
+}

src/plugins/attributes/remark-attributes/mdast-attributes.ts

@@ -0,0 +1,25 @@
+import type { Extension as FromMarkdownExtension } from 'mdast-util-from-markdown'
+
+import type { Attrs } from './attributes-transformer.js'
+
+/**
+ * Fully-configured extension to add Heading ID nodes to Markdown.
+ **/
+export function mdastAttributes(): FromMarkdownExtension {
+  return {
+    enter: {
+      attrs(token) {
+        this.enter({ type: 'attrs', value: null }, token)
+        this.buffer()
+      },
+    },
+    exit: {
+      attrs(token) {
+        const attrs = this.resume()
+        const node = this.stack[this.stack.length - 1] as Attrs
+        this.exit(token)
+        node.value = attrs
+      },
+    },
+  }
+}