159 lines
4.2 KiB
Markdown
159 lines
4.2 KiB
Markdown
|
# OneApp 文档站点配置说明
|
|||
|
|
|
|||
|
|
## 已修复的主要问题
|
|||
|
|
|
|||
|
|
### 1. Repository 信息移除 ✅
|
|||
|
|
- 从 `mkdocs.yml` 中移除了GitHub仓库相关配置
|
|||
|
|
- 移除了Google Analytics和社交链接配置
|
|||
|
|
- 保持了本地化的纯净配置
|
|||
|
|
|
|||
|
|
### 2. Markdown语法支持增强 ✅
|
|||
|
|
新增的扩展支持：
|
|||
|
|
- `nl2br`: 支持单换行转换为`<br>`标签
|
|||
|
|
- `sane_lists`: 更智能的列表解析
|
|||
|
|
- `smarty`: 智能标点符号转换
|
|||
|
|
- `toc`: 改进的目录生成，支持permalink
|
|||
|
|
|
|||
|
|
### 3. Mermaid图表渲染优化 ✅
|
|||
|
|
- 更新到Mermaid 10.9.1最新版本
|
|||
|
|
- 重写了JavaScript初始化逻辑
|
|||
|
|
- 添加了主题切换支持（明暗模式）
|
|||
|
|
- 改进了错误处理和调试信息
|
|||
|
|
- 优化了图表样式和布局
|
|||
|
|
|
|||
|
|
### 4. GitHub风格样式优化 ✅
|
|||
|
|
- **表格样式**: 采用GitHub风格的表格渲染，包括边框、背景色交替
|
|||
|
|
- **代码块样式**: 优化了代码高亮和背景色
|
|||
|
|
- **引用块样式**: GitHub风格的引用块，带有左侧彩色边框
|
|||
|
|
- **标题样式**: 改进的标题层次和下划线
|
|||
|
|
- **响应式设计**: 移动端适配优化
|
|||
|
|
|
|||
|
|
### 5. 静态部署优化 ✅
|
|||
|
|
- 保持了 `use_directory_urls: false` 配置
|
|||
|
|
- 确保生成的是`.html`链接格式，适合直接文件访问
|
|||
|
|
|
|||
|
|
## 与GitHub显示效果的对比
|
|||
|
|
|
|||
|
|
### GitHub的优势
|
|||
|
|
1. **原生Markdown解析**: GitHub使用自己的Markdown解析器，对某些语法支持更好
|
|||
|
|
2. **Mermaid集成**: GitHub Pages对Mermaid有原生支持
|
|||
|
|
3. **字体渲染**: GitHub使用system fonts，在不同平台有更好的显示效果
|
|||
|
|
|
|||
|
|
### MkDocs优势
|
|||
|
|
1. **导航结构**: 提供了完整的左侧导航树
|
|||
|
|
2. **搜索功能**: 内置全文搜索
|
|||
|
|
3. **主题切换**: 支持明暗模式切换
|
|||
|
|
4. **离线访问**: 生成的静态文件可以完全离线使用
|
|||
|
|
5. **移动端体验**: 响应式设计，移动端体验更好
|
|||
|
|
|
|||
|
|
## 当前配置特点
|
|||
|
|
|
|||
|
|
### mkdocs.yml 核心配置
|
|||
|
|
```yaml
|
|||
|
|
# 基础信息（无GitHub仓库信息）
|
|||
|
|
site_name: OneApp 架构设计文档
|
|||
|
|
site_description: OneApp Flutter应用完整技术架构设计和模块说明
|
|||
|
|
site_author: OneApp Team
|
|||
|
|
|
|||
|
|
# 静态部署优化
|
|||
|
|
use_directory_urls: false
|
|||
|
|
|
|||
|
|
# Material主题配置
|
|||
|
|
theme:
|
|||
|
|
name: material
|
|||
|
|
language: zh
|
|||
|
|
palette:
|
|||
|
|
- scheme: default # 浅色模式
|
|||
|
|
- scheme: slate # 深色模式
|
|||
|
|
|
|||
|
|
# 增强的Markdown扩展
|
|||
|
|
markdown_extensions:
|
|||
|
|
- pymdownx.superfences:
|
|||
|
|
custom_fences:
|
|||
|
|
- name: mermaid
|
|||
|
|
class: mermaid
|
|||
|
|
- tables
|
|||
|
|
- toc:
|
|||
|
|
permalink: true
|
|||
|
|
- nl2br
|
|||
|
|
- sane_lists
|
|||
|
|
# ... 更多扩展
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 自定义样式特点
|
|||
|
|
- GitHub风格的表格和代码块
|
|||
|
|
- 优化的Mermaid图表显示
|
|||
|
|
- 响应式设计
|
|||
|
|
- 深色模式支持
|
|||
|
|
- 打印样式优化
|
|||
|
|
|
|||
|
|
## 使用说明
|
|||
|
|
|
|||
|
|
### 构建命令
|
|||
|
|
```bash
|
|||
|
|
# 清理构建
|
|||
|
|
python -m mkdocs build --clean
|
|||
|
|
|
|||
|
|
# 开发服务器
|
|||
|
|
python -m mkdocs serve
|
|||
|
|
|
|||
|
|
# 清理临时文件
|
|||
|
|
Remove-Item site -Recurse -Force
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 目录结构
|
|||
|
|
```
|
|||
|
|
oneapp_docs/
|
|||
|
|
├── mkdocs.yml # 主配置文件
|
|||
|
|
├── docs/ # 文档源文件目录
|
|||
|
|
├── site/ # 生成的静态站点
|
|||
|
|
├── assets/ # 自定义资源
|
|||
|
|
│ ├── css/extra.css # 自定义样式
|
|||
|
|
│ └── js/mermaid.js # Mermaid配置
|
|||
|
|
└── README.md # 项目说明
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 潜在的进一步改进
|
|||
|
|
|
|||
|
|
### 1. Mermaid图表
|
|||
|
|
如果发现某些复杂图表渲染有问题，可以考虑：
|
|||
|
|
- 分割复杂图表为多个简单图表
|
|||
|
|
- 使用图片替代复杂的Mermaid图表
|
|||
|
|
- 调整图表的配置参数
|
|||
|
|
|
|||
|
|
### 2. 表格显示
|
|||
|
|
对于超宽表格，可以考虑：
|
|||
|
|
- 使用横向滚动
|
|||
|
|
- 分割大表格
|
|||
|
|
- 使用卡片式布局替代表格
|
|||
|
|
|
|||
|
|
### 3. 代码高亮
|
|||
|
|
可以添加更多编程语言的语法高亮支持：
|
|||
|
|
```yaml
|
|||
|
|
markdown_extensions:
|
|||
|
|
- pymdownx.highlight:
|
|||
|
|
use_pygments: true
|
|||
|
|
pygments_lang_class: true
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4. 搜索优化
|
|||
|
|
可以配置更高级的搜索功能：
|
|||
|
|
```yaml
|
|||
|
|
plugins:
|
|||
|
|
- search:
|
|||
|
|
lang:
|
|||
|
|
- zh
|
|||
|
|
- en
|
|||
|
|
separator: '[\s\-\.]+'
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 总结
|
|||
|
|
|
|||
|
|
现在的配置已经实现了：
|
|||
|
|
- ✅ 移除不必要的repository信息
|
|||
|
|
- ✅ 增强Markdown语法支持
|
|||
|
|
- ✅ 优化Mermaid图表渲染
|
|||
|
|
- ✅ GitHub风格的样式设计
|
|||
|
|
- ✅ 静态文件部署优化
|
|||
|
|
|
|||
|
|
生成的静态站点可以直接在任何Web服务器或本地浏览器中使用，提供了接近GitHub显示效果的文档浏览体验。
|