翻新博客 (继续使用 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 文件.

其它自定义

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

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 这样的相对路径, 更简洁.