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显示效果的文档浏览体验。 |