511 lines
14 KiB
Markdown
511 lines
14 KiB
Markdown
# 博客样式优化设计
|
||
|
||
## 目标
|
||
|
||
优化博客的整体视觉呈现，确保风格统一、样式美观，并增强 Markdown 内容渲染和代码块高亮显示能力。
|
||
|
||
## 背景
|
||
|
||
当前博客基于 Astro + SolidJS 技术栈，已具备基础样式系统（包括 base.css、typography.css、enhancements.css），并支持暗色模式切换。项目使用 TypeScript 和 PNPM 包管理器，运行于 Node.js 22.21.1 环境。
|
||
|
||
现有样式系统已建立 CSS 变量体系，覆盖颜色主题、圆角、阴影、过渡动画等设计规范，但在 Markdown 渲染和代码高亮方面存在提升空间。
|
||
|
||
## 核心需求
|
||
|
||
### 风格统一性
|
||
|
||
确保整个站点在视觉呈现上保持一致的设计语言：
|
||
|
||
- **色彩体系统一**：所有组件遵循统一的 CSS 变量定义，包括亮色和暗色两套主题配色
|
||
- **间距规范一致**：页面布局、组件内边距、外边距采用统一的间距标准
|
||
- **字体层级清晰**：建立明确的字体大小、行高、字重等级体系
|
||
- **交互反馈统一**：hover、focus、active 等状态的视觉反馈保持一致性
|
||
|
||
### Markdown 渲染优化
|
||
|
||
提升 Markdown 内容的可读性和视觉表现：
|
||
|
||
- **标题层级视觉区分**：h1-h6 各级标题具有明显的视觉差异，便于内容层级识别
|
||
- **段落排版优化**：合理的行高、段落间距，提升长文阅读体验
|
||
- **列表样式美化**：有序列表和无序列表具有清晰的视觉标识
|
||
- **引用块样式增强**：blockquote 具有独特的视觉设计，突出引用内容
|
||
- **链接交互优化**：链接具有醒目但不突兀的视觉效果和悬停动画
|
||
- **图片展示优化**：图片具有适当的边框、圆角、阴影效果，支持放大效果
|
||
- **分隔线美化**：hr 标签具有渐变或装饰性样式
|
||
- **表格样式优化**：表格具有清晰的边框、斑马纹或悬停高亮效果
|
||
|
||
### 代码块高亮
|
||
|
||
实现专业的代码展示能力：
|
||
|
||
- **语法高亮引擎选型**：选择合适的语法高亮方案（Shiki 或 Prism），支持多种编程语言
|
||
- **主题适配**：代码高亮主题需适配亮色和暗色两种模式，确保视觉和谐
|
||
- **代码块装饰**：代码块具有语言标识、行号显示、复制按钮等增强功能
|
||
- **行内代码区分**：行内 `code` 标签与代码块在视觉上有明确区分
|
||
- **代码块容器样式**：代码块具有边框、圆角、阴影、背景色等装饰效果
|
||
- **横向滚动优化**：长代码行支持横向滚动，滚动条样式与整体风格匹配
|
||
|
||
## 设计方案
|
||
|
||
### 样式系统强化
|
||
|
||
#### CSS 变量体系扩展
|
||
|
||
在现有 CSS 变量基础上，补充完善以下变量定义：
|
||
|
||
**代码相关变量**
|
||
- 行内代码背景色、文字色、边框色
|
||
- 代码块背景色（需区分亮色和暗色模式）
|
||
- 代码块边框色
|
||
- 代码行号颜色
|
||
- 代码高亮行背景色
|
||
|
||
**Markdown 元素专用变量**
|
||
- 引用块左侧装饰色
|
||
- 引用块背景色
|
||
- 表格边框色
|
||
- 表格斑马纹背景色
|
||
- 链接装饰线颜色
|
||
|
||
**间距规范变量**
|
||
- 文章内容最大宽度
|
||
- 标题上下边距
|
||
- 段落间距
|
||
- 列表项间距
|
||
|
||
#### 排版增强策略
|
||
|
||
**中英文混排优化**
|
||
- 设置适合中文的行高（1.8-2.0）
|
||
- 字体栈优先选择系统优化字体
|
||
- 字符间距微调，提升可读性
|
||
|
||
**响应式排版**
|
||
- 大屏设备：标准字号（17px）
|
||
- 平板设备：适中字号（16px）
|
||
- 移动设备：缩小字号（15px），调整行高和间距
|
||
|
||
### Markdown 渲染方案
|
||
|
||
#### Astro Markdown 配置
|
||
|
||
利用 Astro 内置的 Markdown 处理能力，通过配置优化渲染输出：
|
||
|
||
**配置项规划**
|
||
- 启用 GitHub Flavored Markdown（GFM）扩展，支持表格、任务列表等
|
||
- 配置自动链接识别
|
||
- 启用智能标点符号转换
|
||
- 配置标题自动生成 ID，便于锚点跳转
|
||
|
||
**插件集成考量**
|
||
- 评估是否需要引入 remark 或 rehype 插件增强处理能力
|
||
- 考虑添加目录生成插件
|
||
- 评估是否需要图片懒加载或优化插件
|
||
|
||
#### 自定义样式映射
|
||
|
||
针对 Markdown 渲染后的 HTML 结构，编写精准的 CSS 选择器：
|
||
|
||
**文章容器作用域**
|
||
- 所有 Markdown 样式限定在 `article` 或 `.post-content` 作用域内
|
||
- 避免全局样式污染
|
||
|
||
**元素样式定义清单**
|
||
- 标题：h1-h6 的字号、字重、颜色、间距、装饰效果
|
||
- 段落：行高、间距、文字颜色
|
||
- 链接：颜色、下划线样式、悬停效果、过渡动画
|
||
- 列表：标记样式、缩进、间距
|
||
- 引用块：边框、背景、左侧装饰、引号装饰
|
||
- 图片：边框、圆角、阴影、悬停效果
|
||
- 表格：边框、表头样式、斑马纹、悬停高亮
|
||
- 分隔线：渐变效果或装饰性样式
|
||
- 行内代码：背景、边框、颜色、字体
|
||
|
||
### 代码高亮方案
|
||
|
||
#### Shiki 语法高亮集成
|
||
|
||
选择 Shiki 作为代码高亮引擎，原因如下：
|
||
- Astro 官方推荐，集成简单
|
||
- 基于 VS Code 主题引擎，主题丰富且美观
|
||
- 支持服务端渲染，无需客户端 JavaScript
|
||
- 支持多语言和自定义主题
|
||
|
||
#### 主题配置策略
|
||
|
||
**亮色模式主题**
|
||
- 选择柔和、对比度适中的主题（如 GitHub Light、One Light）
|
||
- 背景色需与整体页面风格协调
|
||
|
||
**暗色模式主题**
|
||
- 选择护眼、对比度适中的暗色主题（如 One Dark Pro、Night Owl）
|
||
- 背景色需与暗色模式整体风格匹配
|
||
|
||
**主题切换机制**
|
||
- 通过 CSS 变量或 data-theme 属性实现主题动态切换
|
||
- 确保切换过程平滑，无闪烁
|
||
|
||
#### 代码块增强功能
|
||
|
||
**语言标识显示**
|
||
- 在代码块顶部或角落显示语言标签
|
||
- 标签样式需与整体风格一致
|
||
|
||
**复制功能**
|
||
- 在代码块区域提供复制按钮
|
||
- 点击后复制代码内容到剪贴板
|
||
- 提供复制成功的视觉反馈
|
||
|
||
**行号显示（可选）**
|
||
- 评估是否需要显示行号
|
||
- 行号样式不干扰代码阅读
|
||
|
||
**代码块容器装饰**
|
||
- 边框样式：细边框或无边框，颜色与主题协调
|
||
- 圆角效果：使用统一的圆角变量（如 var(--radius-lg)）
|
||
- 阴影效果：适度阴影增强层次感（如 var(--shadow-md)）
|
||
- 左侧装饰线：渐变色装饰线增强视觉效果
|
||
|
||
### 样式文件组织
|
||
|
||
#### 文件结构规划
|
||
|
||
当前样式文件结构保持不变，在现有基础上增强：
|
||
|
||
**base.css**
|
||
- 补充代码高亮相关 CSS 变量
|
||
- 补充 Markdown 渲染相关变量
|
||
|
||
**typography.css**
|
||
- 优化现有文章排版样式
|
||
- 补充缺失的 Markdown 元素样式
|
||
- 确保所有样式作用域限定在 article 内
|
||
|
||
**enhancements.css**
|
||
- 添加代码块复制按钮样式
|
||
- 添加语言标识样式
|
||
- 优化表格、引用块等增强效果
|
||
|
||
**代码高亮主题（新增）**
|
||
- 考虑是否需要单独的代码主题样式文件
|
||
- 如果使用 Shiki，可能无需额外 CSS 文件
|
||
|
||
#### 样式优先级与覆盖策略
|
||
|
||
**导入顺序**
|
||
- reset.css → typography.css → enhancements.css
|
||
- 确保增强样式可以覆盖基础样式
|
||
|
||
**选择器特异性控制**
|
||
- 避免使用过高权重的选择器
|
||
- 优先使用类选择器和属性选择器
|
||
- 必要时使用作用域限定
|
||
|
||
### 响应式设计
|
||
|
||
#### 断点规划
|
||
|
||
遵循移动优先原则，定义以下断点：
|
||
|
||
- 小屏移动设备：<= 480px
|
||
- 大屏移动设备：481px - 768px
|
||
- 平板设备：769px - 1024px
|
||
- 桌面设备：>= 1025px
|
||
|
||
#### 各断点样式调整策略
|
||
|
||
**移动设备（<= 768px）**
|
||
- 减小标题字号
|
||
- 增加段落行高，便于触摸阅读
|
||
- 代码块字号适当缩小
|
||
- 表格横向滚动处理
|
||
- 图片宽度 100%
|
||
|
||
**平板设备（769px - 1024px）**
|
||
- 标题字号适中
|
||
- 代码块保持可读性
|
||
- 表格可正常展示或滚动
|
||
|
||
**桌面设备（>= 1025px）**
|
||
- 最佳阅读体验
|
||
- 充分利用屏幕空间
|
||
- 图片可展示大尺寸
|
||
|
||
### 暗色模式适配
|
||
|
||
#### 主题切换机制
|
||
|
||
依托现有的 `data-theme="dark"` 属性实现主题切换：
|
||
|
||
**颜色变量切换**
|
||
- 所有颜色变量在暗色模式下重新定义
|
||
- 代码块背景色、文字色适配暗色主题
|
||
- 边框、阴影适配暗色环境
|
||
|
||
**代码高亮主题切换**
|
||
- 根据 `data-theme` 属性切换 Shiki 主题
|
||
- 确保暗色模式下代码可读性和对比度
|
||
|
||
**过渡动画**
|
||
- 主题切换过程平滑过渡
|
||
- 避免颜色突变导致的视觉不适
|
||
|
||
#### 暗色模式特殊处理
|
||
|
||
**图片亮度调整**
|
||
- 暗色模式下图片亮度略微降低（opacity: 0.9）
|
||
- 悬停时恢复正常亮度
|
||
|
||
**代码块对比度优化**
|
||
- 暗色模式代码块背景色需与页面背景有一定区分
|
||
- 语法高亮颜色对比度适中，避免刺眼
|
||
|
||
## 技术实现要点
|
||
|
||
### Astro 配置调整
|
||
|
||
在 `astro.config.mjs` 中配置 Markdown 处理选项：
|
||
|
||
**Markdown 配置项**
|
||
- syntaxHighlight：设置为 'shiki'
|
||
- shikiConfig：配置 Shiki 主题和选项
|
||
- remarkPlugins：可选引入 remark 插件
|
||
- rehypePlugins：可选引入 rehype 插件
|
||
|
||
**配置示例结构**
|
||
```
|
||
markdown: {
|
||
syntaxHighlight: 'shiki',
|
||
shikiConfig: {
|
||
theme: 亮色主题,
|
||
themes: { light: 亮色主题, dark: 暗色主题 },
|
||
wrap: 是否换行,
|
||
langs: 支持的语言列表
|
||
},
|
||
remarkPlugins: [...],
|
||
rehypePlugins: [...]
|
||
}
|
||
```
|
||
|
||
### CSS 变量定义规范
|
||
|
||
**命名约定**
|
||
- 使用 kebab-case 命名法
|
||
- 前缀分类：--bg（背景）、--text（文字）、--code（代码）、--border（边框）等
|
||
- 语义化命名，便于理解和维护
|
||
|
||
**亮色与暗色变量对应关系**
|
||
- 每个亮色变量在 `[data-theme="dark"]` 中都有对应定义
|
||
- 变量名保持一致，仅值不同
|
||
|
||
### 组件样式隔离
|
||
|
||
**PostLayout 组件**
|
||
- 确保文章内容区域使用 `.post-content` 类包裹
|
||
- 所有 Markdown 样式限定在此作用域内
|
||
|
||
**全局样式与组件样式协同**
|
||
- 全局样式定义基础规范
|
||
- 组件样式处理特定场景
|
||
|
||
### 性能优化考量
|
||
|
||
**CSS 体积控制**
|
||
- 避免冗余样式定义
|
||
- 使用 CSS 变量减少重复代码
|
||
- 生产环境压缩 CSS
|
||
|
||
**代码高亮性能**
|
||
- Shiki 在构建时高亮，无运行时性能损耗
|
||
- 避免客户端高亮库增加包体积
|
||
|
||
**字体加载优化**
|
||
- 使用系统字体栈，避免额外字体加载
|
||
- 如需自定义字体，采用字体子集化和预加载
|
||
|
||
## 验收标准
|
||
|
||
### 风格统一性检查
|
||
|
||
- 所有页面组件遵循统一的色彩体系
|
||
- 间距、圆角、阴影等设计元素保持一致
|
||
- 亮色和暗色模式切换流畅，无样式错乱
|
||
- 响应式布局在各断点表现正常
|
||
|
||
### Markdown 渲染质量
|
||
|
||
- 标题层级清晰，视觉区分明显
|
||
- 段落排版舒适，行高和间距合理
|
||
- 列表、引用块、表格样式美观
|
||
- 链接具有明确的视觉提示和交互反馈
|
||
- 图片展示效果良好，支持悬停效果
|
||
- 分隔线、行内代码等细节元素样式完善
|
||
|
||
### 代码高亮效果
|
||
|
||
- 支持常见编程语言的语法高亮（JavaScript、TypeScript、Python、Go、CSS、HTML 等）
|
||
- 代码配色与整体主题协调
|
||
- 亮色和暗色模式下代码可读性良好
|
||
- 代码块具有清晰的边界和装饰效果
|
||
- 行内代码与代码块视觉区分明显
|
||
- 复制功能正常工作（如实现）
|
||
|
||
### 可访问性
|
||
|
||
- 颜色对比度符合 WCAG AA 标准
|
||
- 键盘导航支持良好
|
||
- 屏幕阅读器友好
|
||
- 减少动画模式（prefers-reduced-motion）生效
|
||
|
||
### 性能指标
|
||
|
||
- 页面首次渲染时间无明显增加
|
||
- CSS 文件体积控制在合理范围
|
||
- 无不必要的客户端 JavaScript 加载
|
||
- 代码高亮渲染速度快
|
||
|
||
## 潜在风险与应对
|
||
|
||
### 主题切换闪烁
|
||
|
||
**风险描述**
|
||
暗色模式切换时可能出现短暂的白屏或颜色闪烁。
|
||
|
||
**应对策略**
|
||
- 在 HTML 加载初期通过内联脚本读取主题偏好
|
||
- 在 CSS 加载前应用主题属性
|
||
- 使用 localStorage 持久化主题选择
|
||
|
||
### 代码高亮主题适配问题
|
||
|
||
**风险描述**
|
||
选择的 Shiki 主题可能与整体风格不匹配。
|
||
|
||
**应对策略**
|
||
- 预先测试多个主题，选择最协调的方案
|
||
- 必要时自定义 Shiki 主题配色
|
||
- 通过 CSS 变量覆盖部分颜色
|
||
|
||
### 移动端代码块可读性
|
||
|
||
**风险描述**
|
||
移动设备屏幕小，代码块显示可能不佳。
|
||
|
||
**应对策略**
|
||
- 设置合适的最小字号
|
||
- 启用横向滚动，避免代码换行
|
||
- 优化移动端代码块内边距
|
||
|
||
### 长文章性能问题
|
||
|
||
**风险描述**
|
||
包含大量代码块的长文章可能导致渲染性能下降。
|
||
|
||
**应对策略**
|
||
- Shiki 在构建时处理，不影响运行时性能
|
||
- 优化 CSS 选择器性能
|
||
- 避免过度使用复杂动画
|
||
|
||
## 后续优化方向
|
||
|
||
### 交互增强
|
||
|
||
- 代码块行高亮功能
|
||
- 代码差异对比展示
|
||
- 图片点击放大查看（Lightbox）
|
||
- 文章目录自动生成和锚点跳转
|
||
|
||
### 内容增强
|
||
|
||
- 代码注释高亮
|
||
- 公式渲染支持（KaTeX 或 MathJax）
|
||
- 图表渲染支持（Mermaid）
|
||
- 视频嵌入样式优化
|
||
|
||
### 个性化定制
|
||
|
||
- 用户可选代码高亮主题
|
||
- 字号调节功能
|
||
- 阅读进度指示器
|
||
- 打印样式优化
|
||
|
||
### 性能优化
|
||
|
||
- 关键 CSS 内联
|
||
- 非关键样式延迟加载
|
||
- 图片懒加载和响应式图片
|
||
- 字体加载策略优化
|
||
|
||
## 潜在风险与应对
|
||
|
||
### 主题切换闪烁
|
||
|
||
**风险描述**
|
||
暗色模式切换时可能出现短暂的白屏或颜色闪烁。
|
||
|
||
**应对策略**
|
||
- 在 HTML 加载初期通过内联脚本读取主题偏好
|
||
- 在 CSS 加载前应用主题属性
|
||
- 使用 localStorage 持久化主题选择
|
||
|
||
### 代码高亮主题适配问题
|
||
|
||
**风险描述**
|
||
选择的 Shiki 主题可能与整体风格不匹配。
|
||
|
||
**应对策略**
|
||
- 预先测试多个主题，选择最协调的方案
|
||
- 必要时自定义 Shiki 主题配色
|
||
- 通过 CSS 变量覆盖部分颜色
|
||
|
||
### 移动端代码块可读性
|
||
|
||
**风险描述**
|
||
移动设备屏幕小，代码块显示可能不佳。
|
||
|
||
**应对策略**
|
||
- 设置合适的最小字号
|
||
- 启用横向滚动，避免代码换行
|
||
- 优化移动端代码块内边距
|
||
|
||
### 长文章性能问题
|
||
|
||
**风险描述**
|
||
包含大量代码块的长文章可能导致渲染性能下降。
|
||
|
||
**应对策略**
|
||
- Shiki 在构建时处理，不影响运行时性能
|
||
- 优化 CSS 选择器性能
|
||
- 避免过度使用复杂动画
|
||
|
||
## 后续优化方向
|
||
|
||
### 交互增强
|
||
|
||
- 代码块行高亮功能
|
||
- 代码差异对比展示
|
||
- 图片点击放大查看（Lightbox）
|
||
- 文章目录自动生成和锚点跳转
|
||
|
||
### 内容增强
|
||
|
||
- 代码注释高亮
|
||
- 公式渲染支持（KaTeX 或 MathJax）
|
||
- 图表渲染支持（Mermaid）
|
||
- 视频嵌入样式优化
|
||
|
||
### 个性化定制
|
||
|
||
- 用户可选代码高亮主题
|
||
- 字号调节功能
|
||
- 阅读进度指示器
|
||
- 打印样式优化
|
||
|
||
### 性能优化
|
||
|
||
- 关键 CSS 内联
|
||
- 非关键样式延迟加载
|
||
- 图片懒加载和响应式图片
|
||
- 字体加载策略优化
|
||
- 代码高亮渲染速度快
|