# mdx-doc **Repository Path**: gridsoft/mdx-doc ## Basic Information - **Project Name**: mdx-doc - **Description**: mdx 项目文档 - **Primary Language**: JavaScript - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-07 - **Last Updated**: 2026-07-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # MDX Doc MDX Doc 是一个用于管理项目文档的文档工程。项目文档统一使用 MDX 编写，既可以作为项目内部说明、设计记录和使用手册的统一入口，也可以构建为静态 HTML 页面，发布到项目官网或文档站点。 ## 项目目标 - 使用 MDX 组织项目文档，优先保持 Markdown 的易写性，并在必要时保留扩展能力。 - 为每个项目沉淀稳定的文档结构，将项目需求、使用指南和运维信息统一收敛到少量核心文档中。 - 支持将文档构建为静态 HTML 文件，方便托管到官网、对象存储、GitHub Pages 或其他静态站点服务。 - 日常维护以 VS Code 直接编辑 MDX 源文件为主，不依赖本地文档服务。 - 提供统一的目录规范，降低多个项目之间文档维护和迁移成本。 - 将项目文档同时服务于人类读者和 AI 辅助工具，让文档成为项目协作和自动化开发的基础设施。 - 为后续扩展导航、主题、版本管理和自动化发布流程预留空间。 ## 文档受众 本项目的文档面向三类主要用户： - **开发者**：项目的主要负责人和参与者，也是文档的主要编写者。开发者关注项目结构、开发流程、模块边界、架构设计、接口约定、部署发布和技术决策背景。 - **AI 辅助工具**：通过读取项目文档理解项目上下文，用于辅助编码、重构、排查问题、生成说明和补全文档。AI 辅助工具需要稳定、结构化、少歧义的文档内容。 - **最终用户**：项目的实际使用者，主要阅读安装、配置、使用教程、常见问题和版本说明，不需要理解完整的内部实现细节。 本项目坚持单一文档源码原则：所有文档都只在一份 MDX 源码中维护，不为不同受众复制多份文档。 文档源码按内容类型组织，而不是按受众拆成多套目录。同一份文档通过章节安排、标题层级和写作约定同时兼顾开发者、AI 辅助工具和最终用户。 ## 文档结构原则 本项目采用三三制组织文档： - 一级目录只保留三个：`需求`、`指南`、`运维`。 - 每个一级目录下最多保留三个核心分类目录。 - 具体 MDX 文件放在核心分类目录中，新增文档优先归入已有分类。 - `docs/index.mdx` 是文档入口文件，不计入三三制目录约束。 三三制的目标是降低维护成本，避免顶层文档结构膨胀，让开发者、AI 辅助工具和最终用户都能快速定位信息。 ## 技术栈 当前项目使用以下技术栈： - **Sätteri**：文档处理核心，负责 Markdown / MDX 的解析、转换和编译。 - **MDX**：文档源码格式，主要按 Markdown 使用；仅在确实需要时使用 MDX 的扩展能力。 - **Node.js**：运行构建脚本，扫描文档、读取模板并写入静态 HTML。 - **HTML 模板**：通过 `templates/` 定义页面骨架、导航区域和内容区域。 - **VitePress-like CSS**：借鉴 VitePress 默认文档站视觉语言，实现顶部栏、侧边栏、正文排版和响应式布局。 - **yazl**：在构建时生成模板下载 zip，避免项目内维护自定义压缩实现。 README 中的技术栈描述的是本项目自身的文档生成工具链。`docs/需求/开发规范/技术栈.mdx` 用于记录被管理项目的技术栈，两者职责不同，避免重复维护。 默认不引入 VitePress、Vue、React、Vite、搜索框架、额外代码高亮框架或本地文档服务。项目只在执行 `npm run build` 时读取 `docs/**/*.mdx`，通过模板生成静态 HTML。 ## 构建方式 ```sh npm install npm run build ``` 构建产物输出到 `dist/`。日常维护直接在 VS Code 中编辑 `docs/**/*.mdx`，需要发布给最终用户时再执行构建命令。 构建时会同时生成 `dist/assets/mdx-doc-template.zip`。页面顶部右侧的“模板下载”按钮指向这个文件，方便将本项目作为其他软件项目的文档工具模板。 模板压缩包只保留核心内容：`docs/`、`scripts/`、`templates/`、`assets/`、可选的 `public/`、`README.md`、`LICENSE`、`package.json`、`package-lock.json` 和 `.gitignore`。不会包含 `.git/`、`node_modules/`、`dist/`、`target/`、`.maudit-content/` 等项目管理目录或构建产物。 页面默认启用内容居中显示：左侧导航和正文区域作为一个整体限制最大宽度并居中，避免超宽屏下文档区域铺满整屏。顶部右侧的图标按钮可以切换该模式，偏好会保存在浏览器本地。 ## 目录结构 当前初始目录结构如下： ```text mdx-doc/ ├── docs/ │ ├── index.mdx │ ├── 需求/ │ │ ├── 项目需求/ │ │ │ ├── 项目背景.mdx │ │ │ ├── 用户场景.mdx │ │ │ └── 功能范围.mdx │ │ ├── 设计理念/ │ │ │ ├── 架构设计.mdx │ │ │ ├── 数据库设计.mdx │ │ │ ├── 接口设计.mdx │ │ │ └── UI设计.mdx │ │ └── 开发规范/ │ │ ├── 技术栈.mdx │ │ └── 接口规范.mdx │ ├── 指南/ │ │ ├── 入门/ │ │ │ └── 快速开始.mdx │ │ ├── 手册/ │ │ │ └── 使用手册.mdx │ │ └── 参考/ │ │ └── 参考说明.mdx │ └── 运维/ │ ├── 环境/ │ │ └── 开发环境.mdx │ ├── 发布/ │ │ └── 构建发布.mdx │ └── 记录/ │ └── 变更记录.mdx ├── assets/ │ └── style.css ├── package.json ├── package-lock.json ├── scripts/ │ └── build.mjs ├── templates/ │ └── layout.html └── README.md ``` ### 目录说明 - `docs/`：MDX 文档源文件目录。所有项目文档优先放在这里。 - `docs/index.mdx`：文档首页，用于说明项目背景、核心能力和阅读入口。 - `docs/需求/`：说明为什么做、要做什么、按照什么原则做。下设 `项目需求`、`设计理念`、`开发规范` 三个核心分类目录。 - `docs/需求/项目需求/`：记录项目背景、目标用户、核心场景、功能范围、验收标准等需求类文档。 - `docs/需求/设计理念/`：记录不同项目需要的设计文档，例如架构设计、数据库设计、接口设计、UI 设计等。该目录允许根据项目实际情况增减具体设计文档。 - `docs/需求/开发规范/`：记录被管理项目的开发约束和协作规范，默认包括被管理项目的技术栈、接口规范，也可以补充编码规范、文档规范、AI 协作规范等。 - `docs/指南/`：说明如何使用项目和阅读文档。下设 `入门`、`手册`、`参考` 三个核心分类目录。 - `docs/指南/入门/`：面向首次使用者，说明安装、配置和最短可用路径。 - `docs/指南/手册/`：面向最终用户，说明完整功能、常见流程和使用示例。 - `docs/指南/参考/`：收敛接口、配置项、命令和常见问题等参考资料。 - `docs/运维/`：说明如何开发、构建、发布和维护项目。下设 `环境`、`发布`、`记录` 三个核心分类目录。 - `docs/运维/环境/`：记录本地开发、调试、测试和协作流程。 - `docs/运维/发布/`：记录静态站点构建、部署、发布和回滚流程。 - `docs/运维/记录/`：记录版本变更、迁移说明和重要历史背景。 - `scripts/build.mjs`：静态 HTML 构建脚本，负责扫描 MDX、生成导航、套用模板并输出 `dist/`。 - `templates/layout.html`：页面模板，用于控制 HTML 结构和可替换区域。 - `assets/style.css`：静态样式文件，提供 VitePress-like 文档站布局和排版。 - `public/assets/`：可选静态资源目录。只有当文档需要图片、图标、下载文件等资源时再添加。 - `dist/`：静态 HTML 构建产物目录，由构建命令生成，通常不提交到版本库。 - `dist/assets/mdx-doc-template.zip`：模板下载文件，由构建命令自动生成，供其他项目初始化文档工具时使用。 ## 文档写作约定 - 每篇文档使用一个明确的一级标题。 - 文档目录和文档文件名使用中文命名，例如 `docs/指南/入门/快速开始.mdx`。 - 遵循三三制：一级目录控制为 `需求`、`指南`、`运维`，每个一级目录下最多三个核心分类目录。 - 三三制约束的是顶层目录和核心分类目录，不限制分类目录内的具体 MDX 文件数量。 - 具体 MDX 文件数量不强行限制，但应归入明确分类，避免在顶层随意新增目录。 - 如需使用图片和附件，统一放入 `public/assets/`，并在 MDX 中使用稳定路径引用。 - 项目说明类文档优先写清楚背景、目标、使用方式和边界。 - 架构类文档优先说明模块职责、数据流、依赖关系和关键取舍。 - 面向最终用户的章节应避免暴露不必要的内部实现细节，优先说明可操作步骤和预期结果。 - 面向开发者的章节应记录上下文、约束和取舍，避免只写结论。 - 供 AI 辅助工具读取的章节应使用稳定标题、明确术语和直接陈述，减少含糊表达，方便工具读取和引用。 ### 页面元数据 每个 MDX 页面可以通过 frontmatter 提供基础页面信息。默认只保留静态文档生成所需的最小元数据，避免过早引入复杂发布规则。 ```mdx --- title: 快速开始 description: 从零开始使用项目文档。 order: 1 --- ``` - `title`：页面标题。 - `description`：页面摘要，用于列表、导航或 HTML 元信息。 - `order`：同级页面排序。 ## 后续计划 - 维护 MDX 文档骨架和写作规范。 - 持续调整 VitePress-like 页面样式和导航体验。 - 根据实际发布目标补充发布脚本，优先复用 `npm run build` 的静态产物。