refactor(markdown): unify async rendering

Author: YunYouJun

packages/valaxy-theme-press/components/PressFuseSearchModal.vue

@@ -1,6 +1,6 @@
 <script lang="ts" setup>
 import { isClient, useScrollLock } from '@vueuse/core'
-import MarkdownIt from 'markdown-it'
+import { createMarkdownExit } from 'markdown-exit'
 import { useFuseSearch } from 'valaxy'
 import { nextTick, ref, watch } from 'vue'
 import { useI18n } from 'vue-i18n'
@@ -11,7 +11,7 @@ const props = defineProps<{
 
 const emit = defineEmits(['close'])
 
-const md = new MarkdownIt({
+const md = createMarkdownExit({
   html: true,
   linkify: true,
 })

packages/valaxy-theme-press/package.json

@@ -33,6 +33,7 @@
     "@docsearch/css": "catalog:",
     "@docsearch/js": "catalog:",
     "@docsearch/sidepanel-js": "catalog:",
+    "markdown-exit": "catalog:",
     "reka-ui": "catalog:frontend",
     "vitepress": "catalog:frontend"
   },

packages/valaxy/node/modules/rss/utils.ts

@@ -11,7 +11,7 @@ import { Feed } from 'feed'
 
 import fs from 'fs-extra'
 import matter from 'gray-matter'
-import MarkdownIt from 'markdown-it'
+import { createMarkdownExit } from 'markdown-exit'
 
 import { getBorderCharacters, table } from 'table'
 import { tObject } from '../../../shared'
@@ -22,7 +22,7 @@ import { getCreatedTime, getUpdatedTime } from '../../utils/date'
 // Extend Item type to include optional updated field for Atom feed
 type ExtendedItem = Item & { updated?: Date }
 
-const markdown = MarkdownIt({
+const markdown = createMarkdownExit({
   html: true,
   breaks: true,
   linkify: true,

packages/valaxy/node/plugins/markdown/async.ts

@@ -1,13 +1,12 @@
 // ref vitepress src/node/markdown/env.ts
 import type { MarkdownSfcBlocks } from '@mdit-vue/plugin-sfc'
 import type { Header } from '@valaxyjs/utils'
-import type { Env } from 'markdown-it'
 import type { CleanUrlsMode, Page } from '../../../types'
 
 // Manually declaring all properties as rollup-plugin-dts
 // is unable to merge augmented module declarations
 
-export interface MarkdownEnv extends Env {
+export interface MarkdownEnv {
   /**
    * The raw Markdown content without frontmatter
    */

packages/valaxy/node/plugins/markdown/env.ts

@@ -1,16 +1,16 @@
 import type { Header } from '@valaxyjs/utils'
 
 import type { ResolvedValaxyOptions } from '../../types'
-import type { MarkdownItAsync } from './async'
 import type { MarkdownBase } from './base'
+import type { MarkdownRenderer } from './renderer'
 
 import { logger } from '../../logger'
-import { createMarkdownItAsync } from './async'
 import { getSharedHighlighter } from './highlighterCache'
+import { createMarkdownEngine } from './renderer'
 import { defaultCodeTheme, setupMarkdownPageMetadata, setupMarkdownPlugins } from './setup'
 
-export * from './async'
 export * from './env'
+export * from './renderer'
 export * from './setup'
 export * from './transform'
 
@@ -27,7 +27,7 @@ export function disposePreviewMdItInstance() {
   _disposeHighlighter = undefined
 }
 
-export async function createMarkdownRenderer(options?: ResolvedValaxyOptions, base?: MarkdownBase): Promise<MarkdownItAsync> {
+export async function createMarkdownRenderer(options?: ResolvedValaxyOptions, base?: MarkdownBase): Promise<MarkdownRenderer> {
   const mdOptions = options?.config.markdown || {}
   const theme = mdOptions.theme ?? defaultCodeTheme
 
@@ -37,7 +37,7 @@ export async function createMarkdownRenderer(options?: ResolvedValaxyOptions, ba
 
   _disposeHighlighter = dispose
 
-  const md = createMarkdownItAsync({
+  const md = createMarkdownEngine({
     html: true,
     linkify: true,
     ...mdOptions.options,
@@ -47,9 +47,8 @@ export async function createMarkdownRenderer(options?: ResolvedValaxyOptions, ba
   md.linkify.set({ fuzzyLink: false })
 
   await setupMarkdownPlugins(md, options, base)
-  await mdOptions.markdownItSetup?.(
-    md as unknown as Parameters<NonNullable<typeof mdOptions.markdownItSetup>>[0],
-  )
+  const userMarkdownSetup = mdOptions.markdownSetup ?? mdOptions.markdownItSetup
+  await userMarkdownSetup?.(md)
   setupMarkdownPageMetadata(md, options)
   return md
 }
@@ -59,7 +58,7 @@ export async function createMarkdownRenderer(options?: ResolvedValaxyOptions, ba
  * Used by localSearchPlugin where HTML output is stripped anyway,
  * saving ~20-50 MB of Shiki theme/grammar data.
  */
-export async function createLightMarkdownRenderer(options?: ResolvedValaxyOptions, base?: MarkdownBase): Promise<MarkdownItAsync> {
+export async function createLightMarkdownRenderer(options?: ResolvedValaxyOptions, base?: MarkdownBase): Promise<MarkdownRenderer> {
   const mdOptions = options?.config.markdown || {}
 
   // Define highlight separately to avoid circular type inference
@@ -73,7 +72,7 @@ export async function createLightMarkdownRenderer(options?: ResolvedValaxyOption
     return `<pre><code>${escaped}</code></pre>`
   }
 
-  const md = createMarkdownItAsync({
+  const md = createMarkdownEngine({
     html: true,
     linkify: true,
     ...mdOptions.options,
@@ -83,6 +82,8 @@ export async function createLightMarkdownRenderer(options?: ResolvedValaxyOption
   md.linkify.set({ fuzzyLink: false })
 
   await setupMarkdownPlugins(md, options, base)
+  const userMarkdownSetup = mdOptions.markdownSetup ?? mdOptions.markdownItSetup
+  await userMarkdownSetup?.(md)
   setupMarkdownPageMetadata(md, options)
   return md
 }

packages/valaxy/node/plugins/markdown/index.ts

@@ -10,3 +10,13 @@
 export function isPromiseLike(v: unknown): v is PromiseLike<unknown> {
   return typeof v === 'object' && v !== null && typeof (v as any).then === 'function'
 }
+
+/** Apply a synchronous HTML transform without discarding an async render rule. */
+export function mapRenderResult(
+  result: string | Promise<string>,
+  transform: (html: string) => string,
+): string | Promise<string> {
+  return isPromiseLike(result)
+    ? Promise.resolve(result).then(transform)
+    : transform(result)
+}

packages/valaxy/node/plugins/markdown/plugins/async-utils.ts

@@ -1,4 +1,4 @@
-import type { MarkdownIt } from 'markdown-it'
+import type { MarkdownRenderer } from '../renderer'
 import { EXTERNAL_URL_RE } from '../../../../shared'
 
 /**
@@ -8,7 +8,7 @@ import { EXTERNAL_URL_RE } from '../../../../shared'
  *
  * @see https://vitepress.dev/guide/asset-handling
  */
-export function imagePlugin(md: MarkdownIt) {
+export function imagePlugin(md: MarkdownRenderer) {
   const imageRule = md.renderer.rules.image!
 
   md.renderer.rules.image = (tokens, idx, options, env, self) => {

packages/valaxy/node/plugins/markdown/plugins/image.ts

@@ -4,16 +4,16 @@
 // 1. adding target="_blank" to external links
 // 2. normalize internal links to end with `.html`
 
-import type { MarkdownIt } from 'markdown-it'
 import type { MarkdownBaseResolver } from '../base'
 import type { MarkdownEnv } from '../env'
+import type { MarkdownRenderer } from '../renderer'
 import { URL } from 'node:url'
 import { EXTERNAL_URL_RE } from '../../../../shared'
 import { PATHNAME_PROTOCOL_RE } from '../../../constants'
 
 const indexRE = /(^|.*\/)index.md(.*)$/i
 
-export function linkPlugin(md: MarkdownIt, externalAttrs: Record<string, string>, resolveBase: MarkdownBaseResolver) {
+export function linkPlugin(md: MarkdownRenderer, externalAttrs: Record<string, string>, resolveBase: MarkdownBaseResolver) {
   md.renderer.rules.link_open = (
     tokens,
     idx,

packages/valaxy/node/plugins/markdown/plugins/link.ts

@@ -1,26 +1,33 @@
 // ref vitepress
 // src/node/markdown/plugins/containers.ts
 
-import type { Token } from 'markdown-it'
+import type { Token } from 'markdown-exit'
 
-import type { MarkdownItAsync } from '../../async'
+import type { MarkdownRenderer } from '../../renderer'
 import container from 'markdown-it-container'
 import {
   extractTitle,
 } from './preWrapper'
 
+type ContainerPlugin = (
+  md: MarkdownRenderer,
+  name: string,
+  options?: { render: (tokens: Token[], idx: number) => string },
+) => void
+const containerCompat = container as unknown as ContainerPlugin
+
 type ContainerArgs = [
-  typeof container,
+  typeof containerCompat,
   string,
   {
     render: (tokens: Token[], idx: number) => string
   },
 ]
 
-function createContainer(key: string, block: BlockItem = {}, md: MarkdownItAsync): ContainerArgs {
+function createContainer(key: string, block: BlockItem = {}, md: MarkdownRenderer): ContainerArgs {
   const classes = key
   return [
-    container,
+    containerCompat,
     classes,
     {
       render(tokens, idx) {
@@ -87,7 +94,7 @@ const defaultBlocksOptions: Blocks = {
   },
 }
 
-export function containerPlugin(md: MarkdownItAsync, containerOptions: ContainerOptions = {}) {
+export function containerPlugin(md: MarkdownRenderer, containerOptions: ContainerOptions = {}) {
   const blockKeys = new Set(Object.keys({ ...defaultBlocksOptions, ...containerOptions.blocks }))
   blockKeys.forEach((optionKey) => {
     const key = optionKey as keyof Blocks
@@ -97,18 +104,18 @@ export function containerPlugin(md: MarkdownItAsync, containerOptions: Container
   })
 
   // explicitly escape Vue syntax
-  md.use(container, 'v-pre', {
+  md.use(containerCompat, 'v-pre', {
     render: (tokens: Token[], idx: number) =>
       tokens[idx].nesting === 1 ? `<div v-pre>\n` : `</div>\n`,
   })
-  md.use(container, 'raw', {
+  md.use(containerCompat, 'raw', {
     render: (tokens: Token[], idx: number) =>
       tokens[idx].nesting === 1 ? `<div class="vp-raw">\n` : `</div>\n`,
   })
 
   const languages = containerOptions.languages || ['zh-CN', 'en']
   languages.forEach((lang) => {
-    md.use(container, lang, {
+    md.use(containerCompat, lang, {
       render: (tokens: Token[], idx: number) =>
         tokens[idx].nesting === 1 ? `<div lang="${lang}">\n` : '</div>\n',
     })
@@ -117,9 +124,9 @@ export function containerPlugin(md: MarkdownItAsync, containerOptions: Container
   md.use(...createCodeGroup(md))
 }
 
-function createCodeGroup(md: MarkdownItAsync): ContainerArgs {
+function createCodeGroup(md: MarkdownRenderer): ContainerArgs {
   return [
-    container,
+    containerCompat,
     'code-group',
     {
       render(tokens, idx) {