写作与发布流程¶

溪海莘发布于 2026-10-19

一篇博客从新建草稿、本地预览到推送发布的完整步骤，忘了就回来看一眼

这篇是给自己看的操作手册。写新文章、本地检查、发布上线，按顺序走一遍就行。

速查¶

常用的四条命令，先放这里：

PowerShell
cd D:\yourpath\blog\my-blog\my-docs
D:\yourpath\blog\my-blog\venv\Scripts\Activate.ps1

mkdocs serve            # 本地预览，改文件自动刷新
mkdocs build --clean    # 发布前构建检查

git add -A
git commit -m "feat: 新增文章标题"
git push origin master  # 推上去后 GitHub Actions 自动部署

站点地址：https://xihaixin.cn/

一、写文章¶

在 docs/ 下对应的目录新建 .md 文件，比如 docs/BLOG/Linux/docker.md。

文件顶部先写 front matter：

YAML
---
title: "Docker 入门笔记"
date: 2026-09-14
author: "溪海莘"
description: "从安装到第一个容器，记录 Docker 的基本用法。"
---

# Docker 入门笔记

正文……

几个字段的作用：

字段	影响
`title`	浏览器标签、导航文字、搜索标题
`date`	文章页「发布于」；首页「最近更新」的排序
`updated`	首页「最近更新」优先按它排序；文章页「更新于」
`author`	文章页显示作者
`description`	首页摘要、文章页摘要、SEO 描述

日期不要加引号

写成 date: 2026-09-14。加了引号会导致首页的钩子读不到，回退去用 git 日期。

updated 首次发布不用写，以后大改再加。正文最好保留一个与 title 一致的 # 一级标题。图片统一放 docs/images/，用相对路径引用。

二、注册导航¶

打开 mkdocs.yml，把新文章加进对应的 nav：

YAML
  - 博客:
    - BLOG/index.md
    - Linux:
      - BLOG/Linux/vim.md
      - BLOG/Linux/docker.md   # 新增

nav 决定顶部标签栏和左侧目录；
不加也能生成页面，但不会出现在导航里，构建时还会提示 not included in nav；
一级项（如 博客:）对应顶部的一个标签。

三、本地预览¶

PowerShell
mkdocs serve

打开 http://127.0.0.1:8000/。修改 .md 或 mkdocs.yml 后会自动重建，刷新浏览器即可；Ctrl+C 停止。

发布前建议过一遍这个清单：

检查项	看什么
元数据	标题下方是否有「作者 · 发布于」和摘要
导航	顶部标签、左侧目录是否出现新文章
首页	「最近更新」是否自动收录
链接	站内链接是否 404
移动端	用浏览器设备模拟看窄屏
终端	有没有 `WARNING`

首页「最近更新」的收录范围

只有 BLOG、DEV、LECTURE、ESSAY 下的文章会进首页列表； ABOUT、WEBSITE 不参与。文件名是 index.md 的页面也会跳过。

四、发布前构建¶

PowerShell
mkdocs build --clean

确认没有 ERROR 或 WARNING。site/ 是构建产物，已在 .gitignore 里，不会被提交。

五、提交并发布¶

PowerShell
git status
git add -A
git commit -m "feat: 新增 Docker 入门笔记"
git push origin master

推送后 GitHub Actions 会按 .github/workflows/mysite.yml 自动执行：安装依赖 → mkdocs build → 复制 CNAME → 发布到 GitHub Pages。

在仓库的 Actions 页面能看到进度。完成后访问 https://xihaixin.cn/；如果没更新，先按 Ctrl+F5 清缓存。

SSH 推送不稳定时

远端用的是 SSH。如果 git push 卡住或报 Connection closed，可以临时切到 HTTPS：

PowerShell
git remote set-url origin https://github.com/Xihaixin/Xihaixin.github.io.git
git push origin master

推完再切回 SSH 也可以。

六、发布之后¶

在 GA4 的「报告 → 实时」里能看到访问；
首页「最近更新」会自动包含新文章，不用手改；
「推荐文章」是手写的，需要的话再改 docs/index.md。

常见问题¶

现象	原因与解决
点链接 404	原始 HTML 里写了 `.md`，改成目录 URL（如 `BLOG/Linux/docker/`）
文章不在导航	忘了加进 `mkdocs.yml` 的 `nav`
首页没有新文章	不在内容目录下，或文件名是 `index.md`
文章页没有日期	日期加了引号，或字段名拼错
Action 失败	看 Actions 日志，常见是依赖或 YAML 缩进问题
推送失败	SSH 不稳定，按上面的方法临时切 HTTPS