feat(core): attach markdownEnv to page object (#1228)

Co-authored-by: meteorlxy <meteor.lxy@foxmail.com>

Author: Mister-Hope

docs/reference/node-api.md

@@ -536,7 +536,22 @@ interface MarkdownLink {
 
 - Details:
 
-  Links of the page.
+  Links included in the page content.
+
+### markdownEnv
+
+- Type: `Record<string, unknown>`
+
+- Details:
+
+  The `env` object when parsing markdown content with markdown-it.
+
+  Some markdown-it plugins may store extra information inside this object, and you can make use of them for advanced customization.
+
+  Notice that some other page properties are also extracted from the original `env` object. Those properties have already been removed from `page.markdownEnv`.
+
+- Also see:
+  - [markdown-it > API Documentation > MarkdownIt > parse](https://markdown-it.github.io/markdown-it/#MarkdownIt.parse)
 
 ### pathInferred
 

docs/zh/reference/node-api.md

@@ -531,7 +531,23 @@ interface MarkdownLink {
 
 - 详情：
 
-  该 Page 中的链接。
+  该 Page 内容中包含的链接。
+
+
+### markdownEnv
+
+- 类型： `Record<string, unknown>`
+
+- 详情：
+
+  在使用 markdown-it 解析 Markdown 内容时的 `env` 对象。
+
+  一些 markdown-it 插件可能会在这个对象中存储一些额外的信息，你可以使用它们来进行高级定制化。
+
+  需要注意的是，其他的一些 Page 属性其实也是从 `env` 对象中获取到的，但是我们已经把这些属性从 `page.markdownEnv` 中移除掉了。
+
+- 参考：
+  - [markdown-it > API Documentation > MarkdownIt > parse](https://markdown-it.github.io/markdown-it/#MarkdownIt.parse)
 
 ### pathInferred
 

packages/core/src/page/createPage.ts

@@ -37,6 +37,7 @@ export const createPage = async (
     frontmatter,
     headers,
     links,
+    markdownEnv,
     sfcBlocks,
     title,
   } = renderPageContent({
@@ -123,6 +124,7 @@ export const createPage = async (
     date,
     deps,
     links,
+    markdownEnv,
     pathInferred,
     pathLocale,
     permalink,

packages/core/src/page/renderPageContent.ts

@@ -4,6 +4,7 @@ import type {
   MarkdownLink,
   MarkdownSfcBlocks,
 } from '@vuepress/markdown'
+import { omit } from '@vuepress/shared'
 import type { App, PageFrontmatter, PageOptions } from '../types/index.js'
 
 /**
@@ -24,6 +25,7 @@ export const renderPageContent = ({
 }): {
   contentRendered: string
   deps: string[]
+  markdownEnv: Record<string, unknown>
   frontmatter: PageFrontmatter
   headers: MarkdownHeader[]
   links: MarkdownLink[]
@@ -54,6 +56,7 @@ export const renderPageContent = ({
       customBlocks: [],
     },
     title = '',
+    ...extraMarkdownEnv
   } = markdownEnv
 
   return {
@@ -62,6 +65,14 @@ export const renderPageContent = ({
     frontmatter,
     headers,
     links,
+    markdownEnv: omit(
+      extraMarkdownEnv,
+      'base',
+      'content',
+      'filePath',
+      'filePathRelative',
+      'frontmatter'
+    ),
     sfcBlocks,
     title: frontmatter.title ?? title,
   }

packages/core/src/types/page.ts

@@ -42,6 +42,11 @@ export type Page<
      */
     links: MarkdownLink[]
 
+    /**
+     * Markdown env object of the page
+     */
+    markdownEnv: Record<string, unknown>
+
     /**
      * Path of the page that inferred from file path
      *

packages/core/tests/page/renderPageContent.spec.ts

@@ -31,6 +31,7 @@ const msg = 'msg'
       frontmatter: {},
       headers: [],
       links: [],
+      markdownEnv: { excerpt: '' },
       sfcBlocks: {
         template: {
           type: 'template',

packages/shared/src/utils/index.ts

@@ -11,6 +11,7 @@ export * from './isLinkHttp.js'
 export * from './isLinkMailto.js'
 export * from './isLinkTel.js'
 export * from './isPlainObject.js'
+export * from './omit.js'
 export * from './removeEndingSlash.js'
 export * from './removeLeadingSlash.js'
 export * from './resolveHeadIdentifier.js'

packages/shared/src/utils/omit.ts

@@ -0,0 +1,13 @@
+/**
+ * Omit properties from an object
+ */
+export const omit = <T extends Record<string, unknown>, U extends string[]>(
+  obj: T,
+  ...keys: U
+): Omit<T, U[number]> => {
+  const result = { ...obj }
+  for (const key of keys) {
+    delete result[key]
+  }
+  return result
+}