Astro博客

PlainBlog — Astro 博客模板

作者 wutongyuonce

PlainBlog 是一个基于 Astro 的黑白极简静态博客模板，首页按年份列出文章，支持深浅色切换与紧凑 Markdown 排版。

打开源站下载源码 ZIP

看看你的网站会是什么样

浏览真实页面截图，比较内容排版与手机效果。点击下方缩略图切换，放大查看整页细节。

3 个预览视图

桌面端首页1 / 3

访问演示网站在新标签页打开

桌面端截图首屏预览

由服务器浏览器实际访问页面后截取。

全部页面与视图 3

截图用于了解视觉与布局，交互效果请以实际项目为准。

采集于 2026-10-05查看来源

值得关注的模板亮点

从已有项目资料中，快速了解它的特点。

黑白极简视觉，默认深色背景，可切换为白底

首页按年份列出文章，正文采用紧凑 Markdown 排版

面包屑导航与按需展开的目录，目录开关不依赖 JavaScript

文章以 Markdown 文件管理，支持 draft 草稿排除

构建时自动生成 /rss.xml 订阅源，新文章无需手动修改

自带 GitHub Pages 部署工作流，push 到 main 自动发布

模板详细介绍

PlainBlog 是采用 Astro 构建的静态博客模板，整体为黑白极简风格，默认黑色背景，也可切换为白底。首页按年份列出文章，正文使用紧凑的 Markdown 排版；导航由无背景框的面包屑和按需展开的目录组成。仓库中的文字与图片均为可替换的演示内容。

模板通过 src/config.ts 配置站点名称、描述、下拉目录和首页社交地址；文章放在 src/content/posts/ 下，使用单层、全小写 kebab-case 的 .md 文件，Frontmatter 要求非空 title 和带引号的 YYYY-MM-DD 日期，正文从 ## 开始。draft: true 的文章会从首页和正文输出中排除，未来日期不会自动隐藏。文章配图放在 src/assets/posts/<文章文件名>/ 目录，缺失的相对图片会导致构建失败。

构建产物为静态文件，输出到 dist/，无需服务端、数据库或运行时环境变量。设置 SITE_URL 后才会输出 canonical 和绝对订阅链接；部署在子路径时需额外设置 BASE_PATH。仓库自带 GitHub Pages 部署工作流，push 到 main 时执行检查并发布。

Astro博客

适合你的项目吗？

适用场景

搭建以文字为主、重视排版与阅读体验的个人博客
需要按年份归档文章并保持页面结构简洁的写作站点
希望用 Markdown 文件管理内容并部署为纯静态站点的场景
使用 GitHub Pages 托管并希望 push 后自动构建发布的博客

适合人群

偏好极简黑白风格、不需要复杂视觉组件的博主
熟悉 Markdown 与基本命令行操作的个人开发者
需要静态输出、无服务端依赖的博客项目
愿意通过配置文件调整站点信息与导航的维护者

上手与定制指南

结合仓库当前版本的说明，按下面的资料检查内容、配置与运行要求。

1
需要 Node.js 22.12+ 和 pnpm 12.6，版本记录在 package.json 中
2
安装依赖后运行 pnpm dev 启动本地开发，pnpm build 生成静态产物到 dist/
3
生产构建需设置 SITE_URL 为绝对 HTTP(S) 地址，否则不输出 canonical；部署在子路径时再设置 BASE_PATH
4
使用仓库自带 GitHub Pages 工作流前，需在仓库 Settings → Pages 将 Source 设为 GitHub Actions
5
文章配图放在 src/assets/posts/<文章文件名>/，不要放进 src/content/posts/，缺失的相对图片会导致构建失败

查看仓库使用说明

授权与来源资料

使用条件与限制

免费使用 · 保留许可声明

本次收录的是公开仓库中采用 MIT 许可的免费版本；免费范围为该版本代码，不代表外部服务或第三方素材免费。

使用时需要遵守

允许免费使用、修改、商用和分发该版本代码。
分发代码副本或实质性部分时，保留原作者版权声明和完整 MIT 许可声明。
代码按现状提供；担保与责任限制以原许可证及适用法律为准。

额外费用与待核对事项

演示图片、字体、图标及其他第三方素材需按各自许可核对，不能仅凭代码的 MIT 许可判断。
域名、托管、数据库、支付或 AI 等外部服务可能另外收费。
模板内置的社交图标链接默认指向 GitHub、X、B站、小红书等平台首页，发布前必须替换为你自己的主页地址。
使用仓库自带的 GitHub Pages 部署工作流前，需在仓库 Settings → Pages 中将 Source 设置为 GitHub Actions，否则无法自动发布。
生产构建需设置 SITE_URL 为绝对 HTTP(S) 地址，否则不会输出 canonical 链接；该变量为部署时的外部配置要求。
若部署在站点子路径下，需额外设置 BASE_PATH（不带尾斜线），页面、静态资源、canonical 与订阅地址都会带上该前缀。
本地开发与构建需要 Node.js 22.12+ 和 pnpm 12.6，版本要求记录在 package.json 中。
文章引用的相对图片若缺失，会导致构建失败，需确保图片文件存在。
markdown-field-guide.md 同时作为 Markdown 渲染样例；若删除该文件，需同步修改测试中的对应路径。

查看原文依据

Permission is hereby granted, free of charge
许可证原文

现有 GitHub、X、B站、小红书指向各网站首页，发布前换成你自己的主页。
README 原文

启用前需要在仓库 Settings → Pages 把 Source 设为 GitHub Actions。
README 原文

生产域名确定后，在构建环境设置 `SITE_URL=https://your-domain.example/`（必须是绝对 HTTP(S) 地址），构建才会输出对应页面的 canonical；不设置时不输出 canonical。
README 原文

部署在站点子路径时（例如项目页）再设置 `BASE_PATH=/your-sub-path`（不带尾斜线），页面、静态资源、canonical 与订阅地址都会带该前缀；`SITE_URL` 仍然只写源站。
README 原文

需要 Node.js 22.12+ 和 pnpm 12.6（版本记录在 `package.json`）。
README 原文

缺失的相对图片会让构建失败。
README 原文

`markdown-field-guide.md` 同时是 Markdown 渲染样例。若移除它，请把测试里的该路径换成保留的排版样例。
README 原文

https://github.com/wutongyuonce/PlainBlog/blob/main/LICENSE https://github.com/wutongyuonce/PlainBlog/blob/main/README.md

DeepSeek 根据仓库许可证和 README 整理 ·2026-10-05。结果仅覆盖已读取资料，依赖、图片、字体及后续条款变更以各自原文为准。

项目核对记录与介绍依据

模板资料

来源平台: Astro Themes
资料与维护参考分: 资料一般 · 72 / 100
技术栈: Astro
网站类型: 博客

这个分数如何计算

本站按许可资料（最高30分）、演示链接（12分）、预览图（10分）、Star数（15分）、记录的维护时间（15分）、描述完整度（8分）、功能记录（5分）和分类资料（5分）计算。它不是代码、安全或性能测试，也不是 Google 评分；有链接不代表已实测可用。

这个项目需要核对什么

记录的仓库更新时间: 2026-09-29
截图检查日期: 2026-10-05

已收录演示链接。请用你的内容与屏幕尺寸检查；有演示不代表表单、认证或支付已经可用。

目录记录的主要技术栈是 Astro。请通过依赖清单和锁文件核对实际版本与托管要求。这些说明基于收录资料，不代表代码审计或部署实测。

查看具体选型方法 →

介绍的制作与核对状态

介绍由 AI 辅助整理目录与仓库资料。仓库作者不等于这篇介绍的审核者。

审核声明: [email protected] · 2026-10-06

查看当时使用的来源资料

SHA-256: 4750cb7809ae5c1f25970491d8c48c1074235cc20fa01196cb066790e3f65eed

2026-10-05T20:55:35.378Z

来源文件 / 仓库

# PlainBlog

黑色极简静态博客，也可切换为白底。首页按年份列出文章，正文使用紧凑的 Markdown 排版；导航是无背景框的面包屑和按需展开的目录。主题灵感来源来自 https://hyoban.cc

仓库里的文字和图片是可替换的演示内容。产品行为见 [规格](docs/SPEC.md)。

<img src="docs/previews/home-dark.png" alt="深色主题下的首页" style="zoom:40%;" />

<img src="docs/previews/home-light.png" alt="浅色主题下的首页" style="zoom:40%;" />

## 开始

需要 Node.js 22.12+ 和 pnpm 12.6（版本记录在 `package.json`）。

```sh
pnpm install
pnpm dev
```

打开终端给出的本地地址。检查与构建：

```sh
pnpm check
pnpm format
pnpm lint
pnpm test
pnpm build
pnpm preview
```

`pnpm test` 会先构建无站点 URL 的 HTML，再用 Node 测试内容规则与实际产物。失败构建和改名测试使用临时项目副本，不改写作者内容或当前 `dist/`。`pnpm format:write` 可格式化项目文件。`lint` 与 `check` 都运行 Astro 诊断，不是独立的 ESLint。

## 修改内容

- 编辑 `src/config.ts` 的站点名称、描述、下拉目录和首页社交地址。每条社交入口用 `icon` 字段指定图标，可用值见 `src/lib/social-icons.mjs`；现有 GitHub、X、B站、小红书指向各网站首页，发布前换成你自己的主页。Home 已固定在面包屑，不要再加入目录。新增独立页面时创建对应的 `src/pages/*.astro` 文件，再把入口加入导航数组；文章不需要加入目录。
- 在 `src/content/posts/` 新建单层、全小写 kebab-case 的 `.md` 文件，例如 `my-note.md`。Frontmatter 必须有非空 `title` 和引号包围的 `YYYY-MM-DD` 日期；正文从 `##` 开始。`draft: true` 会从首页和正文输出中排除；未写 draft 时默认公开。未来日期不会自动隐藏。
- 编辑 `src/content/pages/home.md` 修改首页介绍；`projects.md` 和 `about.md` 维护独立页面。页面标题由配置或对应 Astro 页面负责。
- `markdown-field-guide.md` 同时是 Markdown 渲染样例。若移除它，请把测试里的该路径换成保留的排版样例。新增普通文章不必修改测试清单。
- 文章配图放在 `src/assets/posts/<文章文件名>/`，用可读文件名，例如 `![说明](../../assets/posts/my-note/photo.jpg)`。不要把图片放进 `src/content/posts/`，那里只放一层 Markdown。缺失的相对图片会让构建失败。

## 部署

执行 `pnpm build`，把 `dist/` 发布到静态站点根路径。生产域名确定后，在构建环境设置 `SITE_URL=https://your-domain.example/`（必须是绝对 HTTP(S) 地址），构建才会输出对应页面的 canonical；不设置时不输出 canonical。部署在站点子路径时（例如项目页）再设置 `BASE_PATH=/your-sub-path`（不带尾斜线），页面、静态资源、canonical 与订阅地址都会带该前缀；`SITE_URL` 仍然只写源站。无需服务端、数据库或运行时环境变量。

仓库自带一个 GitHub Pages demo：`.github/workflows/deploy.yml` 在每次 push 到 `main` 时跑检查并发布到 `https://wutongyuonce.github.io/PlainBlog/`。启用前需要在仓库 Settings → Pages 把 Source 设为 GitHub Actions。这是仓库唯一的部署配置，其他平台按上面的环境变量自行接入。

配置主机把未知路径映射到 `dist/404.html`，并返回 HTTP 404。`/blog/` 没有汇总页面，也不会自动跳转。目录开关的原生功能不依赖 JavaScript。配色按钮会记住选择；没有 JavaScript 时跟随系统。订阅地址是 `/rss.xml`。它在每次构建时读取全部公开文章，新文章不用手改订阅源；草稿不会进入。设置 `SITE_URL` 后，订阅项和图片地址才会变成绝对链接。

## 许可证

[MIT](LICENSE)，版权归仓库作者。首页社交图标取自 [Simple Icons](https://simpleicons.org)（CC0 1.0），其中的品牌标识归各自所有者。

反馈内容错误