Pelican 静态博客网站日常内容更新指南
本文档面向内容创作者，提供使用 Typora 编辑器在本地编写博客文章，并自动同步到服务器的完整工作流程。
1. 工作流程概览
┌─────────────────┐ ┌─────────────┐ ┌─────────────┐
│ 本地 Windows │ │ Gitee │ │ 服务器 │
│ │ │ │ │ │
│ 1. Typora 编辑 │ ───▶ │ 2. Git 推送 │ ───▶ │ 3. 自动构建 │
│ 2. PicGo 上传 │ │ 3. Webhook │ │ 4. Nginx 服务│
│ 3. Git 提交 │ │ 触发 │ │ │
└─────────────────┘ └─────────────┘ └─────────────┘
2. 本地环境准备
2.1 安装必需软件
Git for Windows
- 下载地址：https://git-scm.com/download/win
- 安装时选择"Use Git from Git Bash only"或"Git from the command line"
Typora
- 下载地址：https://typoraio.cn/
- 推荐使用最新版本
PicGo（图片上传工具）
- 下载地址：https://github.com/Molunerfinn/PicGo
- 用于将图片自动上传到图床
2.2 安装 PicGo 插件
启动 PicGo 后，安装以下插件：
1. 打开 PicGo 设置
2. 进入 插件设置
3. 搜索并安装：
- picgo-plugin-gitee-uploader（上传到 Gitee 图床）
2.3 配置 PicGo
Gitee 图床配置：
{
"repo": "hoeking/picgo-images",
"branch": "master",
"token": "your-gitee-token",
"path": "blog/{year}/{month}",
"customUrl": "https://gitee.com/hoeking/picgo-images/raw/master"
}
获取 Gitee Token：
- 登录 Gitee → 右上角头像 → 设置
- 左侧菜单 → 私人令牌
- 生成新令牌，勾选
projects权限 - 保存令牌
2.4 配置 Typora
打开设置 → 图像：
□ 启用本地图片
☑ 上传图片
☑ 对本地图片应用上述规则
☑ 对网络图片应用上述规则
上传服务选择：PicGo (picgo)
PicGo 路径：C:\Users\你的用户名\AppData\Roaming\picgo\picgo.exe
3. 项目目录结构
3.1 推荐的目录结构
my_blog/
├── content/ # 内容目录
│ ├── articles/ # 博客文章
│ │ ├── tech/ # 技术文章
│ │ │ ├── python-guide.md
│ │ │ └── docker-intro.md
│ │ ├── life/ # 生活随笔
│ │ │ └── travel-notes.md
│ │ └── uncategorized/ # 未分类文章
│ │ └── hello-world.md
│ ├── pages/ # 静态页面
│ │ ├── about.md # 关于页面
│ │ └── contact.md # 联系页面
│ ├── images/ # 本地图片（手动管理）
│ │ └── featured/ # 封面图片
│ ├── downloads/ # 下载附件（.zip/.rar/.7z）
│ │ ├── source-code/ # - 源码
│ │ └── templates/ # - 模板文件
│ ├── media/ # 音视频（<10MB）
│ │ ├── videos/ # - 视频
│ │ └── audios/ # - 音频
│ └── drafts/ # 草稿（不发布）
│ └── draft-post.md
├── output/ # 生成的静态文件（gitignore）
├── pelicanconf.py # 开发配置
├── publishconf.py # 生产配置
├── tasks.py # Pelican 任务文件
├── .gitignore # Git 忽略文件
└── README.md # 项目说明
3.2 .gitignore 文件
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
env/
venv/
.venv/
*.egg-info/
# Pelican
output/
cache/
*.cache
# IDE
.vscode/
.idea/
*.swp
*.swo
# OS
.DS_Store
Thumbs.db
# 日志
*.log
4. 文章编写规范
4.1 文章文件命名
推荐使用有意义的英文或拼音文件名：
# 推荐
python-advanced-tutorial.md
docker-basics.md
2024-01-15-my-travel.md
# 不推荐
post1.md
new-article.md
测试文章.md
4.2 文章头部元数据
Pelican 使用文章头部的元数据进行分类和组织：
---
Title: Python 高级教程：装饰器详解
Date: 2024-01-15 10:30
Modified: 2024-01-16 14:20
Category: 技术
Tags: Python, 装饰器, 进阶
Slug: python-decorator-tutorial
Author: Chen Li
Summary: 本文详细介绍 Python 装饰器的原理和使用方法
Status: published
---
文章正文从这里开始...
4.3 元数据字段说明
| 字段 | 必填 | 说明 | 示例 |
|---|---|---|---|
Title |
✅ | 文章标题 | Title: 我的文章 |
Date |
✅ | 发布日期 | Date: 2024-01-15 10:30 |
Category |
❌ | 分类 | Category: 技术 |
Tags |
❌ | 标签（逗号分隔） | Tags: Python, 教程 |
Slug |
❌ | URL 别名 | Slug: my-post |
Author |
❌ | 作者 | Author: 张三 |
Summary |
❌ | 文章摘要 | Summary: 简介 |
Status |
❌ | 状态 | Status: draft |
Modified |
❌ | 修改日期 | Modified: 2024-01-16 |
4.4 Status 状态值
| 状态值 | 说明 | 是否发布 |
|---|---|---|
published |
已发布（默认） | ✅ 发布 |
draft |
草稿 | ❌ 不发布 |
hidden |
隐藏 | ❌ 不发布 |
重要：只有 status: published 的文章才会被发布。
5. 写作最佳实践
5.1 使用 Typora 的技巧
快捷键：
Ctrl + B：加粗Ctrl + I：斜体Ctrl + K：插入链接Ctrl + Shift + K：插入代码块Ctrl + 1-6：标题级别Ctrl + /：切换源码模式
插入图片：
- 直接拖拽图片到编辑器
- Typora 会自动调用 PicGo 上传
- 图片 URL 自动替换为图床地址
代码高亮：
```python
def hello():
print("Hello, World!")
**数学公式**：
```markdown
行内公式：$E = mc^2$
块级公式：
$$
\sum_{i=1}^n x_i = x_1 + x_2 + \cdots + x_n
$$
5.2 Markdown 语法示例
标题：
# 一级标题
## 二级标题
### 三级标题
列表：
- 无序列表项 1
- 无序列表项 2
- 嵌套项
1. 有序列表项 1
2. 有序列表项 2
引用：
> 这是一段引用文字
> 可以多行
表格：
| 列1 | 列2 | 列3 |
|------|------|------|
| 内容 | 内容 | 内容 |
分割线：
---
5.3 文章内容组织
推荐的文章结构：
---
Title: 文章标题
Date: 2024-01-15
Category: 分类
Tags: 标签
---
## 前言
简要介绍文章主题和阅读预期
## 主体部分 1
### 子标题 1.1
内容...
### 子标题 1.2
内容...
## 主体部分 2
内容...
## 总结
总结要点
## 参考资料
- [链接1](url)
- [链接2](url)
6. 草稿管理
6.1 草稿的工作流程
编写草稿 ──▶ 测试预览 ──▶ 修改完善 ──▶ 发布
↑
保存为草稿（发现问题）
6.2 创建草稿
方式一：使用 drafts 目录
将文件放在 content/drafts/ 目录：
content/drafts/my-draft.md
方式二：使用 status 元数据
---
Title: 我的草稿
Date: 2024-01-15
Status: draft
---
草稿内容...
6.3 预览草稿
在本地开发模式下预览草稿：
# 进入博客目录
cd my_blog
# 运行开发服务器（会显示所有草稿）
pelican content/ -s pelicanconf.py -l -p 8000
# 访问 http://localhost:8000/drafts/my-draft.html 查看草稿
6.4 发布草稿
将草稿改为已发布状态：
---
Title: 我的草稿
Date: 2024-01-15
Status: published # 改为 published
---
正文内容...
或者移动文件到正式目录：
mv content/drafts/my-draft.md content/articles/tech/
7. Git 同步流程
7.1 首次设置（只需执行一次）
# 进入博客目录
cd my_blog
# 初始化 Git（如果尚未初始化）
git init
# 添加远程仓库
git remote add origin https://gitee.com/hoeking/my_note.git
# 配置用户信息
git config user.name "Your Name"
git config user.email "your.email@example.com"
7.2 日常提交推送流程
# 1. 查看修改状态
git status
# 2. 添加修改的文件
git add content/articles/tech/new-post.md
# 或者添加所有修改
git add .
# 3. 提交
git commit -m "添加新文章：Python 装饰器教程"
# 4. 推送到 Gitee
git push origin master
7.3 提交信息规范
推荐使用清晰的中文提交信息：
# 格式
<类型>: <简短描述>
# 示例
新增: 添加 Python 装饰器教程
修改: 更新 Docker 入门指南
删除: 移除过时的文章
草稿: 开始写 TypeScript 系列文章
发布: 公开"Draft: TypeScript 基础"文章
常用类型：
新增：添加新文章修改：修改现有文章删除：删除文章草稿：开始写草稿发布：发布草稿配置：更新配置
7.4 常用 Git 命令
# 查看状态
git status
# 查看修改内容
git diff
# 查看提交历史
git log --oneline
# 查看远程仓库
git remote -v
# 拉取最新代码
git pull origin master
# 撤销未提交的修改
git checkout -- filename
# 取消暂存
git reset HEAD filename
8. 本地预览
8.1 启动预览服务器
# 进入博客目录
cd my_blog
# 启动开发服务器
pelican content/ -s pelicanconf.py --listen --autoreload
# 或者分开执行
pelican content/ -s pelicanconf.py --autoreload
pelican --listen
8.2 访问预览
打开浏览器访问：
- http://localhost:8000
8.3 实时预览
--autoreload 选项会在文件修改时自动重新生成：
- 修改 Markdown 文件
- 保存文件
- 浏览器自动刷新查看效果
9. 自动化部署说明
9.1 Webhook 工作原理
本地推送 ──▶ Gitee 接收 ──▶ 发送 Webhook ──▶ 服务器构建 ──▶ 完成
9.2 服务器构建流程
- 接收请求：Webhook 服务接收 Gitee 的 POST 请求
- 验证签名：确认请求来自 Gitee（使用密钥）
- 执行构建：运行构建脚本
bash
cd /var/www/blog
git pull origin master
pelican content/ -s publishconf.py
4. 返回结果：返回构建状态
9.3 构建时间参考
| 网站规模 | 预计构建时间 |
|---|---|
| 10篇文章 | 5-10 秒 |
| 50篇文章 | 20-30 秒 |
| 100篇文章 | 1-2 分钟 |
10. 常见问题处理
10.1 图片上传失败
问题：Typora 显示图片上传失败
解决方案：
- 检查 PicGo 是否运行
- 检查 Gitee Token 是否有效
- 检查 Gitee 仓库是否存在
- 查看 PicGo 日志排查错误
10.2 图片路径问题
问题：本地图片正常，服务器上图片不显示
原因：使用了本地绝对路径
解决方案：
- 使用 PicGo 将图片上传到图床
- 确保使用网络 URL 而非本地路径
- 或将图片放在
content/images/目录
10.3 中文文件名
问题：文件名包含中文导致 URL 异常
解决方案：
# 在元数据中使用 Slug
Title: 我的第一篇文章
Slug: my-first-article
# 文章 URL 将是：/articles/my-first-article.html
10.4 构建失败
问题：推送后网站没有更新
排查步骤：
- 检查 Gitee Webhook 发送记录
- 查看服务器构建日志：
/var/log/pelican-rebuild.log - 检查 Webhook 服务状态：
sudo systemctl status blog-webhook - 手动触发构建测试
10.5 缓存问题
问题：修改文章后页面没变化
解决方案：
# 清除缓存
cd /var/www/blog
pelican content/ -s publishconf.py --ignore-cache
11. 图床管理建议
11.1 图床选择
| 图床 | 优点 | 缺点 |
|---|---|---|
| Gitee | 免费、私有、速度快 | 有单文件限制 |
| GitHub | 国际化、免费 | 国内访问慢 |
| SM.MS | 免费、免登录 | 有流量限制 |
| 七牛云 | 速度快、可定制 | 需要实名认证 |
11.2 图片管理
PicGo-images/
├── blog/ # 博客图片
│ ├── 2024/ # 按年月分类
│ │ ├── 01/
│ │ └── 02/
│ └── avatar/ # 头像
└── screenshots/ # 截图
11.3 图片优化建议
- 使用
jpg格式存储照片（体积小） - 使用
png格式存储截图（支持透明） - 建议图片大小不超过 500KB
- 合理压缩图片再上传
12. 快速参考卡
12.1 Typora 快捷键
| 快捷键 | 功能 |
|---|---|
Ctrl + S |
保存 |
Ctrl + B |
加粗 |
Ctrl + I |
斜体 |
Ctrl + K |
链接 |
Ctrl + Shift + K |
代码块 |
Ctrl + Shift + M |
数学公式 |
Ctrl + / |
源码模式 |
Ctrl + 1-6 |
标题级别 |
12.2 Git 常用命令
| 命令 | 功能 |
|---|---|
git status |
查看状态 |
git add . |
暂存所有修改 |
git commit -m "消息" |
提交 |
git push |
推送到远程 |
git pull |
拉取远程更新 |
12.3 文章元数据模板
---
Title:
Date: 2024-01-01 10:00
Category:
Tags:
Slug:
Summary:
Status: published
---
正文内容...
13. 示例文章
13.1 完整文章示例
---
Title: 使用 Docker 部署 Python 应用
Date: 2024-01-15 09:00
Modified: 2024-01-16 14:30
Category: 技术
Tags: Docker, Python, 部署
Slug: docker-deploy-python
Author: Chen Li
Summary: 本文介绍如何使用 Docker 容器化并部署 Python 应用
Status: published
---
## 前言
在现代软件开发中，容器化已经成为部署应用的标准方式。本文将介绍如何使用 Docker 部署 Python 应用。
## 什么是 Docker
Docker 是一个开源的容器化平台，可以让开发者打包应用及其依赖到一个可移植的容器中。
### Docker 的优势
- **一致性**：开发、测试、生产环境一致
- **隔离性**：应用之间相互隔离
- **轻量级**：比虚拟机更节省资源
## 创建 Dockerfile
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "app.py"]
构建和运行
# 构建镜像
docker build -t my-python-app .
# 运行容器
docker run -d -p 8000:8000 my-python-app
总结
通过 Docker，我们可以轻松实现应用的容器化部署，提高开发和运维效率。
参考资料
```
```
14. 维护建议
14.1 定期整理
- 每月检查草稿箱，清理或发布草稿
- 每季度回顾文章，删除过时内容
- 定期整理图片，删除未使用的图片
14.2 备份策略
# 定期备份（加入 crontab）
0 2 * * * tar -czf /backup/blog-$(date +\%Y\%m\%d).tar.gz /var/www/blog
14.3 更新日志
保持更新记录：
## 更新日志
### 2024-01-15
- 新增 Docker 部署文章
- 优化 about 页面
### 2024-01-10
- 修复图片加载问题
- 添加搜索功能
15. 附件与音视频管理
15.1 目录结构说明
content/
├── articles/ # 博客文章
├── pages/ # 静态页面
├── images/ # 图片（已有）
├── downloads/ # 下载附件（新增）
│ ├── source-code/ # - 源码包
│ ├── templates/ # - 模板文件
│ └── documents/ # - PDF/文档
└── media/ # 音视频（新增）
├── videos/ # - 视频 (<10MB)
└── audios/ # - 音频 (<10MB)
⚠️ 重要：服务端
pelicanconf.py中的STATIC_PATHS已同步配置了这些目录。
15.2 下载附件（.zip/.rar/.7z）
存放位置：content/downloads/
引用方式：
## 示例代码
点击下载源码：[DEMO 源码.zip](/downloads/source-code/demo.zip)
## 附件列表
| 文件名 | 说明 | 下载 |
|--------|------|------|
| template-v1.zip | 模板文件 | [下载](/downloads/templates/template-v1.zip) |
| dataset.7z | 数据集 | [下载](/downloads/documents/dataset.7z) |
渲染效果：
15.3 嵌入视频（<10MB）
存放位置：content/media/videos/
嵌入方式：在文章中使用 HTML 标签
<video src="/media/videos/intro.mp4" controls width="640">
您的浏览器不支持视频播放
</video>
Markdown 中直接使用：
```html
<video src="/media/videos/demo.mp4" controls width="640">
您的浏览器不支持视频播放
</video>
**效果预览**：
<video src="/media/videos/intro.mp4" controls width="640">
您的浏览器不支持视频播放
</video>
### 15.4 嵌入音频（<10MB）
**存放位置**：`content/media/audios/`
**嵌入方式**：
```html
<audio src="/media/audios/podcast.mp3" controls>
您的浏览器不支持音频播放
</audio>
Markdown 中使用：
```html
<audio src="/media/audios/podcast.mp3" controls>
您的浏览器不支持音频播放
</audio>
**效果预览**：
<audio src="/media/audios/podcast.mp3" controls>
您的浏览器不支持音频播放
</audio>
### 15.5 最佳实践建议
| 类型 | 存放目录 | 文件大小限制 | 引用方式 |
| --- | ----------------------- | --------- | ------------ |
| 图片 | `content/images/` | <500KB | 图床 URL |
| 源码包 | `content/downloads/` | 无限制 | 下载链接 |
| 视频 | `content/media/videos/` | **<10MB** | `<video>` 标签 |
| 音频 | `content/media/audios/` | **<10MB** | `<audio>` 标签 |
| 大文件 | 第三方云存储 | 无限制 | 外链 |
### 15.6 大文件处理建议
对于超过 10MB 的视频或音频，建议使用第三方托管：
**推荐方案**：
| 平台 | 优点 | 适用场景 |
| ------------ | --------- | ----- |
| **Gitee** | 免费、国内速度快 | 私有仓库 |
| **阿里云 OSS** | 稳定、CDN 加速 | 生产环境 |
| **腾讯云 COS** | 稳定、按量付费 | 生产环境 |
| **BiliBili** | 视频托管、免费 | 视频内容 |
| **喜马拉雅** | 音频托管、免费 | 播客/音频 |
**外链嵌入示例**：
```markdown
## 视频演示
<iframe src="//player.bilibili.com/player.html?aid=XXXXXXXX"
scrolling="no" border="0" frameborder="no"
framespacing="0" allowfullscreen="true"
width="640" height="480">
</iframe>
文档信息
- 适用对象：内容创作者
- 编辑工具：Typora + PicGo
- 版本：Pelican 最新版