Hakuba 中文介绍

[YeungKC]

Hakuba

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

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

点击这里测试有多少快！

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

如何运作的

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

快速开始

推荐使用以下部署服务：

输出文件夹名称为 build

• Vercel
• Netlify
• Cloudflare Pages

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 [email protected]: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 个空格将不会有任何效果。

了解更多: https://mdsvex.com/docs#limitations

自动合并 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

[ZhaoTim]

麻烦问下，我点击文章里的vercel图片，跳转到部署页面，需要填入token和仓库名，仓库名的形式是什么样呢？

[ZhaoTim]

发现部署能继续下去了，但是最后又报了一个错：

No Output Directory named "public" found after the Build completed. You can configure the Output Directory in your Project Settings. Learn More: https://vercel.link/missing-public-directory

[YeungKC]

因为输出的文件夹名字是 build，而不是 public，vercel 貌似默认是 public，这点我加在 readme 一下。

[ZhaoTim]

已经解决了这个问题了，vervel可以配置overwrite文件夹名称，重写以后没问题了，感谢~

[YeungKC]

嗯嗯，不过我想到一个问题，就是 fork 代码还是 clone 代码部署，都存在代码更新问题，需要执行以下操作

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

这样更新可能存在不及时，有些用户使用可能并不关心代码更新。

那么可以选择编写脚本去 clone，build，效果其实一样的。如果你有兴趣写一个，我会在 readme 加上这个示例。

[icantnotfindaname]

這種部署方法的問題在於，Gihtub Discussion 似乎不支持導出之類的功能，是故遷移起來可能會很困難。

[YeungKC]

我写好了 script，只需要执行 yarn generateData 就可以会自动下载好了

[YeungKC]

update，更新到 readme 了

[icantnotfindaname]

萬分感謝，已經成功部署，體驗相當之好。

[shenweiyan]

这个项目真是太棒了，之前看到有一个 Gatsby + GitHub 名为 GG 的项目，好像都有异曲同工之处。

[String10]

补充说明: 如果使用Vercel部署完成后博文下方有An error occurred: giscus is not installed on this repository的报错, 请前往Giscus APP进行配置.