POSTS / Hakuba 中文介绍

Published: 2022-07-24

Updated: 2022-07-29

Hakuba

Hakuba (白馬村 , Hakuba-mura) 位于日本长野县的一个村庄. 如果你享受徒步登山，滑雪等户外活动, 那么这里将会是一个不错的地方。（另外。。。我还没去过 T_T

一个非常快速的博客启动器，通过 Github Discussion 数据驱动。

点击这里测试有多少快！

如果你喜欢这个项目，那么可以 star 或者 fork 它。

如何运作的

Hakuba 会通过 GitHub GraphQL API 拉取 Github Discussion 的数据，并配置 webhooks 实现自动打包部署。

快速开始

推荐使用以下部署服务：

输出文件夹名称为 build

Deploy with Vercel:

…… 或者查看手动部署相关信息

Hakuba 只是一个 Blog 启动器，数据和代码完全分离，所以可以做到创建一个空 repository 编写文章和页面 discussion，再编写相关 script 去 clone 本仓库，build 就部署成功。

这种做法的好处是不需要关心代码更新，只需要专注于数据。

配置

可以通过环境变量或者 Discussion 配置 Blog 信息。

如果通过 Discussion 配置了 Blog，那么标题必须是 index，分类必须是 CONFIG_CATEGORY，这里是一个示例

名称	描述	是否必须	环境变量	Discussion 配置
GITHUB_TOKEN	对于公共仓库，需要 `public_repo` 范围的 token，对于私有仓库，需要 `repo` 范围的 token。	✅	✅	❌
REPOSITORY	目标仓库	✅	✅	❌
CONFIG_CATEGORY	配置文章的分类名称，默认为 `Config`。	❌	✅	❌
POST_CATEGORY	实际文章的分类名称，默认为 `Post`。	❌	✅	❌
PAGE_CATEGORY	页面的分类名称，默认为 `Page`。	❌	✅	❌
PAGE_SIZE	每页显示的文章数量，默认为 10。	❌	✅	✅
BLOG_NAME	博客名称，如果留空，则会从 GitHub 个人资料中获取。	❌	✅	✅
BIO	个人简介，如果留空，则会从 GitHub 个人资料中获取。	❌	✅	✅
EMAIL	联系邮箱，出现在首页的 about 区域	❌	✅	✅
TWITTER	Twitter 帐号，不带 `@`（e.g. SvelteJS），出现在首页的 about 区域	❌	✅	✅
DOMAIN	博客域名，如果留空，则 RSS 订阅将被禁用。	❌	✅	✅
DESCRIPTION	默认 SEO 描述	❌	✅	✅
KEYWORDS	默认 SEO 关键字	❌	✅	✅
COMMENT	是否开启评论，默认开启	❌	✅	✅
LANGUAGE	博客语言，默认为 `en`	❌	✅	✅
TIMEZONE	时区，默认为 `GMT`，请参考 `Date.prototype.toLocaleDateString(locals, options)` 的 `option.timezone`	❌	✅	✅

配置 GitHub Discussion

创建配置、文章、页面的讨论分类，并将其格式设置为 Announcement。

Hakuba 支持 mdx 和 HTML script 标签，因此不要让它们可以被其他人发布编辑 ❗❗❗

只有名为 index 的文章会被视为配置文件。这里是一个示例。

配置 webhook

如果你使用 vercel、netlify 或 Cloudflare Pages, 当 Discussion 发生改动，可以使用 webhooks 自动更新内容。

创建一个新的 Deploy Hook。
前往仓库设置页面设置 webhook。选择 Discussion 事件。

手动部署

Clone 这个仓库，并使用 git 命令进行更新：

git clone git@github.com:YeungKC/Hakuba.git

然后，生成页面：

# 根据你的爱好使用不同包管理器

yarn build
npm run build
pnpm build

最后，将 build 目录上传到你的服务器。

更新代码

如果是 fork 或者 clone 代码的方式，更新代码需要执行一下命令：

git remote add upstream https://github.com/YeungKC/Hakuba.git
git fetch upstream/master
git merge upstream/master
git push origin master

页面和文章额外的配置

页面和文章支持 Markdown front matter，用于配置页面和文章的 SEO meta data 和展示设置。

针对页面的 Front matter

添加的页面会显示在导航栏。

如果你添加的页面标题是 __error，它将会替换默认错误页面，这里有一个示例

名称	描述
lang	页面的 html lang 属性
comment	是否开启评论
priority	页面的优先级
path	页面的路径，默认使用小写的 title
excerpt	为 SEO 配置的页面摘要

针对文章的 Front matter

这里有一个示例

名称	描述
lang	文章的 html lang 属性
comment	是否开启评论
path	文章的路径，默认使用 discussion 的 number
excerpt	为 SEO 配置的文章摘要
title	文章的标题，默认使用 discussion 的 title
published	文章的发布日期，默认使用 discussion 的 publishedAt
updated	文章的更新日期，默认使用 discussion 的 lastEditedAt
timezone	文章的时区，默认为 `GMT`，请参考 `Date.prototype.toLocaleDateString(locals, options)` 的 `option.timezone`

限制

因为使用 Mdsvex 来预处理 Markdown，所以也有以下限制：

在 Markdown 中，你可以使用 4 个空格开始一个代码块。这不是 mdsvex 的特性，因为 XML-based 语言的缩进是常见的。缩进 4 个空格将不会有任何效果。

自动合并 Dependabot 的 PR

这个项目使用了 action-dependabot-auto-merge 自动更新依赖的功能。如果 CI 失败，请尝试配置 Dependabot 的秘钥。

迁移

clone 这个仓库，配置 GITHUB_TOKEN 和 REPOSITORY 环境变量，使用包管理器安装依赖之后执行:

# 选择你喜欢的包管理器

npm run generateData
yarn generateData
pnpm generateData

文章路径在 src/routes/post/_source 下，页面路径在 src/routes/_page 下。

路线图

详情请参考: https://github.com/YeungKC/Hakuba#roadmap

感谢

hexo-theme-cactus，我使用这个主题已经很长时间了，它对 Hakuba 的当前风格有很大的影响。

License

GPL-3.0