CyberMind-FR
ccfb58124c
Add complete French (fr) and Chinese (zh) translations for all documentation: - Root files: README, CHANGELOG, SECURITY, BETA-RELEASE - docs/: All 16 core documentation files - DOCS/: All 19 deep-dive documents including embedded/ and archive/ - package/secubox/: All 123+ package READMEs - Misc: secubox-tools/, scripts/, EXAMPLES/, config-backups/, streamlit-apps/ Total: 346 translation files created Each file includes language switcher links for easy navigation between English, French, and Chinese versions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
294 lines
5.6 KiB
Markdown
294 lines
5.6 KiB
Markdown
# 文档发布脚本
|
||
|
||
[English](README.md) | [Francais](README.fr.md) | 中文
|
||
|
||
**版本：** 1.0.0
|
||
**最后更新：** 2025-12-28
|
||
**用途：** SecuBox 文档的自动发布脚本
|
||
|
||
---
|
||
|
||
## 可用脚本
|
||
|
||
### 1. setup-wiki.sh
|
||
**用途：** 将 DOCS/ 同步到 GitHub Wiki
|
||
|
||
**使用方法：**
|
||
```bash
|
||
./scripts/setup-wiki.sh
|
||
```
|
||
|
||
**执行操作：**
|
||
- 克隆 wiki 仓库
|
||
- 创建带导航的首页
|
||
- 创建侧边栏
|
||
- 复制所有文档文件
|
||
- 修复内部链接为 wiki 格式
|
||
- 提交并推送到 wiki
|
||
|
||
**前提条件：**
|
||
- 已安装 Git
|
||
- 在 GitHub 仓库设置中启用 Wiki
|
||
- 拥有 GitHub 的 SSH 访问权限
|
||
|
||
**耗时：** 约 2 分钟
|
||
|
||
---
|
||
|
||
### 2. setup-github-pages.sh
|
||
**用途：** 使用 MkDocs Material 主题创建 GitHub Pages 站点
|
||
|
||
**使用方法：**
|
||
```bash
|
||
./scripts/setup-github-pages.sh
|
||
```
|
||
|
||
**执行操作：**
|
||
- 如需要则安装 MkDocs
|
||
- 创建 mkdocs.yml 配置
|
||
- 生成 docs/ 目录结构
|
||
- 创建精美的首页
|
||
- 复制所有文档文件
|
||
- 修复内部链接为 web 格式
|
||
- 构建预览站点
|
||
|
||
**前提条件：**
|
||
- 已安装 Python 3.x
|
||
- 已安装 pip3
|
||
- 约 100MB 磁盘空间
|
||
|
||
**耗时：** 约 10 分钟（首次）
|
||
|
||
---
|
||
|
||
## 选择哪个脚本？
|
||
|
||
### 使用 `setup-wiki.sh` 如果：
|
||
- 您想要快速设置（2 分钟）
|
||
- 仅内部文档
|
||
- 简单导航即可满足需求
|
||
- 不需要主题定制
|
||
|
||
### 使用 `setup-github-pages.sh` 如果：
|
||
- 您想要专业外观
|
||
- 公开文档
|
||
- 需要自定义域名支持
|
||
- 需要深色模式支持
|
||
- 需要更好的移动端体验
|
||
|
||
**我们的建议：** 使用 GitHub Pages 作为 SecuBox 的专业文档。
|
||
|
||
完整设置说明请参见 [WIKI-SETUP-GUIDE.md](../WIKI-SETUP-GUIDE.md)。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 选项 1：GitHub Wiki
|
||
|
||
```bash
|
||
# 1. 在 GitHub 设置中启用 Wiki
|
||
# 2. 运行脚本
|
||
./scripts/setup-wiki.sh
|
||
|
||
# 3. 访问：
|
||
# https://github.com/CyberMind-FR/secubox-openwrt/wiki
|
||
```
|
||
|
||
### 选项 2：GitHub Pages（推荐）
|
||
|
||
```bash
|
||
# 1. 安装依赖
|
||
sudo apt-get install python3 python3-pip
|
||
pip3 install mkdocs mkdocs-material pymdown-extensions
|
||
|
||
# 2. 运行脚本
|
||
./scripts/setup-github-pages.sh
|
||
|
||
# 3. 本地测试
|
||
mkdocs serve
|
||
|
||
# 4. 提交并推送
|
||
git add mkdocs.yml docs/
|
||
git commit -m "Add GitHub Pages documentation"
|
||
git push
|
||
|
||
# 5. 在 GitHub 设置中启用
|
||
# Settings → Pages → Source: master, Folder: /docs
|
||
|
||
# 6. 访问：
|
||
# https://gkerma.github.io/secubox-openwrt/
|
||
```
|
||
|
||
---
|
||
|
||
## 脚本功能
|
||
|
||
### setup-wiki.sh
|
||
|
||
| 功能 | 状态 |
|
||
|---------|--------|
|
||
| 自动克隆 wiki 仓库 | 已完成 |
|
||
| 创建首页 | 已完成 |
|
||
| 创建侧边栏导航 | 已完成 |
|
||
| 复制所有文档 | 已完成 |
|
||
| 修复内部链接 | 已完成 |
|
||
| 存档整理 | 已完成 |
|
||
| 自动提交和推送 | 已完成 |
|
||
| 错误处理 | 已完成 |
|
||
|
||
### setup-github-pages.sh
|
||
|
||
| 功能 | 状态 |
|
||
|---------|--------|
|
||
| 依赖检查 | 已完成 |
|
||
| 自动安装 MkDocs | 已完成 |
|
||
| Material 主题 | 已完成 |
|
||
| 深色/浅色模式 | 已完成 |
|
||
| 搜索功能 | 已完成 |
|
||
| Mermaid 图表 | 已完成 |
|
||
| 移动端响应式 | 已完成 |
|
||
| 自定义 CSS | 已完成 |
|
||
| 存档整理 | 已完成 |
|
||
| 构建预览 | 已完成 |
|
||
| 链接修复 | 已完成 |
|
||
| 错误处理 | 已完成 |
|
||
|
||
---
|
||
|
||
## 更新文档
|
||
|
||
### GitHub Wiki
|
||
|
||
直接重新运行脚本：
|
||
```bash
|
||
./scripts/setup-wiki.sh
|
||
```
|
||
|
||
DOCS/ 中的所有更改将同步到 wiki。
|
||
|
||
### GitHub Pages
|
||
|
||
```bash
|
||
# 选项 1：完全重新同步
|
||
./scripts/setup-github-pages.sh
|
||
|
||
# 选项 2：手动更新
|
||
cp DOCS/CHANGED-FILE.md docs/changed-file.md
|
||
mkdocs build
|
||
git add docs/
|
||
git commit -m "Update docs"
|
||
git push
|
||
```
|
||
|
||
---
|
||
|
||
## 故障排除
|
||
|
||
### setup-wiki.sh
|
||
|
||
**错误："Wiki repository doesn't exist"**
|
||
- 首先在 GitHub 仓库设置中启用 Wiki
|
||
- URL：https://github.com/CyberMind-FR/secubox-openwrt/settings
|
||
|
||
**错误："Permission denied"**
|
||
- 确保已为 GitHub 配置 SSH 密钥
|
||
- 测试：`ssh -T git@github.com`
|
||
|
||
### setup-github-pages.sh
|
||
|
||
**错误："mkdocs: command not found"**
|
||
- 安装 MkDocs：`pip3 install mkdocs mkdocs-material`
|
||
- 或重新运行脚本（自动安装）
|
||
|
||
**错误："No module named 'material'"**
|
||
- 安装主题：`pip3 install mkdocs-material`
|
||
|
||
**错误："Build failed"**
|
||
- 检查 mkdocs.yml 语法
|
||
- 测试：`mkdocs build --strict`
|
||
- 检查 Python 版本：`python3 --version`（需要 3.6+）
|
||
|
||
---
|
||
|
||
## 比较
|
||
|
||
| 方面 | Wiki 脚本 | Pages 脚本 |
|
||
|--------|-------------|--------------|
|
||
| **设置时间** | 2 分钟 | 10 分钟 |
|
||
| **依赖** | 仅 Git | Python、MkDocs |
|
||
| **结果** | 基础 wiki | 专业站点 |
|
||
| **主题** | 默认 | Material Design |
|
||
| **功能** | 基础 | 高级 |
|
||
| **移动端** | 一般 | 优秀 |
|
||
| **SEO** | 基础 | 良好 |
|
||
| **自定义域名** | 否 | 是 |
|
||
|
||
---
|
||
|
||
## 自定义
|
||
|
||
### Wiki
|
||
|
||
编辑 wiki 仓库中生成的文件：
|
||
```bash
|
||
git clone https://github.com/CyberMind-FR/secubox-openwrt.wiki.git
|
||
cd secubox-openwrt.wiki
|
||
# 编辑 _Sidebar.md、Home.md 等
|
||
git commit -am "Customize wiki"
|
||
git push
|
||
```
|
||
|
||
### GitHub Pages
|
||
|
||
编辑 mkdocs.yml 和 docs/stylesheets/extra.css：
|
||
```bash
|
||
# 更改主题颜色
|
||
vim mkdocs.yml
|
||
|
||
# 更改自定义样式
|
||
vim docs/stylesheets/extra.css
|
||
|
||
# 重新构建
|
||
mkdocs build
|
||
```
|
||
|
||
---
|
||
|
||
## 支持
|
||
|
||
**脚本问题：**
|
||
- 检查脚本输出中的错误消息
|
||
- 验证已安装依赖
|
||
- 确保 DOCS/ 目录存在
|
||
|
||
**需要帮助：**
|
||
- 参见：[WIKI-SETUP-GUIDE.md](../WIKI-SETUP-GUIDE.md)
|
||
- 创建 GitHub issue
|
||
- 邮箱：support@cybermind.fr
|
||
|
||
---
|
||
|
||
## 脚本维护
|
||
|
||
**更新脚本：**
|
||
```bash
|
||
# 编辑脚本
|
||
vim scripts/setup-wiki.sh
|
||
vim scripts/setup-github-pages.sh
|
||
|
||
# 测试更改
|
||
./scripts/setup-wiki.sh --dry-run # （如果已实现）
|
||
|
||
# 提交
|
||
git add scripts/
|
||
git commit -m "Update wiki setup scripts"
|
||
git push
|
||
```
|
||
|
||
---
|
||
|
||
**最后更新：** 2025-12-28
|
||
**维护者：** CyberMind.fr
|
||
**许可证：** Apache-2.0
|