博客和周刊使用指南

本文档详细说明如何更新博客文章和周刊，以及如何插入图片、使用Mermaid图表和LaTeX数学公式。

📝 如何更新博客

1. 创建新博客文章

复制模版文件：

cp templates/blog-template.md posts/your-article-name.md

编辑文件头信息（Front Matter）：

---
title: "你的文章标题"
date: 2025-01-15  # 当前日期
tags: ["标签1", "标签2"]  # 相关标签
excerpt: "文章摘要"
---

编写文章内容，参考模版结构
保存文件，Jekyll会自动重新生成网站

2. 文章命名规范

文件名使用英文，用连字符分隔：article-name.md
避免使用空格和特殊字符
文件名要能反映文章主题

3. 标签使用建议

常用标签分类：

技术类：”AI”, “编程”, “工具”, “前端”, “后端”
学习类：”语言学习”, “读书笔记”, “课程”
生活类：”留学”, “旅行”, “思考”, “随笔”
工作类：”职场”, “面试”, “项目”

📰 如何更新周刊

1. 创建新周刊

复制模版文件：
```
cp templates/weekly-template.md weekly/weekly-XXX.md
```
（XXX为期数，如002、003等）

更新文件头信息：

---
title: "第X期 - 周刊标题"
date: 2025-01-15
cover: "../assets/images/weekly/weekly-X-cover.jpg"
excerpt: "本期周刊简介"
---

按照模版结构填写内容

2. 周刊内容建议

保持规律：建议每周或每两周更新一次
内容丰富：包含学习、工具、文章、思考等多个维度
图文并茂：适当添加图片和图表
个人化：记录真实的学习和生活体验

🖼️ 如何插入图片

1. 图片存储结构

assets/
└── images/
    ├── posts/          # 博客文章图片
    │   ├── article-1/
    │   └── article-2/
    ├── weekly/         # 周刊图片
    │   ├── weekly-001/
    │   └── weekly-002/
    ├── tools/          # 工具截图
    ├── books/          # 书籍封面
    └── general/        # 通用图片

2. 图片插入语法

基本语法：

![图片描述](../assets/images/folder/image-name.jpg)

带说明文字：

![图片描述](../assets/images/folder/image-name.jpg)
*图片说明文字*

指定图片大小：

<img src="../assets/images/folder/image-name.jpg" alt="图片描述" width="600">

3. 图片优化建议

格式选择：
- 照片使用 JPG 格式
- 图标、截图使用 PNG 格式
- 简单图形可使用 SVG 格式
尺寸控制：
- 博客文章图片：宽度不超过 800px
- 周刊封面图片：800x400px（2:1比例）
- 工具截图：适当压缩，保持清晰度
文件大小：单张图片不超过 500KB

4. 图片处理工具推荐

压缩工具：TinyPNG、ImageOptim
编辑工具：Photoshop、GIMP、Canva
截图工具：CleanShot X、Snagit

📊 Mermaid 图表支持

1. 配置 Mermaid

在 _config.yml 中添加：

markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighter: rouge

在主布局文件中添加 Mermaid 脚本：

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>
  mermaid.initialize({startOnLoad:true});
</script>

2. Mermaid 语法示例

流程图：

graph TD
    A[开始] --> B{判断条件}
    B -->|是| C[执行操作1]
    B -->|否| D[执行操作2]
    C --> E[结束]
    D --> E

时序图：

sequenceDiagram
    participant A as 用户
    participant B as 系统
    A->>B: 发送请求
    B-->>A: 返回响应

饼图：

pie title 时间分配
    "工作" : 40
    "学习" : 30
    "休息" : 20
    "其他" : 10

🧮 LaTeX 数学公式支持

1. 配置 MathJax

在主布局文件中添加 MathJax 脚本：

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script>
  MathJax = {
    tex: {
      inlineMath: [['$', '$'], ['\\(', '\\)']],
      displayMath: [['$$', '$$'], ['\\[', '\\]']]
    }
  };
</script>

2. LaTeX 语法示例

行内公式：

这是行内公式：$E = mc^2$

块级公式：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

复杂公式：

$$
\begin{align}
f(x) &= ax^2 + bx + c \\
g(x) &= \frac{d}{dx}f(x) = 2ax + b
\end{align}
$$

🚀 发布流程

1. 本地预览

# 启动本地服务器
bundle exec jekyll serve

# 访问 http://localhost:4000 预览

2. 提交更改

# 添加文件
git add .

# 提交更改
git commit -m "添加新文章/周刊：标题"

# 推送到远程仓库
git push origin main

3. 自动部署

GitHub Actions 会自动构建和部署网站到 GitHub Pages。

📋 检查清单

发布前检查

文章标题和日期正确
标签和摘要已填写
图片路径正确，图片已优化
Mermaid 图表和 LaTeX 公式渲染正常
本地预览无误
拼写和语法检查

定期维护

清理未使用的图片文件
更新过时的链接
检查网站加载速度
备份重要内容

🔧 故障排除

常见问题

图片不显示：检查路径是否正确，确保图片文件存在
Mermaid 不渲染：确认脚本已正确加载，语法无误
LaTeX 不显示：检查 MathJax 配置，确认公式语法正确
Jekyll 构建失败：查看错误日志，通常是 YAML 格式或 Markdown 语法问题

获取帮助

Jekyll 官方文档：https://jekyllrb.com/docs/
Mermaid 文档：https://mermaid-js.github.io/mermaid/
MathJax 文档：https://docs.mathjax.org/

最后更新：2025年1月15日