折腾半天,终于把博客迁移过来了。记录下来,对自己提个醒,说不定有初学者也会犯这样的错误

注意,这并不是一篇从零开始使用 Hugo 的教程,而是 Troubleshooting,意味着内容直接奔着问题

环境配置

系统:Windows10 64bit
Hugo 版本:0.8.1
安装方式:Binary
部署方式:Vercel

关于配置文件 config.yml

配置文件格式不唯一,且能用工具互相转换yml<->toml<->json

如果主题有 i18n 文件夹,博客指定为中文会比较好,可能是个别情况,我的主题 i18n 文件夹下的中文翻译文件是cn.yml,设置后会在博客的 HTML 标签里加上lang=cn,然而这并不符合直觉(没有说不符合规范是因为真正的规范好像并没有人去遵循,链接),由于文件要求严格小写,所以最好改成zh-cn.yml,然后网站配置文件中加上defaultContentLanguage: "cn"即可。

如果网站开了阅读时间显示(比如ShowReadingTime: true),而所有中文文章阅读估计时间都显示为「1 分钟」(阅读时间显示错误),可能你正在使用非中文博客主题,并没有统计中文文字,配置文件加上以下即可。

hasCJKLanguage: true
isCJKLanguage: true

配置文件的缩进代表层级,普通人可能不知道,这里需要注意配置项的层级关系。

params:
    hidemeta: false 
//比如params下的false可配置项
hidemeta: false
//这里就是一个错误示范

日期的格式配置比较特殊,一定要按照月日数字从小到大,年为 2006 来配置,比如2006-01-23,其中年月日的整体顺序可变,比如January 2, 2006,日期之间用什么连接都行2日Jan月2006年这种都可以。

由于著名的高亮脚本 Highlight.js 需要额外加载,所以我使用了 Hugo 自带的高亮功能,见「Configuration-markup」,支持的高亮语言简写,见「list-of-chroma-highlighting-languages」,大多数人应该知道,在代码块开头/```/加上语言简写即可。

关于网站文件夹

除去博客主题文件夹外,结构一般是这样子的

  config.yml

├─archetypes
      default.md
├─content
    about.md
  └─post
          10.md
├─data
├─layouts
├─public
├─static
      favicon.ico
      markmap.mm.md

archetypes 下的 default.md 是默认模板,为了以后方便,查看自己的博客主题文档后修改一下,以后写文章就能直接hugo new 文件名.md来新建文章了。或你自己建一个文章默认模板 post.md 并用hugo new --kind post 文件名.md来新建文章。

关于新建文章,你的博客主题没有什么特殊要求的话:

hugo new Alice.md
//在content根目录下创建 Alice.md同时页面/文章网址是 https://example.org/Alice/
hugo new /posts/Bob.md
//在content/posts下创建 Bob.mb同时地址是https://example.org/posts/Bob

如对路径有其他要求,见「Ugly-urls」
如果已经在配置中写明,或者默认值已设定的,仍然对单独文章特殊化,例如如果配置文件里comment值为true或者没写出但默认为true的,可以在页面头部进行特殊化。

title: "博客转移至 Hugo后的踩坑总结"
date: 2021-09-10T12:38:20+08:00
comment: false

static 文件夹内文件/子文件夹则是网站生成后直接加入的。比如网站图标。

关于博客主题文件夹

一般博客的主要文件夹比如是这样

├─assets
  ├─css
    ├─core
          reset.css
          ...
    
    └─extended
           blank.css
  
  └─js
          fastsearch.js

├─i18n
      en.yaml
      zh-cn.yaml

└─layouts
      404.html
      robots.txt
    
    ├─partials
        anchored_headings.html
        ...
      └─templates
              opengraph.html
    
    ├─shortcodes
          blockquote.html
          ...
    └─_default
        └─  archives.html
         ...

文件夹 assets 里新增样式和脚本文件能不写死就不要写到核心文件里,比如我用的主题可以自己在 extended 文件夹下添加额外的 custom.css 样式文件,如不支持,也可以在网站文件夹 static 下放置后写在主题模板里引用。i18n 在上面已讲过不多说,layouts 存主题模板,如果要添加一些字符的话也是尽量不要写死,比如我要自定义网站底部信息,那我就在\layouts\partials\footer.html里找位置添加变量{{ .Site.Params.footerinfo }},然后网站配置文件这样:

params:
    footerinfo: 版权所有,禁止转载

但是在 js 里直接写变量无效,见变量

关于 Hugo 命令行

生成静态网站时压缩需要用hugo --minify,不要以为config.yml里面写了minifyOutput: true就会自动输出压缩好的文件。

虽有一键hugo deploy,但是不支持 Vercel 非常遗憾,所以有以下几种方法部署到 Vercel(其他不推荐)

  • 生成的 Public 静态内容——>Github 仓库——>Vercel
  • 生成的 Public 静态内容——>Vercel
  • 网站文件夹——>Github——>Vercel(Hugo)
  • 网站文件夹——>Vercel(Hugo)

网站文件夹的区别在于,是上传整个文件夹后在云端自动构建后部署。我使用的是 Public 文件夹直接上传 Vercel,上传比较快,需要安装 Vercel-cli,且正式上线要目录下vercel --prod,零碎的命令行我就写到 cmd 脚本里了。

其他注意事项

如果是大幅修改过主题模板,建议下一个文件对比工具(比如 Winmerge)与原版对比,保留记录。等原主题更新后可以有条理的重新修改。

为了本地对文章进行分类,我的文章文件夹结构是这样的:content/post/year/title.md(别人可能是 posts)但是我又想保持原来 Gridea 的文章路径怎么办呢?在配置文件中这样写:

permalinks:
  post: /post/:title/
# see https://gohugo.io/content-management/urls/#permalinks

于是,本地结构与网站文章路径至此不同。