主页
文章 标签 分类
主页

目录

博客网站搭建记录

   收录于 hugo  约 1543 字   预计阅读 4 分钟 

选定博客搭建框架

因为所有的笔记都是 markdown + Typora 写的,所以希望找一个要求如下的网站搭建框架

  • [必要]可以根据 markdown 生成或者渲染网站
  • [必要]不能和 Typora 冲突, 搭建对于目录结构以及 *.md 的改动要尽可能地小
  • [必要]因为不是所有的笔记都需要在网站发布, 所以得区分哪些笔记不可以发布
  • [必要]有标签和站内搜索的功能
  • [必要]代码高亮, 有行号
  • [可选]框架使用自己熟悉的语言编写,方便自定义
  • [可选]架构明了,配置简单,一键式部署

最理想的流程是本地使用 Typora 写文档 –> git 同步 –> hugo 展示

综合以上需求, 选定 hugo 作为博客搭建框架

Hugo

Hugo是由Go语言实现的静态网站生成器

安装

安装标准版本

1
2
3
4
5

# 下载二进制文件 https://github.com/gohugoio/hugo/releases
# 解压
tar -zxvf file.tar.gz
# 将 hugo 添加到 path 中
mv ./hugo ~/bin

安装 extended 版本 (优先使用)

[重要]为什么要使用 extended 版本?

在使用部分主题时,会有错误提示: you need the extended version to build SCSS/SASS

1
2
3
4
5
6
7
8
9

# clone hugo
git clone https://github.com/gohugoio/hugo.git
# install hugo extend
cd hugo
go install --tags extended
# check
which hugo 		# output: $GOPATH/bin/hugo
hugo version	# output: hugo v0.87.0+extended darwin/amd64 BuildDate=unknown
# 包含 `extended` 说明版本为 extended version

使用

生成 hugo 站点文件夹

1
2

hugo new site $(site_name)
cd $(site_name)

hugo 站点目录结构

.
├── archetypes 	# 存放生成博客的模版
├── config.toml # 存放 hugo 配置文件 支持 JSON YAML TOML 三种格式配置文件
├── content 	# 存放 markdown 文件
├── data 		# 存放 Hugo 处理的数据
├── layouts 	# 存放布局文件
├── static 		# 存放静态文件:图片 CSS JS文件
└── themes 		# 存放主题

使用主题 loveit

将主题作为子模块添加到 themes 目录

1

git submodule add https://github.com/dillonzq/LoveIt.git themes/LoveIt

也可以使用 git clone https://github.com/dillonzq/LoveIt.git themes/LoveIt，但不推荐，使用 submodule 方便使用 git 管理站点目录

配置

1

cp ./themes/LoveIt/exampleSite/config.toml ./config.toml

配置文件分为三部分: hugo 基础配置, 菜单配置, 主题配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# config.toml
# hugo 全局配置
baseURL = "https://example.com"
defaultContentLanguage = "en"
theme = "LoveIt"
title = "LoveIt"
...

# 菜单配置
[menu]
...

# 参数配置
[params]
...

创建文章

1

hugo new posts/first_post.md

之后会在 /content/posts目录下看到文件 first_post.md，文件最开始的部分被称为 Front Matter

Front Matter

支持 yaml toml json, 默认 yaml, 位于 *.md 的开始

1
2
3
4
5

---
date: "2020-12-26T22:24:23+08:00"
draft: true 	# 草稿状态, true: 默认前端不展示
title: title 	# 标题
---

运行

hugo server

会生成一个 public 目录, 其中包含你网站的所有静态内容和资源

# 包含草稿
hugo server -D 
# 指定配置文件
hugo server --config $(config_file)

Hugo 主题对比

主题市场 https://themes.gohugo.io/

使用 hugo-theme 作为 tag 搜索 github, 以 stars 排序

有几点需要特殊说明

  • wowchemy 比较特殊, 它并不算是主题, 而是提供 site 模板 https://wowchemy.com/hugo-themes/, 可以直接 hugo server, 以 academic 为例, 使用方式如下

     1
 2
 3
 4
 5
 6
 7
 8
 9
10

    # 下载主题
git clone https://github.com/wowchemy/starter-academic.git
cd starter-academic
# 修改对应的 md 目录
cd ./content
mv ./post ./post_backup
ln $(md_dir) post
# 运行 hugo
cd ..
hugo server

  • 部分主题使用 yaml 格式的配置文件, 可以使用在线工具 yaml 转 toml

主题 描述 优缺点
wowchemy-academic 和主流 theme 使用方式不同
PaperMod 不支持国际化
coder 不支持 tag, search, highlight
hugoThemes 一个 hugo theme 集合
even 不支持 search
LoveIt 不再更新, 相似主题可查看 DoIt
stack 以 Front Matter 的方式支持 search, archives

踩坑记录

生产环境下访问 chrome network 存在 wss://livereload 连接失败的问题

nginx 使用以下配置

location / {
    proxy_pass http://localhost:1313;
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location /livereload {
    proxy_pass http://localhost:1313;
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
}

但实际上不推荐这样使用 hugo server,最佳配置为使用 nginx 将 public 目录作为静态服务器的根目录,之后后台启动 hugo server 监控 文件改动, hugo server 不对外通信

修改 scss 无法生效

必须使用 hugo extended 版本

修改 theme.js 无法生效

需要重新生成 min.js

1
2
3
4
5
6

cd /site
npx npm-force-resolutions
# 下载 babel
npm install --save-dev @babel/core @babel/cli @babel/preset-env
# 生成 min.js
npx babel src/js --out-file assets/js/theme.min.js --source-maps
不支持以如下格式展示 mermaid
1
2
3

```mermaid
context
```

解决办法:

  • 在 layouts/partials/assets.html 页面增加 metadata

    <script src="https://cdn.jsdelivr.net/npm/mermaid@8.10.1/dist/mermaid.min.js"></script>

  • 在 layouts/partials/footer.html 页面增加 js

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

        <script>
            // Replace mermaid pre.code to div
            // language-fallback
            const mermaidKeywords = [
                "graph TD",
                "graph TB",
                "graph BT",
                "graph RL",
                "graph LR",
                "sequenceDiagram",
                "gantt",
                "classDiagram",
                "gitGraph",
                "erDiagram",
                "journey"
            ];
            Array.from(document.getElementsByClassName('language-fallback')).forEach(ele => {
                var graphDefinition = ele.innerText;
                if (mermaidKeywords.some((keyword) => graphDefinition.startsWith(keyword))) {
                    eleN = ele.parentElement.parentElement.parentElement.parentElement
                    eleN.parentElement.outerHTML = `<div class="mermaid">${ele.innerText}</div>`
                }
            })
            Array.from(document.getElementsByClassName('language-mermaid')).forEach(ele => {
                ele.parentElement.outerHTML = `<div class="mermaid">${ele.innerText}</div>`
            })
        </script>
gitalk 无法加载

更新 gitalk 版本, 具体操作如下:

  • 修改 assert/data/cdn/jsdelibr.yml

    由

    # gitalk@1.6.2 https://github.com/gitalk/gitalk
gitalkCSS: gitalk@1.6.2/dist/gitalk.min.css
gitalkJS: gitalk@1.6.2/dist/gitalk.min.js

    变更为

    # gitalk@1.7.2 https://github.com/gitalk/gitalk
gitalkCSS: gitalk@1.7.2/dist/gitalk.min.css
gitalkJS: gitalk@1.7.2/dist/gitalk.min.js

  • 修改 lib/VERSION 中 gitalk 版本

  • 下载 gitalk@1.7.2 的 min.js 以及 css 文件并替换 lib/gitalk 的 min.js, css 文件

hugo server 报错 failed to unmarshal YAML

Front Matter 格式不符合要求或者其他错误, 以下为测试结果

字段与值之间没有空格, 例如 draft:true, 正确格式应为 draft: true

hugo server 错误, failed to unmarshal YAML

没有内容, 正文为空

hugo server 错误

没有 date 字段或者 存在空的 date 字段

文章页面存在日期, 但显示 0001-01-01

没有 draft 字段

默认为 false

其他

图标生成网站

https://img.shields.io/badge/Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black

更新于 2021-11-08
阅读原始文档
 hugo, loveit
返回 | 主页