hugo-fixit 收录于 GitHub 和开源项目

2024-04-09 2026-08-28 约 500 字预计阅读 2 分钟 - 次阅读

GitHub Projects Embed | FixIt

apple-devices-preview

在 FixIt 主题中展示你的 GitHub 项目并根据 README 自动生成博客文章。

Demo

特性

支持 GitHub 项目卡片展示（layout 或者 shortcodes）
支持根据 README 自动生成博客文章（content adapter）

要求

FixIt v1.0.0 或更高版本

安装

安装方法与安装主题相同。有几种安装方法，请选择一种。

安装为 Hugo 模块

首先确保你的项目本身是一个 Hugo 模块。

然后将此主题组件添加到你的 hugo.toml 配置文件中：

1
2
3
4
5
6
7
[module]

[[module.imports]]
path = "github.com/hugo-fixit/FixIt"

[[module.imports]]
path = "github.com/hugo-fixit/component-projects/v2"

在第一次启动 Hugo 时，它将下载所需的文件。

要更新到模块的最新版本，请运行：

1
2
hugo mod get -u
hugo mod tidy

安装为 Git 子模块

将 FixIt 和此 git 存储库克隆到你的主题文件夹中，并将其添加为网站目录的子模块。

1
2
git submodule add https://github.com/hugo-fixit/FixIt.git themes/FixIt
git submodule add https://github.com/hugo-fixit/component-projects.git themes/component-projects

接下来编辑项目的 hugo.toml 并将此主题组件添加到你的主题中：

1
theme = ["FixIt", "component-projects"]

配置

最后，为了通过 FixIt 主题在 layouts/_partials/custom.html 文件中开放的自定义块将 component-projects.html 注入到 custom-head 或 custom-assets 中，你需要填写以下必要配置：

1
2
3
4
5
6
[params]

[params.custom_partials]
# ... other partials
assets = [ "inject/component-projects.html" ]
# ... other partials

访问令牌（可选）

获取仓库信息依赖 GitHub 官方 API。在开始使用之前，建议在 GitHub 上生成个人访问令牌，以防止 GitHub API 使用限制。

点击跳到 GitHub 生成 token，选择名为 public_repo 的范围以生成个人访问令牌。
配置环境变量 HUGO_PARAMS_GHTOKEN=your-person-access-token，详细信息请参见 os.Getenv | Hugo

使用

布局

首先，创建 projects.yml 文件并编辑数据：

`1`	`cp themes/component-projects/data/projects.example.yml data/projects.yml`

如果你的网站是多语言的，你可以为英语创建一个 projects.en.yml 文件，为中文创建一个 projects.zh-cn.yml 文件。

接下来，使用 projects 布局创建一个新页面：

`1`	`hugo new projects/_index.md`

编辑新页面的标题和内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
---
title: My Projects
titleIcon: fa-solid fa-laptop-code
subtitle: <https://github.com/Lruihao>
sectionSlot: Some text to display in the section slot which is above the related articles list.
hidden_adapters: false
layout: projects
---

Some text to display at the start of the page.

Shortcodes

在任何页面中使用 gh-repo-card-container 和 gh-repo-card 短代码来显示卡片式 GitHub 存储库：

1
2
3
4
{{< gh-repo-card-container >}}
  {{< gh-repo-card repo="hugo-fixit/component-projects" >}}
  {{< gh-repo-card repo="Lruihao/hugo-blog" >}}
{{< /gh-repo-card-container >}}

内容适配器

🎉 这是一个很棒的功能！它能够根据你配置的项目数据，把仓库的 README 自动生成博客文章。

在项目文件夹中创建 _content.gotmpl，添加以下代码：

1
{{- partial "adapters/projects.html" . -}}

目录结构如下：

1
2
3
4
5
6
content/
├── projects/
│   ├── _content.gotmpl  <-- content adapter
│   └── _index.md        <-- layout: projects
data/
└── projects.yml         <-- projects data

然后，打开 hugo.toml 文件，配置的 projects_adapters 选项，启用内容适配器：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[params]

[params.projects_adapters]
enable = true
only_public = true
categories = []
collections = []
ignore_list = []

[params.projects_adapters.params]
hidden_from_home_page = true
# more font matter here ...

自定义块

你可以通过 define 来实现这些块。

块名称	描述
`projects-aside`	显示在项目页面的侧边栏中
`projects-meta`	显示在项目页面的开始处
`projects-footer`	显示在项目页面的底部处

定时任务

由于采用服务端渲染，所有数据是在构建时获取的，而不会在每次访问时都请求 GitHub API。为了保持数据最新，本组件提供了 cache-projects.yml GitHub Action 工作流模板，用于定时预缓存项目数据到 data/caches/projects.json，Hugo 构建时将优先读取缓存数据，大幅减少构建时间。

配置定时缓存

将工作流模板复制到你的站点仓库：

`1`	`cp themes/component-projects/.github/workflows/cache-projects.yml .github/workflows/cache-projects.yml`

该工作流默认每天 UTC 00:00 自动运行，也可手动触发。它会从 data/projects*.yml 中提取所有仓库，通过 GitHub API 获取仓库信息和 README 内容，然后写入 data/caches/projects.json。

首次运行后 data/caches/projects.json 会被生成并提交到仓库，后续 Hugo 构建将直接读取缓存文件，不再逐个请求 GitHub API。提交缓存文件会自动触发你的站点部署工作流，无需额外配置。

故障排除

本地调试时，可以在 hugo server 命令后加上 --ignoreCache 参数以清除缓存。

Buy me a coffee~

赞赏

支付宝

微信

收录于合集・开源项目 49

临时决定再写一个小工具 - 网站预览图生成器 Lruihao/vercel-gravatar

🐙 Display your GitHub projects in the FixIt theme and generate blog posts from readme.