gobin

README

Gobin - 高性能静态博客生成器

Gobin 是一个基于 Go 语言开发的静态博客网站生成器，专为追求极致性能和高定制性的博客作者设计。它兼容常见的 Jekyll 博客内容结构，让您能够迁移现有 Markdown 内容，同时享受更快的构建速度和更灵活的定制能力。

项目背景

本项目旨在将现有的 Jekyll 博客（使用 Beautiful Jekyll 主题）迁移到一个自研的静态网站生成器上。通过使用 Go 语言重写，我们期望达到以下目标：

• 极速构建：相比 Jekyll，构建速度提升 10-100 倍
• 零依赖部署：单二进制文件，无需运行时环境
• 迁移友好：保持常见 Markdown 文件结构和 Front Matter 格式
• 灵活定制：强大的模板系统和配置选项

当前能力

已支持

• Markdown + YAML Front Matter 解析
• _posts/ 目录结构
• 列表页、文章页、标签页、分类页生成
• RSS、Atom、Sitemap、搜索索引生成
• 基础主题模板与静态资源复制
• build、serve、init、new、check、version CLI 命令
• permalinks.posts 文章链接配置
• draft / published 内容可见性控制
• assets.fingerprint 静态资源指纹（query / filename 两种策略）
• serve watch 模式下的 LiveReload 注入
• gobin build --incremental 增量构建：按 source / list / feed / search / sitemap 多类别指纹跳过未变化的产物
• gobin serve watcher 重建自动启用增量，只重渲染受影响的产物
• gobin build --jobs N 并行页面渲染：多 worker 并发渲染文章/列表/taxonomy 页面，与增量构建正交叠加
• Hugo 风格短代码（shortcodes）：{{< name args >}} / {{% name args %}}，内置 figure / youtube / gist / highlight，并支持站点与主题自定义
• v1.6 gobin build --jobs N 同时并行 Markdown 解析（min(NumCPU, 4)，与渲染共用同一并发度）
• v1.7 assets.images 图片优化管线：自动生成多尺寸变体 + HTML <picture><source srcset> 改写（jpg/png 完整支持）
• v1.7.1 image pipeline 增量构建：按源文件 hash + 配置 hash 跳过未变化的变体，未变化时接近零开销
• v1.7.2 WebP 真实编码：基于 github.com/HugoSmits86/nativewebp（纯 Go，零 cgo）的 WebPExecutor，formats: ["webp"] 现在产出浏览器可加载的真实 WebP 字节
• v1.8 Jekyll 模板兼容层：自动发现 _layouts/ / _includes/，front matter layout: 驱动模板选择，{{ .Content }} 正文注入（对应 Jekyll {{ content }}）；模板语法仍为 Go html/template，不引入 Liquid
• v1.8.1 Jekyll 模板变更跟踪修复：_layouts/ / _includes/ 纳入增量构建环境哈希和 serve --watch 监听
• v1.8.2 多静态资源目录 staticDirs：img/ / images/ 等一并复制进 publishDir，serve --watch 监听全部静态目录

当前限制

• 多语言、AVIF 编码、图片 LQIP 占位图等仍在规划中
• v1.7 图片管线默认关闭（assets.images.enabled: false），opt-in；启用后端到端构建时间因图片转换增加 ~10-30%
• v1.7.2 WebP 编码为 VP8L lossless（nativewebp 后端），体积偏大于 lossy WebP；AVIF / lossy WebP / LQIP / EXIF 保留为后续候选

规划中

• AVIF / lossy WebP 编码后端（libvips）
• Jekyll 模板迁移诊断与辅助工具（保持 Go html/template，不引入 Liquid 运行时）
• 多语言支持
• 更完善的主题系统和开发服务器体验

进一步阅读

完整文档索引见 docs/README.md。功能使用指南见 docs/guides/：

• Shortcodes 使用指南
• 增量构建使用指南
• 并行构建使用指南
• 统一日志系统使用指南
• 资源管线使用指南
• serve watch 行为指南
• 图片优化管线指南
• Jekyll 模板迁移指南
• 多静态资源目录指南

版本发布说明与更新日志见 docs/releases/，构建与发布流程见 docs/releases/build-and-release-guide.md。

技术栈

• 后端生成器：Go 1.25
• Markdown 渲染：goldmark
• 代码高亮：Chroma / Prism.js
• 模板引擎：Go html/template
• CLI 框架：cobra
• CSS 框架：Tailwind CSS（可选）

快速开始

安装

# 从源码安装（推荐）
git clone https://github.com/mengbin92/gobin.git
cd gobin
go build -o gobin ./cmd/gobin

# 使用 Go install 安装
go install github.com/mengbin92/gobin/cmd/gobin@latest

# 使用 Docker 运行
docker run --rm -p 8080:8080 \
  -v "$PWD:/site" \
  docker.io/mengbin92/gobin:latest

创建新站点

# 初始化新博客
gobin init my-blog
cd my-blog

# 目录结构
my-blog/
├── _posts/           # 博客文章
├── assets/           # 静态资源
├── templates/        # 页面模板
├── config.yaml       # 配置文件
└── public/           # 构建输出（自动生成）

创建第一篇文章

# 创建文章文件
$EDITOR _posts/2026-01-04-my-first-post.md

文章格式：

---
title: "我的第一篇文章"
date: 2026-01-04T10:00:00+08:00
description: "这是我的博客第一篇文章"
tags: ["博客", "教程"]
categories: ["生活"]
draft: false
---

# 文章内容

## 开始写作

从这里开始你的写作之旅...

本地预览

# 启动开发服务器
gobin serve

# 或指定端口
gobin serve -p 8080

# 启用文件监听和自动刷新
gobin serve --watch

访问 http://localhost:8080 查看你的博客。

构建站点

# 构建静态文件
gobin build

# 增量构建，仅重写受影响的产物
gobin build --incremental --clean=false

# 轻量压缩输出（保守模式）
gobin build --minify

# 包含草稿文章
gobin build --drafts

# 跳过输出目录清理
gobin build --clean=false

# 控制并行页面渲染的 worker 数（0 = 自动，1 = 串行）
gobin build --jobs 4

--minify 当前会对 HTML 和 CSS 做保守压缩，并保留 JavaScript 原始内容，优先保证输出正确性而不是做激进资源改写。

--jobs 控制并行渲染页面的 worker 数：0（默认）按 CPU 数自动选择并封顶为 4，1 强制串行。页面渲染以写入大量小文件为主、偏 I/O 密集，因此默认封顶可在多核机器上获得收益（基准约 15–19%）而不引入高并发下的文件系统竞争退化；如使用更重、更偏 CPU 的模板，可显式指定更大的 --jobs。并行只改变写盘顺序、不改变内容，产物与串行字节级一致，且可与 --incremental 叠加。

使用 --clean=false 时，未变化的静态资源会跳过复制以加快重建。Gobin 会通过资源 manifest 清理上次构建记录过、但本次源目录中已不存在的旧静态资源；未被资源管线管理的输出文件仍会保留。

配置说明

主配置文件（config.yaml）

# 网站基本信息
title: 我的个人博客
description: 专注于技术分享和生活记录
theme: default
languageCode: zh-CN
baseURL: https://example.github.io

# 目录配置
contentDir: _posts
staticDir: assets
# 可选：一起复制到 publishDir 的额外静态目录（保留目录名，如 img -> public/img）
# staticDirs:
#   - assets
#   - img
#   - images
publishDir: public

# 分页配置
paginate: 10
paginatePath: page

# Permalink 配置
permalinks:
  posts: /:year-:month-:day-:title/

# 导航链接
navbarLinks:
  - name: 首页
    url: /
  - name: 分类
    url: /categories/
  - name: 标签
    url: /tags/
  - name: 关于
    url: /about/

# 社交媒体
social:
  github: your-github-username
  email: your-email@example.com

# 功能开关
enableEmoji: true
enableGitInfo: true
enableRobotsTXT: true

# 站点级产物开关（可选）
outputs:
  feed: true
  search: true
  sitemap: true
  robots: true

# 评论系统（可选）
comments:
  enabled: false
  provider: utterances
  utterances:
    repo: "username/repo"
    theme: "github-light"

# Markdown 渲染和代码高亮
markup:
  # 默认关闭 Markdown 中的原始 HTML。
  # 迁移可信旧内容且需要 HTML 片段时，可显式设为 true。
  allowUnsafeHTML: false
  highlight:
    style: github
    lineNos: true

markup.allowUnsafeHTML 默认关闭。显式设置为 true 时，Markdown 中的原始 HTML 会作为活动 HTML 输出，适合迁移完全可信的旧内容；内容来源不完全可信时应保持默认值。

短代码（Shortcodes）

短代码让你在 Markdown 正文里用简短指令生成结构化 HTML，而不必开启全局 allowUnsafeHTML 或手写重复 HTML。语法兼容 Hugo：

形式	说明
{{< name args >}}	HTML 形式，模板输出作为原始 HTML 注入（即使 allowUnsafeHTML: false 也生效）
{{% name args %}}	Markdown 形式，模板输出再经 Markdown 渲染
{{< name >}}body{{< /name >}}	配对形式，正文通过 .Inner 提供

参数支持位置参数与引号命名参数，二者可混用：

{{< youtube dQw4w9WgXcQ >}}

{{< figure src="/img/cover.png" alt="封面" caption="图 1" >}}

{{< highlight go >}}
fmt.Println("hello")
{{< /highlight >}}

内置短代码

名称	参数	用途
figure	src（必填）、alt、title、caption、link	输出 <figure> 图片块
youtube	视频 id（位置或 id=）	响应式 YouTube 嵌入
gist	user、id（位置或命名）	嵌入 GitHub Gist
highlight	语言（位置 0），配对	包裹正文为代码块

自定义短代码

新增或覆盖短代码：在站点 templates/shortcodes/<name>.html 放一个 Go 模板即可（主题作者用 <theme>/layouts/shortcodes/<name>.html）。覆盖优先级为站点 > 主题 > 内置，与模板覆盖规则一致。

模板上下文提供：

• {{ .Get 0 }}：第 N 个位置参数；{{ .Get "key" }}：命名参数（缺失返回空串）
• {{ .Inner }}：配对短代码的正文（已先行展开嵌套短代码；按文本转义，需原始 HTML 用 {{ .Inner | safeHTML }}）
• {{ .Name }}：短代码名称
• 辅助函数：safeHTML、absURL、urlize、default

示例 templates/shortcodes/note.html：

<div class="note note-{{ .Get "type" | default "info" }}">{{ .Inner | safeHTML }}</div>

说明

• 代码围栏（```）与行内代码（`...`）中的短代码语法不会展开。
• 引用未注册的短代码会中断构建并指出文件与名称，便于及早发现拼写错误。
• 选型建议：要输出 HTML 用 {{< >}}，要输出仍走 Markdown 渲染的内容用 {{% %}}。短代码改动会触发增量构建失效与 serve 全量重载。

项目结构

gobin/
├── cmd/
│   └── gobin/          # CLI 入口
├── internal/
│   ├── config/         # 配置管理
│   ├── parser/         # 内容解析
│   └── generator/      # 站点生成
├── templates/          # 默认模板
├── assets/             # 默认静态资源
├── themes/             # 主题目录
├── docs/               # 文档
│   ├── releases/        # 发布说明、更新日志、构建发布指南
│   ├── guides/          # 功能使用指南
│   ├── design/          # 设计文档（specs）
│   ├── plans/           # 实施计划（plans）
│   └── reports/         # 测试报告、阶段总结
├── examples/           # 示例站点
└── scripts/            # 迁移和工具脚本

CLI 命令参考

命令	说明	示例
gobin init [name]	初始化新站点	gobin init myblog
`gobin new <post	page>