← 返回主页

博客内容发布与维护操作指南

2026年08月01日
#博客维护 #Hugo #Markdown

本文档旨在规范 Miles’ Archive 博客的内容更新流程，提供关于文章（Post）与动态（Moment）的标准化写作规范、元数据（Front Matter）配置说明，以及代码仓库（GitHub）的提交流程。

1. 核心概念与路径规范

基于 Hugo 静态站点生成器的架构，博客的所有文字内容均作为 Markdown (.md) 文件存储于特定的文件树节点中。文件上传至 GitHub 仓库后，Cloudflare Pages 将自动触发构建并更新线上环境。

1.1 文件分类与存储路径

博客内容分为两种独立类型，需严格存放于对应的 GitHub 目录中：

2. 元数据（Front Matter）参数详解

每个 Markdown 文件的顶部必须包含一块以 +++ 包裹的区域，被称为 Front Matter。当前站点使用 TOML 语法解析此区域。该区域不显示在文章正文中，但控制着网页的生成逻辑（如标题、时间、标签归属、是否可见）。

2.1 结构示例

+++
title = "这里是文章的标题"
date = "2026-08-01T13:41:29+09:00"
draft = false
tags = ["Python", "随笔"]
+++

2.2 核心参数说明

编写 +++ 与 +++ 之间的内容时，必须遵守严格的键值对（Key-Value）数据类型：

参数名 数据类型 填写说明与约束条件
title 字符串 (String) 网页及列表中显示的主标题。必须使用双引号包裹，如 "学习笔记"。对于部分动态（Moments），如果模板不需要显示标题，该项留空或保留默认即可。
date 日期时间 (Datetime) 决定文章在列表中的排序依据。标准格式推荐使用 YYYY-MM-DD（如 "2026-08-01"）或 ISO 8601 标准包含时间与时区（如 "2026-08-01T13:41:29+09:00"）。无需加双引号。
draft 布尔值 (Boolean) 控制内容是否在线上环境显示。填 true 为草稿模式（上传至 GitHub 后不会被 Cloudflare 构建并展示），填 false 为正式发布。无需加双引号。
tags 字符串数组 (Array) 用于生成侧边栏或底部的“标签云”。支持多标签，需用中括号包裹，各项用逗号与双引号分隔，如 ["技术", "生活"]。空标签写为 []。

严格语法警告： TOML 语法对格式极为敏感。参数名必须全小写；除了布尔值和日期，字符串内容必须包含在英文状态的双引号中；每行仅书写一个参数；+++ 符号必须独占首行和末行，且前后不能有空格。

3. 标准化写作流程

3.1 撰写一篇新文章（Post）

  1. 在本地文本编辑器（如 VS Code 或 Notepad）中新建一个 .md 文件，命名为 your-title.md。
  2. 在文件头部添加并配置 Front Matter。
  3. 在第二个 +++ 下方留出一个空行，开始书写正文。
  4. 使用标准 Markdown 语法排版（见附录）。

完整文件示例代码：

+++
title = "如何使用 Python 爬取网页"
date = "2026-08-05"
draft = false
tags = ["Python", "爬虫"]
+++

这里是文章的开头。

## 准备工作
首先需要安装 requests 库。

## 代码实现
```python
import requests
print("Hello World")

正文内容结束。


### 3.2 撰写一条新动态（Moment）
与文章类似，但通常不需要复杂的排版和过长的文字。
1. 新建 `.md` 文件，命名为 `2026-08-05-thought.md`。
2. 配置 Front Matter。由于动态列表更侧重于信息流，`tags` 等属性可视需精简。

**完整文件示例代码**：
```markdown
+++
title = "今日随笔"
date = "2026-08-05T20:30:00+09:00"
draft = false
tags = ["生活"]
+++

今天修复了博客的一些遗留 Bug，清理了不再使用的时间轴菜单。
下一步准备开始深入学习 Python。

4. 上传至 GitHub 触发云端部署

当你在本地编写并保存好 .md 文件后，需将其上传至 GitHub 仓库以触发 Cloudflare Pages 的自动构建与发布。

4.1 GitHub 网页端上传步骤

  1. 访问并登录你的 GitHub 仓库（https://github.com/你的用户名/miles-archive）。
  2. 在仓库首页的文件列表中，点击进入 content 文件夹。
  3. 根据你写的内容类型，点击进入 posts 或 moments 文件夹。
  4. 点击右上角的 “Add file” 按钮，在下拉菜单中选择 “Upload files”。
  5. 将你在本地写好的 .md 文件拖拽进入虚线框内。
  6. 等待文件加载完毕后，在底部的 “Commit changes” 区域填写提交信息（例如：“新建文章：Python 爬虫教程” 或 “更新动态”）。
  7. 确认下方选项为 “Commit directly to the main branch”，点击绿色的 “Commit changes” 按钮。

4.2 状态监测

完成上述步骤后：

  1. 文件已被永久存入 GitHub 仓库。
  2. Cloudflare Pages 会在 3 秒内侦测到代码仓库的变化。
  3. 云端服务器将自动执行 hugo 构建命令（约耗时 1-2 分钟）。
  4. 刷新你的专属域名（.pages.dev），即可看到最新发布的文章或动态。

附录：常用 Markdown 语法备忘

为保持博客页面排版的统一性与美观度，正文部分请遵循以下常用 Markdown 规范：