POSTS / Hakuba 中文介绍

Published: 2022-07-24
Updated:   2022-07-29

Hakuba screenshots

Hakuba

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

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

点击这里测试有多少快!

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

如何运作的

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

快速开始

推荐使用以下部署服务:

输出文件夹名称为 build

Deploy with Vercel:
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

如果你使用 vercelnetlifyCloudflare 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 个空格将不会有任何效果。

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

自动合并 Dependabot 的 PR

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

迁移

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

# 选择你喜欢的包管理器

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