跳转至

Blog 工作流

这是什么

这篇文档记录本站 Blog 文章的固定写法。
每次新建 Blog 文章时，可以直接复制模板，然后修改图片、日期、正文、标签和目录卡片。

1. 当前 Blog 结构

Blog 目前按栏目组织：

docs/Blog/
├── index.md                         # Blog 总入口
├── month-journal/
│   ├── index.md                     # Month Journal 列表页
│   └── journal/
│       └── 开篇记.md                # 单篇文章
└── technical/
    └── index.md                     # Technical 列表页

当前文章样式由 docs/stylesheets/extra.css 中的 blog-article 系列类控制。
新文章只需要复用模板，不需要每次改 CSS。

2. 新建文章步骤

第一步：新建 Markdown 文件

例如新增一篇月度记录：

docs/Blog/month-journal/journal/新文章.md

建议：

  • 文件名可以用中文，方便在目录里识别。
  • 如果文章标题较长，也可以用英文短横线文件名，例如 first-month-review.md。
  • 图片地址建议优先使用本站本地资源，例如 /assets/images/...；如果临时使用图床，也要确认国内能访问。

3. 单篇文章模板

复制下面模板到新 .md 文件中，然后替换标注项。

docs/Blog/month-journal/journal/新文章.md
---
title: 文章标题
date: 2026-06-13
updated: 2026-06-13
cover: 图片地址
tags:
  - journal
  - self-review
---

<article class="blog-article" markdown>

<header class="blog-article-hero" markdown>
<div class="blog-article-hero-card" style="--article-cover: url('图片地址');">
  <img src="图片地址" alt="文章标题">
</div>

<div class="blog-article-hero-copy">
  <span class="blog-article-kicker">Month Journal · Jun 13, 2026</span>
  <h1>文章标题</h1>
  <p class="blog-article-summary">一句话摘要，说明这篇文章在记录什么。</p>
</div>
</header>

<div class="blog-article-body" markdown>

## 一、第一节标题

正文内容。

## 二、第二节标题

正文内容。

</div>
</article>

需要替换的内容

字段 示例 说明
title 开篇记 页面标题
date 2026-06-13 撰写日期，建议用 YYYY-MM-DD
updated 2026-06-13 更新日期
cover /assets/images/blog/xxx.jpg 文章头图
tags journal、self-review 文章标签
blog-article-kicker Month Journal · Jun 13, 2026 头图下方的小字
h1 开篇记 正文显示的大标题
blog-article-summary 一句话摘要 同时建议用于列表页卡片摘要

图片地址要改两处

文章模板里图片地址出现了两次：

style="--article-cover: url('图片地址');"
<img src="图片地址" alt="文章标题">

两处都要替换成同一张图。第一处用于右侧虚化阴影，第二处用于真实显示图片。

4. 注册到导航

打开项目根目录的 mkdocs.yml，找到 Blog 部分。

月度记录文章添加到这里：

mkdocs.yml
- Blog:
    - Blog/index.md
    - Month Journal:
        - Blog/month-journal/index.md
        - 文章标题: Blog/month-journal/journal/新文章.md
    - Technical:
        - Blog/technical/index.md

路径规则

路径从 docs/ 后面开始写。
例如真实文件是：

docs/Blog/month-journal/journal/新文章.md

在 mkdocs.yml 中写：

Blog/month-journal/journal/新文章.md

5. 添加到栏目列表页

如果是月度记录，打开：

docs/Blog/month-journal/index.md

在 <div class="blog-post-list" markdown> 里添加文章卡片。新文章建议放在最上面。

docs/Blog/month-journal/index.md
<a class="blog-post-card" href="journal/新文章/" style="--blog-cover: url('图片地址');">
  <span class="blog-post-date">Jun 13, 2026</span>
  <strong>文章标题</strong>
  <span class="blog-post-desc">一句话摘要，说明这篇文章在记录什么。</span>
  <span class="blog-post-time">2 min read</span>
  <span class="blog-tags"><i>journal</i><i>self-review</i></span>
  <span class="blog-card-arrow">-></span>
</a>

卡片字段说明

字段 示例 说明
href journal/新文章/ 指向文章页面
--blog-cover url('图片地址') 列表卡片背景图
blog-post-date Jun 13, 2026 列表显示日期
strong 文章标题 列表显示标题
blog-post-desc 一句话摘要 列表摘要
blog-post-time 2 min read 预估阅读时间
blog-tags journal、self-review 标签

图片在列表页也要填

正文页的 cover 不会自动同步到列表页。
目录卡片里仍然需要手动填：

style="--blog-cover: url('图片地址');"

6. 更新 Blog 总入口

如果这篇文章让某个栏目有了最新更新，可以打开：

docs/Blog/index.md

更新对应栏目卡片的日期。例如 Month Journal：

<a class="blog-post-card" href="month-journal/" style="--blog-cover: url('图片地址');">
  <span class="blog-post-date">Jun 13, 2026</span>
  <strong>Month Journal</strong>
  <span class="blog-post-desc">每月复盘、阶段想法。</span>
  <span class="blog-tags"><i>journal</i><i>review</i></span>
  <span class="blog-card-arrow">-></span>
</a>

通常只需要改：

  • blog-post-date
  • 必要时改 --blog-cover

7. 日期格式约定

文章 front matter 使用机器友好的日期：

date: 2026-06-13
updated: 2026-06-13

页面显示和卡片显示使用英文短日期：

Jun 13, 2026

保持这两种格式即可。

8. 标签建议

Month Journal 常用：

tags:
  - journal
  - self-review

Technical 常用：

tags:
  - technical
  - engineering

卡片中的标签也要同步：

<span class="blog-tags"><i>journal</i><i>self-review</i></span>

9. 完整检查清单

每次新增 Blog 文章后，检查这几处：

  • 新文章 .md 已创建。
  • 文章模板中的 title、date、updated、cover、tags 已修改。
  • 头图地址在 --article-cover 和 <img src=""> 两处都已修改。
  • 文章标题、摘要、正文已修改。
  • mkdocs.yml 已注册到 Blog 导航。
  • 对应栏目列表页已新增文章卡片。
  • Blog 总入口日期已更新。
  • 本地预览正常。

10. 本地预览与发布

本地预览：

mkdocs serve

确认没问题后发布：

git add .
git commit -m "add: 新增Blog文章"
git push

推送后 GitHub Pages 和 Vercel 会自动部署。