我原以为，建立个人 Blog 最难的部分应该是设计页面。真正动手以后才发现，页面反而不是最让我纠结的地方。第一次把仓库、Markdown、GitHub Actions 和 GitHub Pages 连在一起时，我花了不少时间确认它们各自到底负责什么。

现在回头看，这个过程很像搭一条小小的传送带：我在本地写文章，Git 记录改动，GitHub 保存内容，Actions 负责构建，Pages 把结果发布到网上。每一段都不复杂，但只有它们顺利接上，浏览器里才会出现最终的网页。

从一个空仓库开始

新建仓库时，空白页面给我的感觉有点像刚翻开的新笔记本：知道要写什么，却还是会在第一行前停一下。我把仓库命名为 githubskylh.github.io，并设为公开。这个名字不是随便取的，它正好对应 GitHub Pages 的个人站点规则，发布后的地址也会比较干净。

接着，我把 Blog 的配置、页面布局、样式和文章源文件放进仓库。最核心的目录其实并不多：

.
├─ _layouts/       # 页面骨架
├─ _posts/         # Markdown 文章
├─ assets/css/     # 页面样式
├─ _config.yml     # Jekyll 配置
└─ index.html      # Blog 首页

以前看到下划线开头的目录时，我总觉得它们像某种复杂框架的内部机关。这次自己搭完才明白，Jekyll 只是按照约定去找文件：文章放进 _posts，布局放进 _layouts，全站设置写在 _config.yml。理解了约定，目录就不再神秘了。

Markdown 怎么变成网页

写第一篇文章时，我用的仍然是熟悉的 Markdown。标题前加 #，代码放进围栏，段落之间留一个空行。它看起来只是一个普通文本文件，却因为文件开头多了一段 YAML Front Matter，拥有了标题、日期、布局和固定链接。

---
layout: post
title: GitHub新手之旅从Markdown到自动发布
permalink: /posts/github-newcomer-journey/
---

这几行配置像文章的“身份证”。Jekyll 读取它以后，知道应该把正文套进哪一种页面布局，也知道最终网页应该放在哪个地址。Markdown 负责让我专心写内容，Jekyll 负责把内容变成结构完整的 HTML，两者的分工比我一开始想象得更清楚。

Actions 是一条看得见的流水线

让我最有成就感的部分，是第一次看到 GitHub Actions 里的绿色对勾。

我在 .github/workflows/pages.yml 中写下自动发布流程，并把触发条件设为向 main 分支推送内容。每次提交之后，GitHub 会自动检出仓库、初始化 Pages、运行 Jekyll 构建、上传生成的站点文件，最后完成部署。

这意味着我不需要手动把 HTML 文件复制到服务器，也不用记住一长串发布命令。对我来说，最直观的理解是：

仓库保存“我写了什么”，Actions 记录“怎样把它做成网站”，Pages 负责“让别人在哪里看到它”。

工作流文件本身也是仓库内容的一部分，所以发布方法和 Blog 源文件被放在一起管理。以后无论在哪台电脑上修改文章，只要把改动推送到 main，同样的流程就会重新执行。

一个容易忽略的关键配置

配置文件写好并不等于网站一定会出现。我还需要在仓库的 Settings → Pages 中，把发布来源设置成 GitHub Actions。

如果这里仍然选择从某个分支目录发布，GitHub 就不会按照自定义工作流上传的站点产物来部署。另外，工作流还需要 pages: write 和 id-token: write 权限：前者允许它写入 Pages，后者用于完成安全的身份验证。

这个配置点让我真正理解了“自动发布”不是一个模糊的开关。它既需要一份写清楚步骤的工作流，也需要仓库明确允许这份工作流把构建结果发布出去。

修改文章以后，网站为什么会更新

第一次部署成功后，我又改了文章中的一句话并提交。随后，Actions 页面出现了一条新的运行记录。构建和部署完成后，我刷新文章页面，刚才的修改已经出现在网站上。

这个小测试比只看到一次成功记录更有说服力。它证明网站不是我手动上传的一份静态成品，而是和仓库内容保持着联系：

  1. 我修改 Markdown 并提交；
  2. push 事件触发 GitHub Actions；
  3. Jekyll 重新生成网页；
  4. Pages 用新的构建结果替换旧版本。

从写下一句话到它出现在公开网页上，中间的过程虽然由机器完成，但每一步都有记录，也都能回头检查。我开始理解为什么自动化发布会成为开源项目中很常见的做法：它不仅节省操作，也让发布过程变得可重复、可追踪。

写在第一次发布之后

这个 Blog 现在还很小，只有一个首页和第一篇文章。不过，从空仓库到真正可以访问的网站，我已经走完了一次完整的流程。

更重要的是，我不再把 GitHub 只看作存放代码的网盘。仓库保存历史，Markdown降低写作负担，Actions连接开发与发布，Pages提供公开访问地址。它们合作起来，才组成了现在看到的这个 Blog。

第一次发布成功时，绿色对勾并没有多么惊天动地，但我还是盯着它看了几秒。那一刻很具体：我写下的文字已经不只躺在电脑里，它有了一个可以被分享、被访问，也可以继续生长的地址。