易于配置的变更日志网站Openchangelog

什么是 Openchangelog ?

Openchangelog 能将您托管在 GitHub 或本地的 Markdown 文件呈现为漂亮的 Changelog 网站。

软件特点:

  • 易于自托管,只需一个配置文件
  • Go 编写 → 轻量级
  • 各种集成,打开问题以请求新的集成
  • 自动 RSS 提要

安装

在群晖上以 Docker 方式安装。

老苏折腾时,最新版本为 0.1.0tags 分为 0.1.00.1.0-litefs0.1.0-sqlite,具体的差异未找到官方的说明;
本文发布时,最新版本为 0.2.1,注意修改对应的 tags

下载镜像

1
2
3
4
5
6
7
8
# 新建文件夹 openchangelog 和 子目录
mkdir -p /volume1/docker/openchangelog/data

# 进入 openchangelog 目录
cd /volume1/docker/openchangelog

# 下载镜像
docker pull ghcr.io/jonashiltl/openchangelog:0.1.0

配置文件

创建一个openchangelog.yml配置文件

因为配置文件中使用了中文,记得用 UTF-8 格式保存

1
2
3
4
5
6
7
8
9
10
11
addr: 0.0.0.0:6001
local:
filesPath: data
page:
title: xxx软件
subtitle: 产品更新说明
logo:
src: https://openchangelog.com/_astro/logo.0TXZ-ydY.svg
width: 30px
height: 30px
link: https://laosu.tech
  • addr:侦听的地址和端口
  • filesPath:指定包含 Changelog Markdown 文件的目录的本地文件路径
  • title:标题显示在所有 Changelog 文章上方
  • subtitle:子标题,显示在标题下方
  • logologo 标志显示在页眉中

关于配置的更多的详细说明,可以参考官方文档:https://github.com/JonasHiltl/openchangelog#configuration

示例文件

文件名格式

变更日志文件的排序按文件名降序排列。建议在文件前面加上发布版本号

1
{version}.{title}.md

老苏准备了 2 个文件,分别是 v0.0.1.xxx.mdv0.0.2.xxx.md

内容格式

变更日志以 Markdown 编写,符合 Openchangelog 符合 CommonMark 0.31.2 规范

可以使用 Frontmatter 指定

  • title:以粗体标题显示在变更日志文章的顶部
  • description:显示在标题下方
  • publishedAt:采用 ISO 8601 格式,显示在变更日志文章旁边

v0.0.1.xxx.md 的内容如下:

1
2
3
4
5
6
7
---
title: xxx软件
description: 这是发布的第一个版本
publishedAt: 2024-08-31
---

第一个版本

v0.0.2.xxx.md 的内容如下:

1
2
3
4
5
6
7
---
title: xxx软件
description: 这是发布的第二个版本
publishedAt: 2024-09-01
---

第二个版本

docker cli安装

如果你熟悉命令行,可能用 docker cli 更快捷

1
2
3
4
5
6
7
8
# 运行容器
docker run -d \
--restart unless-stopped \
--name openchangelog \
-p 6001:6001 \
-v $(pwd)/openchangelog.yml:/etc/openchangelog.yml:ro \
-v $(pwd)/data:/app/data
ghcr.io/jonashiltl/openchangelog:0.1.0

docker-compose 安装

也可以用 docker-compose 安装,将下面的内容保存为 docker-compose.yml 文件

1
2
3
4
5
6
7
8
9
10
11
12
version: '3.8'

services:
openchangelog:
image: ghcr.io/jonashiltl/openchangelog:0.1.0
container_name: openchangelog
restart: unless-stopped
ports:
- "6001:6001"
volumes:
- ./openchangelog.yml:/etc/openchangelog.yml:ro
- ./data:/app/data

然后执行下面的命令

1
2
3
4
# 将 docker-compose.yml 和 openchangelog.yml 放入 openchangelog 根目录

# 一键启动
docker-compose up -d

运行

在浏览器中输入 http://群晖IP:6001 就能看到主界面

右上角可以通过 feed 订阅,来跟踪软件的版本变更

参考文档

JonasHiltl/openchangelog: Easy to configure & self hostable Changelog Website
地址:https://github.com/JonasHiltl/openchangelog

Markdown to a beautiful Changelog Site | Openchangelog
地址:https://openchangelog.com/

CommonMark
地址:https://commonmark.org/