@active-mdx/core 中文文档教程

Question

Active MDX

MDX 的内容建模

在线文档

MDX 是一个很棒的Markdown 的增强功能。 在常规 Markdown 呈现为静态 html 的地方，MDX 为您提供了一个动态的、基于 React 的输出，您可以自定义并使其具有交互性，无论是通过嵌入 React 组件，还是自定义用于呈现 Markdown 输出的组件。

ActiveMDX 在 Node.js 中运行，并在文件夹及其子文件夹中的 MDX 文件的 集合 之上提供结构化内容建模 API。 这使您可以像处理数据库一样处理文档集合，将单个文档视为记录，并且内容结构（和 YAML frontmatter）决定其属性。 当您将 MDX 和 React 的自定义表示与从内容本身派生的数据相结合时，它会开启强大的可能性。

Active MDX 是一个内容建模库，可让您为项目中不同类型的 MDX 文档开发模型。 模型 假定文档遵循已知的标题和子标题结构。 例如，Recipe 将有一个 ## Ingredients 部分和一个 ## Steps 部分。 活动 MDX 模型允许您通过提供帮助程序来处理 AST 形式中的文档，从而将任何 MDX 文档转换为 JSON 对象。 进入 JSON 对象的内容将完全取决于您在此可预测结构中编写的内容。 Active MDX 模型由 Document 类提供支持，该类为您提供许多实用程序，用于将正在编写的内容转换为结构化数据。

Active MDX 根据所写内容提供的数据可用于支持各种应用程序。 如果你正在建立一个网站，这是一本有十几种食谱的食谱，Active MDX 可以为你提供所有成分和数量的数据库，你可以呈现一个按钮来下订单，让用户根据什么成分找到食谱他们有。

Requirements

• Node.js 14.15.0 or later.

Installation

$ npm install active-mdx

Usage

ActiveMDX 在服务器上运行，在 Node.js 中。 使用本机支持 esm 模块的更高版本的节点。

首先，您有一个包含 mdx 文件的文件夹。

├── epics
│   ├── authentication.mdx
│   └── search.mdx
├── index.js
├── index.mdx
├── models
│   ├── Epic.js
│   └── Story.js
└── stories
    ├── authentication
    │   └── a-user-should-be-able-to-register.mdx
    └── search
        └── searching-for-a-product-by-category.mdx

此文件夹由 Active MDX Collection 的实例表示，

// index.js
import { Collection } from "@active-mdx/core"

// load({ models: true }) will automatically register ./models/*.js as model classes
export default new Collection({ rootPath: "./content" })

您可以在任何地方使用它

import collection from './index.js'

collection.load({ models: true }).then(async (collection) => {
  const Epic = collection.model('Epic')
  const epics = Epic.query(qb => qb.where("status", "completed")).fetchAll()
})

epics 文件夹由我们在 中定义的 模型 表示。 /models/Epic.js。 模型定义了该文档如何与项目中的其他文档相关，以及如何将文档内容中的信息表示为数据。

// ./models/Epic.js
import { Model } from "@active-mdx/core"
import Story from "./Story.js"

export default class Epic extends Model {
  stories() {
    return this.hasMany(Story, {
      heading: "stories",
      meta: () => ({ epic: this.title.toLowerCase() })
    })
  }

  get isComplete() {
    return this.stories().fetchAll().every((story) => story.meta.status === 'completed')
  }

  static is(document) {
    return document.id.startsWith("epic")
  }
}

这将采用 mdx 内容，例如 epics/authentication.mdx

---
status: proposed
---

# Authentication

The Authentication stories cover users logging in and out of the application, as well as the roles and permissions granted to these users and how they are enforced in the application.

## Stories

### A User should be able to register

As a User I would like to register so that I can use the application.

### A User should be able to login

As a User I would like to login so that I can use the application.

除了以 MDX 形式显示 Epic，我们还可以使用它作为数据和参考写作本身所包含的事物。

const authEpic = collection.getModel("epics/authentication")
console.log(authEpic.toJSON({ related: ["stories"], attributes: ["isComplete"] }))
/*
{
  "id": "epics/authentication",
  "meta": {
    "status": "proposed"
  },
  "title": "Authentication",
  "stories": [
    {
      "id": "stories/authentication/a-user-should-be-able-to-register",
      "meta": {
        "epic": "authentication"
      },
      "title": "A User Should be able to Register"
    },
    {
      "id": "stories/authentication/a-user-should-be-able-to-login",
      "meta": {
        "epic": "authentication"
      },
      "title": "A User should be able to login"
    }, ...
  ],
  "isComplete": false
}
*/

每个模型都可以访问底层的 Document 类，该类为 提供方法查询 AST 和 AST 节点的快捷方式，可用于从书写内容中提取数据。

Document 类 API 还提供了以编程方式操作文档内容的方法，例如

• replaceSectionContent("Section Title", "- new\n - markdown\n - list\n")
• appendToSection("Section Title", "[Link](www.google.com)")

获取 API 中可用内容的完整列表 查看 API 文档

CLI

该包附带一个 bin amdx，可用于初始化新项目，并使用文档和模型。

$ amdx --help

Guides and Documentation

• Introduction
• Example Project
• Usage with NextJS
• Models

Example Projects

• Example Next.js Blog