docs(element-transform): added documentations

Signed-off-by: Neko Ayaka <neko@ayaka.moe>

Author: nekomeowww

docs/package.json

@@ -26,7 +26,9 @@
     "@rive-app/canvas": "^2.11.1",
     "@rollup/plugin-yaml": "^4.1.2",
     "@shikijs/vitepress-twoslash": "^1.2.4",
+    "@types/markdown-it": "^13.0.7",
     "@types/markdown-it-footnote": "^3.0.4",
+    "markdown-it": "^13.0.2",
     "markdown-it-footnote": "^4.0.0",
     "thumbhash": "^0.1.1",
     "unlazy": "^0.11.2"

docs/pages/en/integrations/markdown-it-bi-directional-links/index.md

@@ -55,6 +55,10 @@ Install `@nolebase/markdown-it-bi-directional-links` to your project dependencie
 
 ::: code-group
 
+```shell [@antfu/ni]
+ni @nolebase/markdown-it-bi-directional-links -D
+```
+
 ```shell [pnpm]
 pnpm add @nolebase/markdown-it-bi-directional-links -D
 ```
@@ -113,8 +117,8 @@ Then you need to use the `use()` member methods from the `markdown-it` instance
 With a options object that contains a `dir` field which is the root directory of your project supplied, the value for `dir` field can be obtained through `cwd()` function call that imported from either `process` or `node:process`:
 
 ```typescript twoslash
-import type { MarkdownIt } from 'markdown-it'
-let markdownIt = null as MarkdownIt
+import MarkdownIt from 'markdown-it'
+let markdownIt: MarkdownIt = null as unknown as MarkdownIt
 // ---cut---
 import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links' // [!code ++]
 import { cwd } from 'node:process' // [!code ++]

docs/pages/en/integrations/markdown-it-element-transform/assets/vite-plugin-inspect-screenshot-day-theme.png

@@ -1,5 +1,182 @@
 # Elements Transformation <Badge type="tip" text="v1.28.0" />
 
-::: warning 🚧 Constructing
-Nice to meet you! But sorry, this page is still under construction. If you don’t find the information you are interested in, you can first find the content you are interested in in the navigation in the sidebar to start reading.
+This is a low-level plugin that is intended to be used by advanced users who want to transform the `markdown-it` [tokens](https://markdown-it.github.io/markdown-it/#Token) to perform tasks like replacing elements, adding attributes, etc.
+
+::: warning Before you start
+
+This plugin primarily is a helper utility markdown-it plugin for [Inline Links Previewing](/pages/en/integrations/vitepress-plugin-inline-link-preview/) to help to transform all the `<a>` elements to `<NolebaseInlineLinkPreview>` components.
+
+When using this plugin directly, you may encounter errors like `Invalid tag`, or `Element missing end tag` errors when integrating with VitePress or Vue markdown plugins after transforming [tokens](https://markdown-it.github.io/markdown-it/#Token) and elements,
+or other markdown-it plugins that are not compatible with the transformed elements. Please use it when you understand how the [Token API](https://markdown-it.github.io/markdown-it/#Token) of `markdown-it` works.
+
+:::
+
+## Installation
+
+Install `@nolebase/markdown-it-bi-element-transform` to your project dependencies by running the following command:
+
+::: code-group
+
+```shell [@antfu/ni]
+ni @nolebase/markdown-it-bi-element-transform -D
+```
+
+```shell [pnpm]
+pnpm add @nolebase/markdown-it-bi-element-transform -D
+```
+
+```shell [npm]
+npm install @nolebase/markdown-it-bi-element-transform -D
+```
+
+```shell [yarn]
+yarn add @nolebase/markdown-it-bi-element-transform -D
+```
+
 :::
+
+
+## Usage
+
+::: tip Suggestions to developers
+
+When learning, debugging, we suggest including [`vite-plugin-inspect`](https://github.com/antfu/vite-plugin-inspect) in your project. It allows you to inspect the intermediate state of Vite plugins, Markdown transformations. After installing, you can visit [](http://localhost:5173/__inspect/) to inspect the modules and transformation stack of your project.
+
+Check out install instructions in the [`vite-plugin-inspect` docs](https://github.com/antfu/vite-plugin-inspect).
+
+<picture>
+  <source srcset="./assets/vite-plugin-inspect-screenshot-day-theme.png" media="(prefers-color-scheme: light)">
+  <source srcset="./assets/vite-plugin-inspect-screenshot-night-theme.png" media="(prefers-color-scheme: dark)">
+  <img src="./assets//vite-plugin-inspect-screenshot-day-theme.png" alt="Screenshot of vite-plugin-inspect" />
+</picture>
+
+:::
+
+### Use with [Inline Links Previewing](/pages/en/integrations/vitepress-plugin-inline-link-preview/)
+
+Use this plugin with [Inline Links Previewing](/pages/en/integrations/vitepress-plugin-inline-link-preview/) to replace all the `<a>` elements to `<NolebaseInlineLinkPreview>` components to enable the abilities to preview the links.
+
+::: danger Implementation may change in the future for [Inline Links Previewing](/pages/en/integrations/vitepress-plugin-inline-link-preview/)
+
+Such usage is a temporary workaround due to the fact that we haven't had time to refactor [Inline Links Previewing](/pages/en/integrations/vitepress-plugin-inline-link-preview/) plugin to listen the mouse hovering event of all the `<a>` elements as singleton instance across all pages for both better accessibility and compatibilities (since it replaces all the `<a>` elements and may break the markdown processing pipelines for advanced users).
+
+:::
+
+This is the living example code where we use it as references:
+
+```ts twoslash
+import MarkdownIt from 'markdown-it'
+let markdownIt: MarkdownIt = null as unknown as MarkdownIt
+// ---cut---
+import { ElementTransform } from '@nolebase/markdown-it-element-transform'
+
+markdownIt.use(ElementTransform, (() => {
+  // Define variables inside the closure function to share the state between multiple tokens
+  // Here we need a variable to track whether the next token needs to be transformed or not because we need to modify two tokens (link_open, link_close)
+  let transformNextLinkCloseToken = false
+
+  return {
+    transform(token) {
+      switch (token.type) {
+        case 'link_open':
+          // Skip the transformation if the token is a header anchor
+          // because the header anchor doesn't need to be previewed
+          if (token.attrGet('class') !== 'header-anchor') {
+            // Modify the tag of the token
+            token.tag = 'NolebaseInlineLinkPreview'
+            // Set the flag to transform the next link_close token
+            transformNextLinkCloseToken = true
+          }
+          break
+        case 'link_close':
+          // Transform the token if the flag is set
+          if (transformNextLinkCloseToken) {
+            // Modify the tag of the token
+            token.tag = 'NolebaseInlineLinkPreview'
+            // Reset the flag
+            transformNextLinkCloseToken = false
+          }
+
+          break
+      }
+    },
+  }
+})())
+```
+
+### Use it to add more attributes to the elements
+
+There are many use cases where you want to add more attributes to the elements.
+
+For example:
+
+1. Add `target="_blank"` and `rel="noopener noreferrer"` to all the `<a>` elements.
+2. Add inline styles to all the `<span>` elements.
+3. Add more classes to the elements.
+
+#### Add `target="_blank"` and `rel="noopener noreferrer"` to links
+
+```ts twoslash
+import MarkdownIt from 'markdown-it'
+let markdownIt: MarkdownIt = null as unknown as MarkdownIt
+// ---cut---
+import { ElementTransform } from '@nolebase/markdown-it-element-transform'
+
+markdownIt.use(ElementTransform, (() => {
+  return {
+    transform(token) {
+      if (token.type === 'link_open') {
+        token.attrSet('target', '_blank')
+        token.attrSet('rel', 'noopener noreferrer')
+      }
+    },
+  }
+})())
+```
+
+#### Add inline styles to the elements
+
+```ts twoslash
+import MarkdownIt from 'markdown-it'
+let markdownIt: MarkdownIt = null as unknown as MarkdownIt
+// ---cut---
+import { ElementTransform } from '@nolebase/markdown-it-element-transform'
+
+markdownIt.use(ElementTransform, (() => {
+  return {
+    transform(token) {
+      if (token.type === 'span') {
+        token.attrSet('style', 'color: red;')
+      }
+    },
+  }
+})())
+```
+
+#### Add more classes to the elements
+
+```ts twoslash
+import MarkdownIt from 'markdown-it'
+let markdownIt: MarkdownIt = null as unknown as MarkdownIt
+// ---cut---
+import { ElementTransform } from '@nolebase/markdown-it-element-transform'
+
+markdownIt.use(ElementTransform, (() => {
+  return {
+    transform(token) {
+      if (token.type === 'span') {
+        const existingClasses = token.attrGet('class') || ''
+        token.attrSet('class', existingClasses + ' my-custom-class')
+      }
+    },
+  }
+})())
+```
+
+## Alternatives?
+
+### [jeffbski/markdown-it-modify-token](https://github.com/jeffbski/markdown-it-modify-token)
+
+Yes, this plugin does everything literally the same as [jeffbski/markdown-it-modify-token](https://github.com/jeffbski/markdown-it-modify-token). The reason why we have our own implementation is because we didn't know the existence of the plugin until we have implemented it.
+
+Feel free to use the alternative if you want to. 😋