openpitrix/docs.openpitrix.io

OpenPitrix 文档仓库

镜像概述和主要用途

OpenPitrix文档仓库是用于管理和维护OpenPitrix项目技术文档的专用仓库。它支持多版本、多语言文档的开发、编辑与贡献，提供结构化的文档导航和展示功能，帮助开发者和用户获取OpenPitrix项目的相关技术信息。

核心功能和特性

• 多版本支持：通过content目录下的版本子目录（如v1.0）管理不同版本的文档
• 多语言支持：每个版本目录下包含en（英文）和zh-CN（中文）等语言子目录，支持国际化文档
• 导航管理：通过toc_*.json文件定义各版本、各语言的文档导航结构，控制页面导航展示
• 文档格式：采用特定Markdown格式，支持标题、图片引用等元素，确保文档展示一致性
• 静态资源管理：文档图片等静态资源统一存放在static目录，便于引用和管理

使用场景和适用范围

适用于OpenPitrix项目的文档开发者和贡献者，主要用于：

• 本地开发和预览OpenPitrix文档
• 添加新的文档版本
• 编辑现有文档内容
• 维护文档导航结构

使用方法和配置说明

开发

通过以下步骤克隆仓库并进行本地开发：

shell
git clone https://github.com/openpitrix/docs.openpitrix.io.git
cd docs.openpitrix.io
yarn
yarn develop

贡献

仓库结构

bash
├── content                                         // 文档目录
│   ├── v1.0                                        // 文档版本
│   │   ├── en                                      // 文档语言 
│   │   │   └── openpitrix-install-guide.md         // 文档文件
│   │   └── zh-CN
│   │       └── openpitrix-install-guide.md 
│   ├── toc_v1.0_en.json                            // 目录文件，定义页面导航
│   └── toc_v1.0_zh-CN.json
├── src
└── static                                          // 文档图片存放目录
    └── create-repo.png

添加新版本

1. 在content目录下创建新的版本目录：

shell
cd content && mkdir version-xxxx

2. 在新版本目录下为每种支持的语言创建子目录：

shell
cd content/version-xxxx && mkdir zh-CN en

3. 在content目录下为新版本的每种语言创建导航文件：

shell
cd content
touch toc_version-xxx_en.json toc_version-xxx_zh-CN.json

编辑导航

导航文件示例：

• id：格式应为{version}-{language}
• chapters：导航项
• title：导航标题
• entry：导航入口，指向要显示的文档路径
• entries：子导航

json
{
  "id": "v1.0-zh-CN",
  "chapters": [
    {
      "title": "简介",
      "entry": "./v1.0/zh-CN/basic.md"
    },
    {
      "title": "安装指南",
      "chapters": [
        {
          "title": "部署模式",
          "entries": [
            {
              "entry": "./v1.0/zh-CN/openpitrix-install-guide.md"
            },
            {
              "entry": "./v1.0/zh-CN/allinone.md"
            },
            {
              "entry": "./v1.0/zh-CN/kubernetes.md"
            }
          ]
        }
      ]
    }
  ]
}

编辑文档

文档示例：

markdown
---
  title: '文档标题，将显示在导航中'
---

  ## 标题 1

  内容 1

  ![](/image.png) 

  此路径将请求 `/static/image.png`

  ## 标题 2

  ### 子标题 2.1
    内容 2.1
  
  ### 标题 3

## 会转换为页面锚点，并显示在导航中。