在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

mermaid-js/mermaid

菜单

文档系统

相关源文件

本文档描述了 Mermaid.js 项目中使用的文档系统。它涵盖了文档的结构、构建、维护和发布方式。有关文档贡献的信息，请参阅贡献指南。

概述

Mermaid 文档系统基于 VitePress，这是一个由 Vue 提供支持的静态站点生成器。文档源文件以 Markdown 编写并存储在仓库中，然后经过处理并发布到 mermaid.js.org 网站。

来源：CONTRIBUTING.md405-417

文档目录结构

文档系统遵循特定的目录结构，将源文件与生成输出分开。

文档组织如下：

  • 源文件：位于 packages/mermaid/src/docs/
  • 生成文件：位于 /docs/（不应直接编辑）
  • 配置：VitePress 配置在 .vitepress/config.ts 中定义
  • 组件：文档中使用的自定义 Vue 组件位于 .vitepress/components/

来源：CONTRIBUTING.md405-417 packages/mermaid/src/docs/.vitepress/components/TopBar.vue1-154

文档工作流程

文档系统的工作流程包括从创建到发布的几个步骤。

文档工作流程中的关键点：

  1. 贡献者在 packages/mermaid/src/docs 目录中编辑源文件
  2. 提交更改后，GitHub Actions 会处理这些文件
  3. 处理后的文件存储在 /docs 目录中
  4. 合并到 master 分支的更改将反映在官方网站上

来源：405-428

文档格式与样式

文档以 Markdown 编写，并带有一些附加功能和样式约定。

Markdown 扩展

Mermaid 的文档系统支持 Markdown 的多种扩展：

  1. 警示框：您可以创建注释、提示、警告和危险框
```note
This is a note


2. **Mermaid diagrams**: Documentation can include Mermaid diagrams using code blocks (note that the documentation about Mermaid uses the `mermaid-nocode` tag to prevent rendering in examples)

3. **VitePress frontmatter**: Documentation files can include YAML frontmatter for metadata

Sources: <FileRef file-url="https://github.com/mermaid-js/mermaid/blob/8a703bd0/CONTRIBUTING.md#L452-L496" min=452 max=496 file-path="CONTRIBUTING.md">Hii</FileRef> <FileRef file-url="https://github.com/mermaid-js/mermaid/blob/8a703bd0/packages/mermaid/src/docs/news/announcements.md#L1-L4" min=1 max=4 file-path="packages/mermaid/src/docs/news/announcements.md">Hii</FileRef>

## Documentation Components

The documentation site includes several custom Vue components that enhance the user experience.

### TopBar Component

The TopBar component displays announcements and promotional content at the top of each documentation page. It includes rotating taglines with links to Mermaid Chart features.

```mermaid
classDiagram
    class TopBar {
        +design: number
        +taglines: Taglines[]
        +index: number
        +onMounted()
    }
    
    class Taglines {
        +label: string
        +url: string
    }
    
    TopBar --> Taglines : contains

该组件处理：

  • 设计变体的随机选择
  • 不同标语的循环显示
  • 提供 Mermaid Chart 功能的链接

来源：packages/mermaid/src/docs/.vitepress/components/TopBar.vue1-154

文档构建过程

文档通过 GitHub Actions 自动化构建。

生成文件中的警告标题明确指出它们是自动生成的

> **Warning**
>
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
>
> ## Please edit the corresponding file in <FileRef file-url="https://github.com/mermaid-js/mermaid/blob/8a703bd0/packages/mermaid/src/docs/..." undefined  file-path="packages/mermaid/src/docs/...">Hii</FileRef>

此警告有助于防止贡献者直接修改生成的文件。

来源：docs/news/announcements.md1-6 docs/news/blog.md1-6 docs/config/setup/README.md1-6

在本地运行文档

贡献者可以在本地运行文档站点，以便在提交更改前进行预览。

命令行指令

主机环境

或

Docker 环境

运行这些命令后，文档站点将在 http://:3333/ 可用。

来源：429-450

文档导航在 VitePress 配置文件中定义。对文档组织进行的任何更改，例如添加新章节或重新排列现有章节，都需要更新此配置。

要提出对文档结构的更改，贡献者必须更新 VitePress 配置文件中定义的侧边栏导航。

来源：498-500

发布流程

Mermaid 文档遵循特定的发布流程：

  1. 贡献者修改 packages/mermaid/src/docs 中的文件
  2. GitHub Actions 处理这些文件并生成 /docs 目录的内容
  3. master 分支的内容发布到 mermaid.js.org

为了使此过程正常工作，如果贡献者希望在创建拉取请求之前查看生成的文档，则需要在其 fork 中启用 GitHub Actions。

来源：502-508

新闻与公告

文档系统包含新闻、博客文章和公告部分。这些部分提供有关 Mermaid 及相关项目（如 Mermaid Chart）的最新信息。

博客部分

博客部分包含按时间顺序排列的博客文章列表，包括标题、日期和简要描述。此内容维护在 packages/mermaid/src/docs/news/blog.md 文件中。

公告部分

公告部分提供有关项目的重要更新。此内容维护在 packages/mermaid/src/docs/news/announcements.md 文件中。

来源：packages/mermaid/src/docs/news/blog.md1-265 packages/mermaid/src/docs/news/announcements.md1-50

版本控制与发布说明

当为新功能添加文档时，贡献者应使用特定语法包含版本指示符

# Feature Name (v<MERMAID_RELEASE_VERSION>+)

此占位符将在发布时自动替换为当前版本号，帮助用户识别特定功能的引入时间。

来源：385-392