翻新博客 (继续使用 hugo)

目录

两年多没更新博客了, 可能现在终于想起 GitHub 的密码了, 但博客可能需要翻新一下.

两年过去了, Hugo 本身已经更新, Mainroad 主题也更新了不少, 之前的设置大部分要重新来过, 所以干脆从头构建博客, 反正也没啥内容. hugo 与 hexo 一样, 都是渲染 markdown 文档, 生成一系列的静态页面. 然后可以选择将生成的页面部署在 Github Pages 等服务上面. Hexo 仍然不考虑, node 那一大坨是真的不喜欢.

安装 hugo

ArchLinux 源里面有比较新的 hugo, 直接安装即可, 其它发行版可以下载 hugo 官方预构建好的二进制文件, go 语言写的程序这点就是棒.

注意: python-pygments 包标记为可选, 但实际没啥需要了, 新版 hugo 内建了 Chroma 作为语法高亮渲染, 已经够用了, 速度也快.

创建站点

# 初始化一个站点
hugo new site sitename.com
cd sitename.com

# 加入版本管理
git init

# 添加主题
git submodule add https://github.com/vimux/mainroad themes/mainroad

主题也可以在 GitHub 上面下载 zip 包解压到 themes 文件夹即可.

简单测试

# 创建 `posts` section 和一篇博文
hugo new posts/hello-hugo/index.md

# 使用任意文本编辑器编辑文章内容
nano content/posts/hello-hugo/index.md

# 测试
hugo server -D -p 8080

在浏览器中访问 http://127.0.0.1:8080 即可测试站点是否工作.

配置

编辑 config.toml:

# 站点名称
title = "hugo site"
# 站点 URL
baseURL = "/"
# 使用 themes/ 中的哪个主题, 注意大小写
theme = "mainroad"

# 中文显示配置
languageCode = "zh-cn"
DefaultContentLanguage = "zh-cn"
enableEmoji = true
hasCJKLanguage = true

# 每页显示多少条博文标题
paginate = "10"

# hugo 发布设置, 发布生成的文件夹路径
publishDir = "../publish"
# 是否清理发布文件夹中多余的文件
cleanDestinationDir = true


# 页面底部的作者信息
[Author]
    name = "姓名"
    bio = "简介"
    avatar = "/res/avatar.png"  # logo

[Params]
    # 站点描述
    description = "hugo site"
    # 版权声明
    copyright = "版权所有"
    twitter_cards = false
    # 使用 继续阅读 功能
    readmore = true
    # 文章底部显示作者信息
    authorbox = true
    # 显示文章目录
    toc = true
    # 显示 上一篇/下一篇博文
    pager = true
    # 博文元数据显示配置
    post_meta = ["author", "date", "categories", "translations"]
    # 主页中显示哪些
    mainSections = ["posts",]
    # 如果觉得 Google 字体导致网站打开太慢, 可以用其它的替代 API
    googleFontsLink = "/res/font/opensans/opensans.css"
    # 自定义 CSS 和 JS
    customCSS = ["/res/css/custom.css"]
    customJS = ["/res/js/custom.js"]

[Params.Logo]
    subtitle = "网站子标题"
    # 此处可以添加网站 Logo, 显示在页面顶部

[Params.style.vars]
    # 页面高亮 (链接等) 颜色
    highlightColor = "#2692ff"

# 使用侧边栏, 可接受: 'left', false, true
[Params.sidebar]
    home = true
    list = true
    single = true
    widgets = ["search", "recent", "categories", "taglist", "social", "languages", "sidemenu"]

[Params.widgets]
    recent_num = 10 # Set the number of articles in the "Recent articles" widget
    categories_counter = true # Enable counter for each category in "Categories" widget
    tags_counter = true # Enable counter for each tag in "Tags" widget

[Params.widgets.social]
    github = "github 用户名"
    email = "邮件地址"

# 在顶部添加菜单栏, weight 决定显示顺序
[menu]
    [[menu.main]]
        identifier = "posts"
        name = "博客文章"
        url = "/posts/"
        weight = 10
    [[menu.main]]
        identifier = "categories"
        name = "所有分类"
        url = "/categories/"
        weight = 20
    [[menu.main]]
        identifier = "tags"
        name = "所有标签"
        url = "/tags/"
        weight = 30
    [[menu.main]]
        identifier = "about"
        name = "关于我"
        url = "/about/"
        weight = 40

自定义

新版的 hugo 和 mainroad 主题已经挺完善了, 之前还需要去修改主题满足我的需求, 这一次我希望尽量不修改主题本身来实现一些自定义.

替换 Google 搜索为 bing 或者其它

通过 customJS 加入的 js 中, 修改搜索框的行为, 监听提交事件, 跳转到 bing 即可. 具体细节可以 F12 查看我的 custom.js 文件.

其它自定义

通过编辑 customCSS 和 customJS 完成, 可以根据个人需要调整.

GitHub CNAME

GitHub CNAME配置:

在 hugo 站点 static 目录下创建 CNAME 文件, 内容是站点的域名.

hugo new 的默认模板

编辑 archtypes/default.md

文章编辑提示

草稿

文章 meta 中的 draft: true 则文章不会被发布, 除非在发布或者测试时指定 hugo -D 选项.

阅读更多分隔符

默认自动提取前面部分字符, 但不是很好用, 我个人喜欢使用 <!--more--> 来分隔预览与全文. 全文仍会包含全面的预览内容.

md 源文件中图片路径包含空格等特殊字符导致渲染错误

图片或者资源名称中有特殊字符, 尤其是空格, 需要使用 URL 编码来转义, 不然无法渲染. 例如: 空格使用 %20 代替.

文章分类和标签设置

在文章元数据区域添加:

categories:
  - "Category 1"
  - "Category 2"
tags:
  - "Test"
  - "Another test"

语法高亮

方法 1: 可以在 md 文档中使用标准的格式, 三个 ` + 语言名称.

方法 2: 使用高级高亮语法, 可以实现行号显示, 行高亮等功能, 参考 官方文档

文章资源管理

我喜欢将文章与资源 (图片/附件等) 放在一起管理, 这样写 md 时轻松一点, 且可以看出资源文件和文章的关系.

例如:

content/posts/post-title/index.md
content/posts/post-title/figure.jpg

这样在文章中可以直接写 figure.jpg 这样的相对路径, 更简洁.