diff --git a/.github/workflows/app_from_contentful.yml b/.github/workflows/app_from_contentful.yml index 06c0fdfd..b6595426 100644 --- a/.github/workflows/app_from_contentful.yml +++ b/.github/workflows/app_from_contentful.yml @@ -1,3 +1,7 @@ +# 从 Contentful CMS 自动生成 App 应用的元数据文档（_include/）和 App 文档骨架。 +# 触发方式：管理员手动触发（workflow_dispatch），需要仓库 Write 权限 + CONTENTFUL_ACCESS_TOKEN。 +# 注意：该 workflow 生成的 _include/ 文件不应手工修改，属于自动管理内容。 + name: Generate Apps header and appdocs files on: @@ -8,14 +12,15 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v5 with: python-version: '3.x' + cache: 'pip' - name: Install dependencies run: | @@ -26,9 +31,9 @@ jobs: env: CONTENTFUL_ACCESS_TOKEN: ${{ secrets.CONTENTFUL_GRAPHQLTOKEN }} run: | - python builds/gen_md_from_contenful.py template/meta/zh_head.jinja2 versioned_docs/version-2.0/apps/_include --override - python builds/gen_md_from_contenful.py template/meta/en_head.jinja2 i18n/en/docusaurus-plugin-content-docs/version-2.0/apps/_include --override - python builds/gen_md_from_contenful.py template/meta/zh_app.jinja2 versioned_docs/version-2.0/apps --ignore-list template/meta/skip_file.json + python builds/gen_md_from_contenful.py template/meta/zh_head.jinja2 versioned_docs/version-2.0/apps/_include + python builds/gen_md_from_contenful.py template/meta/en_head.jinja2 i18n/en/docusaurus-plugin-content-docs/version-2.0/apps/_include + python builds/gen_md_from_contenful.py template/meta/zh_app.jinja2 versioned_docs/version-2.0/apps --ignore-list template/meta/skip_file.json python builds/gen_md_from_contenful.py template/meta/en_app.jinja2 i18n/en/docusaurus-plugin-content-docs/version-2.0/apps --ignore-list template/meta/skip_file.json - name: Commit and push changes diff --git a/.github/workflows/build_doc.yml b/.github/workflows/build_doc.yml index 5c9bfa9c..38ceddfb 100644 --- a/.github/workflows/build_doc.yml +++ b/.github/workflows/build_doc.yml @@ -1,15 +1,28 @@ -# This workflow is triggered on pushes and pull requests to any branch. -# The job name includes the branch name dynamically. +# 文档构建与部署工作流 +# - dev 分支：只构建，不部署（用于验证 PR 不破坏构建） +# - main 分支：构建 + 部署到 Cloudflare Pages（生产环境） name: Docs Build and Upload to Cloudflare -on: +on: workflow_dispatch: push: branches: - dev - main - paths: + paths: + - 'docs/**' + - 'versioned_docs/**' + - 'i18n/**' + - 'src/**' + - 'static/**' + - '**.js' + - '.github/workflows/**' + - '!docs/_list' + pull_request: + branches: + - dev + paths: - 'docs/**' - 'versioned_docs/**' - 'i18n/**' @@ -18,27 +31,38 @@ on: - '**.js' - '!docs/_list' +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + jobs: build: name: Build on branch ${{ github.ref_name }} runs-on: ubuntu-latest - #if: false # stop steps steps: - - uses: actions/checkout@master + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 with: - node-version: 20 + node-version: 20 + + - name: Cache yarn dependencies + uses: actions/cache@v4 + with: + path: node_modules + key: ${{ runner.os }}-yarn-${{ hashFiles('**/package.json') }} + restore-keys: | + ${{ runner.os }}-yarn- + - name: Docusaurus build run: | yarn install yarn run build env: CI: true - - - name: Debug - run: ls - name: Create apidocs directory and add files + continue-on-error: true run: | mkdir -p build/apidocs cd build/apidocs @@ -46,29 +70,26 @@ jobs: wget -O README.md https://websoft9.github.io/websoft9/apphub/apidocs/README.md wget -O index.html https://websoft9.github.io/websoft9/apphub/apidocs/index.html docker run -d --name apphub -p 8080:8080 websoft9dev/apphub:latest - sleep 5 - max_attempts=10 - url="http://localhost:8080/openapi.json" - for attempt in $(seq 1 $max_attempts); do - echo "Attempt #$attempt to download $url..." - if wget -O openapi.json "$url"; then - echo "Successfully downloaded $url" - break - else - echo "Failed to download $url. Waiting for 5 seconds before retry..." - sleep 5 - fi - done + sleep 5 + max_attempts=10 + url="http://localhost:8080/openapi.json" + for attempt in $(seq 1 $max_attempts); do + echo "Attempt #$attempt to download $url..." + if wget -O openapi.json "$url"; then + echo "Successfully downloaded $url" + break + else + echo "Failed to download $url. Waiting for 5 seconds before retry..." + sleep 5 + fi + done - name: Publish to Cloudflare Pages + if: github.ref == 'refs/heads/main' uses: cloudflare/pages-action@v1 with: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} accountId: eb79f13320db531d8cf1f3720966b695 projectName: doc-websoft9-com directory: build - # Optional: Enable this if you want to have GitHub Deployments triggered gitHubToken: ${{ secrets.GITHUB_TOKEN }} - # Optional: Switch what branch you are publishing to. - # By default this will be the branch which triggered this workflow - # branch: dev diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 24f0c3d8..a066b485 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -1,30 +1,45 @@ -# ProxyCheck: Read dockerhub proxy URL from docs/reference/_include/dockerhub-proxy.md and test the network speed -# Spellcheck +# 文档质量检查工作流 +# - push 到 dev 分支时触发 +# - 向 dev 分支提 PR 时触发（作为合并前的强制质量门） +# 功能：使用 lychee 检查文档中的 broken links，结果输出为 artifact name: Check Action -on: +on: workflow_dispatch: push: branches: - dev - + pull_request: + branches: + - dev + jobs: + broken-links: + name: Broken Links Check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Check broken links + uses: lycheeverse/lychee-action@v2 + with: + args: >- + --verbose + --no-progress + --exclude-path node_modules + --exclude-path build + versioned_docs/ + i18n/ + fail: false + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - # Spellcheck: - # name: Spellcheck - # runs-on: ubuntu-latest - # steps: - # - uses: actions/checkout@v3 - # - uses: rojopolis/spellcheck-github-actions@0.41.0 - # name: Spellcheck - # with: - # source_files: i18n/en/docusaurus-plugin-content-docs/current/**/*.md - # task_name: Markdown - # output_file: spellcheck-output.txt + - name: Upload lychee results + uses: actions/upload-artifact@v4 + if: always() + with: + name: lychee-report + path: lychee/out.md + retention-days: 7 - # - uses: actions/upload-artifact@v3 - # if: '!cancelled()' # Do not upload artifact if job was cancelled - # with: - # name: Spellcheck Output - # path: spellcheck-output.txt diff --git a/.github/workflows/json2md.yml b/.github/workflows/json2md.yml index d31079b3..869e4b7c 100644 --- a/.github/workflows/json2md.yml +++ b/.github/workflows/json2md.yml @@ -1,28 +1,34 @@ +# 从制品文件生成 App 应用目录列表 Markdown。 +# 触发方式：手动触发 或 repository_dispatch（事件名: applist_dev_event）。 +# repository_dispatch 由 Websoft9 主仓库 release 时自动触发。 + name: Generate Apps list for docs on: workflow_dispatch: repository_dispatch: types: [applist_dev_event] - + jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - name: Setup Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v5 with: python-version: "3.x" + cache: 'pip' - name: Install unzip utility run: sudo apt-get install unzip - name: Download and unzip JSON files run: | - curl -L -o media-latest.zip https://artifact.websoft9.com/release/websoft9/plugin/media/media-latest.zip + curl -L --retry 3 --retry-delay 5 --retry-connrefused --fail \ + -o media-latest.zip https://artifact.websoft9.com/release/websoft9/plugin/media/media-latest.zip unzip media-latest.zip "media/json/product_zh.json" "media/json/product_en.json" "media/json/catalog_zh.json" "media/json/catalog_en.json" -d ./extracted - name: Generate Markdown for app catalog README.mdx(zh) @@ -53,3 +59,4 @@ jobs: uses: stefanzweifel/git-auto-commit-action@v4 with: commit_message: Update Product Catalog Markdown + diff --git a/.github/workflows/update.yml b/.github/workflows/update.yml index 423b4a6f..85e2b406 100644 --- a/.github/workflows/update.yml +++ b/.github/workflows/update.yml @@ -8,7 +8,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: Install dependencies run: | diff --git a/.lycheeignore b/.lycheeignore new file mode 100644 index 00000000..a4736e79 --- /dev/null +++ b/.lycheeignore @@ -0,0 +1,19 @@ +# lychee broken-links 检查排除规则 +# 以下 pattern 匹配的链接将不被检查 + +# 本地开发地址 +localhost +127.0.0.1 + +# CDN 图片域名（外网请求不稳定，大量图片链接） +libs.websoft9.com + +# Algolia 搜索相关（动态 URL 中出现的 appId 和 indexName） +NA4GDUSQ4H +support-websoft9 + +# 内部支持站点 +support.websoft9.com + +# 文档模板占位链接 +example.com diff --git a/CHANGELOG.md b/CHANGELOG.md index 5bbe2279..f45c94c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,2 +1,37 @@ -# 开发日志 +# Changelog + +本文件记录本项目的所有重要变更，遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/) 规范。 + +版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 + +--- + +## [Unreleased] + +### Added + +- 新增 `CONTRIBUTING.md` 贡献指南（由 `developer.md` 重命名并全面重写），包含分支策略、PR 规范、i18n 说明、文档原则和常见问题 +- 新增 `DEVELOPMENT.md` 开发手册，包含环境配置、本地开发命令、模板系统说明、CI/CD 工作流说明、BMAD Quick Flow 使用指南和 App 文档创建标准流程 +- 新增 `template/docs/zh/app.md` Quick Flow 专用 App 文档 Prompt 模板 +- 新增 `.lycheeignore` broken-links 检查排除规则文件 + +### Changed + +- `README.md` 全面重写：新增 CI badge、Tech Stack badge、快速开始、项目结构和文档链接 +- `docs/readme.md` 更新为 next 版本说明 +- `build_doc.yml`：升级 `checkout@master` → `@v4`，新增 yarn cache、concurrency 控制，删除调试步骤，修复 Docker 缩进，区分 dev/main 分支部署行为，apidocs 步骤设为 `continue-on-error: true`，新增 `pull_request` 触发（PR 构建质量门） +- `check.yml`：全量重写，恢复 broken-links 检查（`lychee-action@v2`），新增 PR 触发 +- `app_from_contentful.yml`：升级 `checkout@v2` → `@v4`、`setup-python@v2` → `@v5`，新增 pip cache，移除 `--override` 参数 +- `json2md.yml`：升级 `checkout@v2` → `@v4`、`setup-python@v2` → `@v5`，新增 pip cache，curl 新增重试参数 +- `update.yml`：升级 `checkout@v2` → `@v4` + +### Removed + +- 删除 `Notes.md`（内容已迁移至 `CONTRIBUTING.md`） +- 删除 `add_apps.md`（纯占位文件） + +--- + + +[Unreleased]: https://github.com/Websoft9/doc.websoft9.com/compare/HEAD...HEAD diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..046aabc5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,139 @@ +# 贡献指南（Contributing Guide） + +感谢你为 [Websoft9 文档站](https://support.websoft9.com) 做出贡献！本文说明分支策略、PR 规范、i18n 要求和文档质量原则。 + +--- + +## 分支策略 + +| 分支 | 用途 | 说明 | +|------|------|------| +| `dev` | 开发分支 | **所有 PR 必须提交到此分支** | +| `main` | 生产分支 | 仅由 Owner 合并，触发 Cloudflare Pages 部署 | + +> ⚠️ **Owner 不接受直接向 `main` 提交的 PR。** + +--- + +## PR 流程 + +1. Fork 本仓库（外部贡献者）或新建 feature 分支（内部成员） +2. 在 `dev` 分支基础上创建工作分支，命名建议：`feat/appname-doc`、`fix/broken-link` +3. 完成修改后向 `dev` 分支提 PR +4. PR 会自动触发 `check.yml`（broken-links 检查）和 `build_doc.yml`（构建验证） +5. 通过 CI 检查 + Owner Review 后 merge + +--- + +## 国际化（i18n） + +本项目支持 **中文（默认）** 和 **英文** 两种语言： + +| 内容类型 | 中文路径 | 英文路径 | +|----------|----------|----------| +| 版本文档 | `versioned_docs/version-2.0/` | `i18n/en/docusaurus-plugin-content-docs/version-2.0/` | +| 主题翻译 | — | `i18n/en/docusaurus-theme-classic/` | +| 插件翻译 | — | `i18n/en/code.json` | + +**提交 App 或功能文档时，建议同步更新中英文两份文件。** 若英文翻译暂时缺失，可先提交中文版，后续补充英文。 + +推荐翻译工具：[DeepL](https://www.deepl.com/) + [DeepL Write](https://www.deepl.com/zh/write) 校对。 + +--- + +## 文档质量原则 + +好的文档应遵循以下 10 条原则： + +1. **可维护优先**：文档进化的第一任务是可维护性，允许使用上存在"不直观"的情况 +2. **组件化设计**：像编写程序一样设计文档的组件和接口 +3. **三层技术体系**：文档满足入门、配置、运维三层结构 +4. **通用方案复用**：通用方案参考 + 特殊要素清单 = 特殊解决方案（例：特殊 Nginx 配置只需列出配置文件模板，不重复步骤说明） +5. **路由扁平化**：路由层级不超过两层结构 +6. **内容与结构分离**：`_include/` 片段由 CI 自动生成，不应手工维护 +7. **锚点语义化**：标题锚点使用语义化英文（如 `{#guide}`、`{#wizard}`） +8. **截图规范**：截图命名格式 `{appname}-{feature}-websoft9.png`，存放于 `assets/` 目录 +9. **链接健壮性**：避免使用绝对路径外链，内部链接使用相对路径 +10. **中英文同步**：重要内容变更后及时同步英文版本 + +--- + +## 常见问题 + +#### 多层链接写法有哪些？ + +``` +./../administrator/firewall#security +../ +./ +``` + +#### 异常有哪些参数类型？ + +``` +Type: 'ignore' | 'log' | 'warn' | 'throw' +``` + +#### `app_from_contentful.yml` 自动生成文档需要排除哪些应用？ + +该 Action 根据 Contentful 产品数据自动在 `apps/` 生成中英文文档。以下类型应用需排除： + +- 非 Docker 应用（如 BT、明道） +- 环境类应用（如 Python、Ruby，未放在 `apps/` 目录） + +排除列表：[`template/meta/skip_file.json`](template/meta/skip_file.json) + +#### `build_doc.yml` 因 `broken links` 失败？ + +若出现类似以下错误： + +``` +Broken link on source page path = /docs/apps: + -> linking to ./phpfpmapache (resolved as: /docs/phpfpmapache) +``` + +说明有 App 文档路由缺失。排除列表：[`template/meta/skip_applink.json`](template/meta/skip_applink.json) + +#### `json2md.yml`（Generate Apps list for docs）执行失败？ + +1. 下载最新制品 `media_latest.zip` 并解压 +2. 在 `product_zh.json` 中找出 `"title": "产品"` 对应的 `appname` +3. 确保该 App 的父 catalog 不是一级目录 +4. 重新更新 media 制品后重新触发 Action + +--- + +## Docsearch 配置参考 + +如需更新 Algolia Docsearch 抓取配置，使用以下 scraper 配置： + +```json +{ + "index_name": "websoft9", + "start_urls": ["https://support.websoft9.com/"], + "selectors": { + "lvl0": { + "selector": "(//ul[contains(@class,'menu__list')]//a[contains(@class,'menu__link menu__link--sublist menu__link--active')]/text() | //nav[contains(@class,'navbar')]//a[contains(@class,'navbar__link--active')]/text())[last()]", + "type": "xpath", + "global": true, + "default_value": "Documentation" + }, + "lvl1": "header h1", + "lvl2": "article h2", + "lvl3": "article h3", + "lvl4": "article h4", + "lvl5": "article h5,article td:first-child", + "lvl6": "article h6", + "text": "article p, article li, article td:last-child" + }, + "strip_chars": " .,;:#", + "custom_settings": { + "separatorsToIndex": "_", + "attributesForFaceting": ["language", "version", "type", "docusaurus_tag"], + "attributesToRetrieve": ["hierarchy", "content", "anchor", "url", "url_without_anchor", "type"] + }, + "conversation_id": ["833762294"], + "nb_hits": 46250 +} +``` + diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 00000000..67f04378 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,210 @@ +# 开发手册（Development Guide） + +本手册面向本仓库的文档维护者和内容贡献者，涵盖本地开发环境搭建、工具链使用、CI/CD 工作流说明、BMAD AI 辅助开发，以及新增 App 文档的完整标准流程。 + +--- + +## 环境要求 + +| 工具 | 版本要求 | 说明 | +|------|----------|------| +| Node.js | >= 18 | 推荐使用 LTS 版本 | +| yarn | >= 1.22 | 包管理器（`yarn.lock` 不提交到版本库） | +| Python | >= 3.8 | 构建脚本依赖 | +| Git | >= 2.x | 版本控制 | + +--- + +## 本地开发命令 + +```bash +# 安装依赖 +yarn install + +# 启动本地开发服务器（中文，默认） +npm run start -- --host 0.0.0.0 --port 3000 + +# 启动本地开发服务器（英文） +npm run start -- --host 0.0.0.0 --port 3000 --locale en + +# 构建生产包 +yarn build + +# 本地预览构建结果 +npm run serve -- --host 0.0.0.0 --port 3000 + +# 生成 i18n 翻译文件（新增翻译语言时使用） +yarn run write-translations -- --locale zh-cn + +# 升级 Docusaurus（生成 PR，不直接 push） +yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest +``` + +> **注意**：`yarn.lock` 已在 `.gitignore` 中，**不提交**。CI 使用 `package.json` hash 作为缓存键。 + +--- + +## 项目结构说明 + +``` +versioned_docs/version-2.0/ # 中文主文档（当前版本） +i18n/en/ # 英文翻译文档 +builds/ # Python 构建脚本 +template/ + meta/ # Jinja2 模板（Contentful 内容生成） + docs/zh/ # Quick Flow 专用 Prompt 模板 +.github/workflows/ # CI/CD 工作流 +``` + +--- + +## 模板系统 + +本项目使用两套模板系统： + +### 1. Jinja2 App 模板（`template/meta/`） + +由 `app_from_contentful.yml` 自动调用，从 Contentful CMS 生成 App 文档的 `_include/` 元数据片段和 App 文档骨架。 + +- `zh_head.jinja2` / `en_head.jinja2` — 生成 `apps/_include/{appname}.md` +- `zh_app.jinja2` / `en_app.jinja2` — 生成 `apps/{appname}.md` 骨架 +- `skip_file.json` — 排除不需要生成的应用列表 +- `skip_applink.json` — 排除无路由的应用链接 + +> ⚠️ **`_include/` 目录下的文件由 CI 自动生成，不应手工修改。** + +### 2. Quick Flow Prompt 模板（`template/docs/zh/`） + +供贡献者使用 BMAD Barry（QD 模式）填充 App 文档内容时参考。详见「新增 App 文档标准流程」章节。 + +--- + +## CI/CD 工作流说明 + +| 工作流 | 触发条件 | 用途 | +|--------|----------|------| +| `build_doc.yml` | push to `dev`/`main`，`workflow_dispatch` | 构建文档并部署到 Cloudflare Pages（main 分支）| +| `check.yml` | push to `dev`，PR to `dev`，`workflow_dispatch` | broken-links 检查（PR 质量门）| +| `app_from_contentful.yml` | `workflow_dispatch`（管理员手动触发）| 从 Contentful 生成 App 元数据文档 | +| `json2md.yml` | `workflow_dispatch`，`repository_dispatch: applist_dev_event` | 从制品生成 App 目录列表（由主仓库 release 触发）| +| `update.yml` | `workflow_dispatch` | 升级 Docusaurus 依赖并创建 PR | + +**分支行为差异（`build_doc.yml`）：** + +- `dev` 分支：执行构建验证，**不部署**到生产环境 +- `main` 分支：构建 + 部署到 Cloudflare Pages + +--- + +## AI 辅助开发（BMAD Quick Flow） + +本仓库已集成 [BMAD 方法](https://github.com/bmadcode/BMAD-METHOD)，提供 AI 驱动的文档开发加速工具。**BMAD 是本仓库专属内部工具**，适用于文档站内容贡献，不属于 `develop/` 多项目公共贡献区的内容。 + +### Quick Flow 三阶段流程 + +```mermaid +graph LR + QS["QS 规格阶段\n(Barry Quick Spec)"] + QD["QD 开发阶段\n(Barry Quick Dev)"] + CR["CR 审查阶段\n(Code Review / Human)"] + + QS -->|生成 tech-spec| QD + QD -->|实现 Tasks| CR +``` + +- **QS（Quick Spec）**：与 Barry 对话，输出结构化 tech-spec 文件，明确实现任务和验收标准 +- **QD（Quick Dev）**：Barry 读取 tech-spec，自动执行所有实现任务（写文档、修 CI、创建文件等） +- **CR（Code Review）**：人工审查 + PR Review，确认输出质量后 merge + +### 如何启动 Quick Flow + +在 VS Code Copilot Chat 中： + +``` +启动 quick dev +``` + +然后输入 `QS` 进入规格阶段，或 `QD` 直接进行实现（需提前有 tech-spec 文件）。 + +### 适用场景 + +- 新增或大幅重写 App 文档 +- 批量修改多个文件（如 CI/CD 升级） +- 需要结构化任务跟踪的中型改动 + +--- + +## 新增 App 文档标准流程 + +新增一个 App 的完整文档需要**管理员前置操作 + 贡献者执行**两个阶段。 + +### Step 0：管理员前置操作 + +> **此步骤需要仓库 Write 权限 + `CONTENTFUL_ACCESS_TOKEN`，普通贡献者无法自行完成。** + +1. 在 [Contentful CMS](https://app.contentful.com/) 中录入新 App 的产品数据 +2. 在 GitHub Actions 页面手动触发 `app_from_contentful.yml` +3. 确认以下两个文件已自动生成并 commit 到 `dev` 分支： + - `versioned_docs/version-2.0/apps/_include/{appname}.md` + - `i18n/en/docusaurus-plugin-content-docs/version-2.0/apps/_include/{appname}.md` + +> ⚠️ **贡献者必须等管理员完成 Step 0 后才能开始。** 若 `_include/{appname}.md` 不存在，本地 `yarn build` 将因 `onBrokenLinks: throw` 报错。 + +### Step 1：拉取最新代码并生成骨架 + +```bash +git checkout dev +git pull origin dev + +# 生成 App 文档骨架（根据现有模板创建文件） +python template/create_app.py {appname} +``` + +生成的文件： + +- `versioned_docs/version-2.0/apps/{appname}.md` — 中文主文档骨架 +- `i18n/en/docusaurus-plugin-content-docs/version-2.0/apps/{appname}.md` — 英文文档骨架 + +### Step 2：使用 Quick Flow 填充文档内容 + +1. 在 VS Code Copilot Chat 启动 Barry：`启动 quick dev` → 输入 `QD` +2. 告知 Barry：`请帮我填充 {appname} 的 App 文档，参考模板：template/docs/zh/app.md` +3. Barry 将依据模板结构生成： + - `## 入门指南` — 安装初始化、基本使用 + - `## 最佳实践` — 典型用例、集成方案 + - `## 配置选项` — 关键参数说明 + - `## 故障排除` — 常见问题 + +### Step 3：本地验证 + +```bash +# 验证中文版构建（_include 已存在，不会报错） +yarn build + +# 或本地预览 +npm run start -- --host 0.0.0.0 --port 3000 +``` + +### Step 4：提交 PR + +```bash +git checkout -b feat/{appname}-doc +git add versioned_docs/version-2.0/apps/{appname}.md +git add i18n/en/docusaurus-plugin-content-docs/version-2.0/apps/{appname}.md +git commit -m "docs: add {appname} documentation" +git push origin feat/{appname}-doc +``` + +向 `dev` 分支提 PR，等待 CI 检查通过后由 Owner Review。 + +### Step 5：英文翻译（可选但推荐） + +如 Step 2 中英文文档尚未完整填充，可使用 [DeepL](https://www.deepl.com/) 翻译中文版本后补充。 + +--- + +## 参考资源 + +- [Docusaurus 官方文档](https://docusaurus.io/docs) +- [BMAD 方法仓库](https://github.com/bmadcode/BMAD-METHOD) +- App 文档参考样例：[`versioned_docs/version-2.0/apps/wordpress.md`](versioned_docs/version-2.0/apps/wordpress.md) diff --git a/Notes.md b/Notes.md deleted file mode 100644 index 6dd7ee93..00000000 --- a/Notes.md +++ /dev/null @@ -1,49 +0,0 @@ -# 创作指南 - -## 文档10个原则 - -* 可维护是文档进化第一任务，也就是说允许使用上的“不直观”出现 -* 向编程序一样设计文档的：组件、接口 -* 文档满足三层技术体系 -* 通用方案参考+特殊要素清单=特殊解决方案。例如：特殊 Nginx 配置只需列出配置文件模板，而不用再次阐述步骤 -* 路由不超过两层结构 - -## 常见问题 - -#### 多层链接有哪些？ - -``` -./../administrator/firewall#security -../ -./ -``` - -#### 异常有哪些参数类型？ - -Type: 'ignore' | 'log' | 'warn' | 'throw' - - -#### Action app_from_contentful.yml 自动生成文档需要排除哪些应用？ - -这个 action 会根据所有 contenful 的产品数据自动在 apps 生成中英文文档。但是由于非docker应用例如：BT，明道已经从当前版本中剔除；环境类应用例如: Python，Ruby 没有放在 apps 目录下， -需要排除。排除列表请参照: [skip_file.json](template/meta/skip_file.json) - -#### build_doc.yml 由于产生 `broken links` 执行失败？ - - ``` - Exhaustive list of all broken links found: - - Broken link on source page path = /docs/apps: - -> linking to ./phpfpmapache (resolved as: /docs/phpfpmapache) - -> linking to ./phpfpmnginx (resolved as: /docs/phpfpmnginx) - ``` - -由于某些特殊的 app 没有对应的路由，需要排除这些应用。排除列表请参照: [skip_applink.json](template/meta/skip_applink.json) - - -#### Action json2md.yml（Generate Apps list for docs）执行失败？ - -1. 下载最新的制品 media_latest.zip并解压 -2. 查找product_zh.json中【"title": "产品"】，并找出它的appname -3. 需要保证这个app的父catalog不是一级目录 -4. 重新更新media制品后action即可正常执行 - diff --git a/README.md b/README.md index ea5a3280..4a0fc8c5 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,83 @@ -# About +# Websoft9 文档站 + +[![Build Status](https://github.com/Websoft9/doc.websoft9.com/actions/workflows/build_doc.yml/badge.svg)](https://github.com/Websoft9/doc.websoft9.com/actions/workflows/build_doc.yml) +[![Check Status](https://github.com/Websoft9/doc.websoft9.com/actions/workflows/check.yml/badge.svg)](https://github.com/Websoft9/doc.websoft9.com/actions/workflows/check.yml) +[![Docusaurus](https://img.shields.io/badge/Docusaurus-3.5.1-brightgreen)](https://docusaurus.io/) +[![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/) + +[Websoft9](https://github.com/Websoft9/websoft9) 官方文档站的源码仓库，基于 [Docusaurus 3.5.1](https://docusaurus.io/) 构建，部署于 [Cloudflare Pages](https://pages.cloudflare.com/)。 + +**在线访问**：[https://support.websoft9.com](https://support.websoft9.com) + +--- + +## 技术栈 + +| 技术 | 版本 | 用途 | +|------|------|------| +| Docusaurus | 3.5.1 | 文档框架 | +| Node.js | >= 18 | 运行环境 | +| yarn | >= 1.22 | 包管理器 | +| GitHub Actions | — | CI/CD | +| Cloudflare Pages | — | 静态托管部署 | +| Algolia Search | — | 全文搜索 | +| Python 3 / Jinja2 | — | 内容生成脚本 | + +--- + +## 快速开始 + +```bash +# 克隆仓库 +git clone https://github.com/Websoft9/doc.websoft9.com.git +cd doc.websoft9.com + +# 安装依赖 +yarn install + +# 启动本地开发服务器（中文） +npm run start -- --host 0.0.0.0 --port 3000 + +# 启动本地开发服务器（英文） +npm run start -- --host 0.0.0.0 --port 3000 --locale en + +# 生产构建 +yarn build +``` + +--- + +## 项目结构 + +``` +versioned_docs/version-2.0/ # 中文主文档（当前发布版本） +i18n/en/ # 英文翻译文档 +builds/ # Python 内容生成脚本 +template/ # 模板文件（Jinja2 + Quick Flow Prompt） +.github/workflows/ # CI/CD 工作流（5个） +src/ # Docusaurus 自定义组件 +static/ # 静态资源 +``` + +--- + +## 国际化（i18n） + +本站支持 **中文（默认）** 和 **英文** 两种语言。 + +- 中文主文档：`versioned_docs/version-2.0/` +- 英文翻译：`i18n/en/docusaurus-plugin-content-docs/version-2.0/` + +--- + +## 参与贡献 + +- 📖 **[CONTRIBUTING.md](CONTRIBUTING.md)** — 分支策略、PR 规范、文档原则 +- 🛠️ **[DEVELOPMENT.md](DEVELOPMENT.md)** — 本地开发、模板系统、BMAD AI 辅助、App 文档创建流程 +- 📋 **[CHANGELOG.md](CHANGELOG.md)** — 版本变更记录 + +> 所有 PR 请提交到 **`dev` 分支**，Owner 不接受直接向 `main` 提交的 PR。 -This is the documentation repository of [Websoft9](https://github.com/Websoft9/websoft9) which is a Multi-application Self-hosted PaaS platform. ## Contribute for it diff --git a/add_apps.md b/add_apps.md deleted file mode 100644 index e25163bb..00000000 --- a/add_apps.md +++ /dev/null @@ -1,2 +0,0 @@ -appname1 -appname2 diff --git a/developer.md b/developer.md deleted file mode 100644 index 54e184cc..00000000 --- a/developer.md +++ /dev/null @@ -1,30 +0,0 @@ -# Developer - -## docsearch-scraper - -``` - - CONFIG={ - "index_name":"websoft9", - "start_urls":["https://support.websoft9.com/"], - "selectors":{ - "lvl0":{ - "selector":"(//ul[contains(@class,'menu__list')]//a[contains(@class, 'menu__link menu__link--sublist menu__link--active')]/text() | //nav[contains(@class, 'navbar')]//a[contains(@class, 'navbar__link--active')]/text())[last()]", - "type":"xpath", - "global":true, - "default_value":"Documentation"}, - "lvl1":"header h1", - "lvl2":"article h2", - "lvl3":"article h3", - "lvl4":"article h4", - "lvl5":"article h5,article td:first-child", - "lvl6":"article h6", - "text":"article p, article li, article td:last-child"}, - "strip_chars":" .,;:#", - "custom_settings":{ - "separatorsToIndex":"_", - "attributesForFaceting":["language","version","type","docusaurus_tag"], - "attributesToRetrieve":["hierarchy","content","anchor","url","url_without_anchor","type"]}, - "conversation_id":["833762294"], - "nb_hits":46250} -``` - diff --git a/docs/readme.md b/docs/readme.md index 3346ad6e..49453334 100755 --- a/docs/readme.md +++ b/docs/readme.md @@ -1 +1,7 @@ -Preview for the next version \ No newline at end of file +# 文档说明 + +本目录为 Docusaurus `next`（未发布）版本的文档源文件目录。 + +当前对外发布的稳定版本为 **version-2.0**，位于 `versioned_docs/version-2.0/`。 + +`next` 版本内容不对外展示（`includeCurrentVersion: false`），仅用于开发中的新内容预览。 diff --git a/template/docs/zh/app.md b/template/docs/zh/app.md new file mode 100644 index 00000000..9b0f54a6 --- /dev/null +++ b/template/docs/zh/app.md @@ -0,0 +1,117 @@ +--- +title: "{{AppName}}" +prompt_version: "1.0" +usage: "在 BMAD Barry QD 模式下，使用此模板引导 AI 填充 App 文档内容" +reference_example: "versioned_docs/version-2.0/apps/wordpress.md" +--- + +# Quick Flow App 文档 Prompt 模板 + +## 使用说明 + +1. 将 `{{AppName}}` 替换为实际的应用名称（如 `WordPress`、`GitLab`） +2. 在 BMAD Barry QD 模式中告知：`请帮我填充 {appname} 的 App 文档，参考模板：template/docs/zh/app.md` +3. Barry 将根据以下结构生成完整文档内容 + +--- + +## Prompt 指令 + +你是一名专业的技术文档工程师，请帮我为 **{{AppName}}** 编写 Websoft9 应用文档。 + +### 背景信息 + +- **平台**：Websoft9（Multi-application Self-hosted PaaS） +- **目标读者**：使用 Websoft9 控制台部署并使用 {{AppName}} 的用户 +- **参考样例**：`versioned_docs/version-2.0/apps/wordpress.md`（阅读此文件了解标准结构和写作风格） +- **语言**：中文，技术术语保留英文原文 + +### 文档结构要求 + +请按以下结构填充 `versioned_docs/version-2.0/apps/{{appname}}.md` 文件： + +```markdown +--- +title: {{AppName}} +slug: /{{appname}} +tags: + - {{AppName}} + - （相关分类标签，如 CMS、数据库、开发工具等） +--- + +import Meta from './_include/{{appname}}.md'; + + + + +## 入门指南 {#guide} + +### 初始化 {#wizard} + +Websoft9 控制台安装 {{AppName}} 后，通过 "我的应用" 查看应用详情，在 "访问" 标签页中获取访问信息。 + +（描述安装后的初始化步骤：默认账号、首次登录、初始配置等） + +### （核心功能 1 标题）{#feature1} + +（描述最常用的核心功能场景，步骤清晰，必要时附截图说明） + +### （核心功能 2 标题，可选）{#feature2} + +（第二个常用功能场景） + + +## 最佳实践 + +### （典型集成或高级用例） + +（描述与其他 Websoft9 应用集成的场景，或企业级使用的最佳实践） + + +## 配置选项 {#configs} + +| 配置项 | 说明 | 默认值 | +|--------|------|--------| +| （关键配置参数名） | （说明） | （默认值） | + +（列出 3-5 个最重要的配置选项，来源于应用的官方配置文档） + + +## 管理维护 {#administrator} + +### 升级 + +（描述如何通过 Websoft9 控制台升级 {{AppName}} 版本） + +### 备份与恢复 + +（描述数据备份策略和恢复步骤） + + +## 故障排除 {#troubleshooting} + +#### {{AppName}} 无法访问？ + +（原因分析 + 排查步骤） + +#### （其他常见问题） + +（原因分析 + 解决方案） +``` + +### 质量要求 + +1. **准确性**：所有步骤描述必须基于 {{AppName}} 的真实功能，不能虚构 +2. **完整性**：入门指南必须覆盖安装后的完整初始化流程 +3. **一致性**：写作风格与 `wordpress.md` 保持一致（简洁、步骤化、用户视角） +4. **锚点规范**：所有二级标题使用语义化英文锚点（格式：`{#anchor-name}`） +5. **截图占位**：需要截图的位置用 `![](./assets/{{appname}}-feature-websoft9.png)` 占位 +6. **中英文混排**：技术名词（如 API、CLI、Docker）保留英文，说明文字使用中文 + +### 参考信息来源 + +在生成内容时，请参考以下来源（按优先级）： + +1. `versioned_docs/version-2.0/apps/{{appname}}.md`（现有骨架文件，如有内容则基于此扩充） +2. `versioned_docs/version-2.0/apps/wordpress.md`（标准参考样例） +3. {{AppName}} 官方文档（基于你的训练知识）