Hugo 博客搭建经验

本地初始操作

1. 下载 git，更新用户名和邮箱信息。
2. 下载 hugo，选 extended。
3. 建文件夹，里面存所有网站的文件夹。
4. hugo new site 名字，会出现一个子文件夹（下称为主文件夹），对应一个网站。
5. 进入，找想要的主题，通过 git clone 或直接复制粘贴的方式放到 themes 文件夹中，最好只有一个主题（实际是可以在配置的 theme 改），然后主题的文件夹名别动。
6. 把主题对应的 exampleSite 内文件复制到主文件夹。
7. hugo 可以编译（生成 public/ 内的网页文件），hugo server 在 hugo 的基础上开了个 localhost 网页以供实时预览，每次运行即可查看效果，随时改（保存）随时更新，不需要“编译”。Ctrl+C 停止。注意，有的时候改风格或页面布局时出现语法问题，就算改回来也会没反应（停留在一个编译错误页面或没有改动效果），这时应当停止再运行。

主题相关（stack）

如果遇到其他主题需求，一个通用方法是，如果想改某些样式或大小或长宽，则找 assets 里 scss 文件；如果想改页面布局，则找 layouts 里 html 文件。具体可以按文件名实际意思找，也可以 F12 出调试工具后找对应的项名字或数值，然后用查找文件内容在主题文件夹里直接暴力找。

1. 注意主题对浏览器页面不同大小的时候做了适配，所以会发现有 respond(…) 这种东西，阈值参见 breakpoint.scss。一般建议改参数（某些距离之类）的时候，顺带各种尺寸情况都改了，然后最后拿手机、平板之类的访问一下看看是否合适。

2. 配置文件应当放在主文件夹中，名字为 hugo.*，后缀可以是 yaml，toml 或 json。建议直接按上面第 6 点，把 exampleSite 的配置文件复制过来，删掉原来的 hugo.toml。下文简称该文件为“配置”。

3. 把配置里的 baseurl 改一下。

4. 多语言选项直接关了完事，配置里 DefaultContentLanguage 改 zh-cn，hasCJKLanguage 改 false，language 删了。

5. 网站图标：配置里 params.favicon。.ico 文件放到 static/ 里。

6. 头像放 assets/img/。

7. 左右边栏最大宽度：grid.css 里 .container&.extended 的 respond(xl) 内。会相应改变中间主题的宽度。

8. 左右边栏与页面左右边缘距离：grid.css 里 .main-container 的 respond(md) 内。

9. 头像大小，头像、博客标题、博客描述居中：sidebar.scss 里 .left-sidebar 的 –sidebar-avatar-size，.sidebar header 的 .site-avatar（其实不改就行）、.site-name、.site-description 内加 text-align: center;。

10. 左右边栏额外两侧空白：sidebar.scss 里 .left-sidebar、.right-sidebar 内额外加 padding-left: ?px; 和 padding-right: ?px; 即可。

11. 左右边栏和中间主体的间距：variables.scss 里 :root 的 –section-separation。

    所以，如果你想真的让左边栏内容完美居中，所要做的就是：把 4 和 7 调成相等，6 的 left、right 不要不相等。

12. 左侧边栏之页面 second method 的高亮：主题文件夹/layouts/partials/sidebar/left.html 里找到这段：

    {{ $currentPage := . }}
    {{ range .Site.Menus.main }}
    {{ $active := or (eq $currentPage.Title .Name) (or ($currentPage.HasMenuCurrent "main" .) ($currentPage.IsMenuCurrent "main" .)) }}
    

    删掉改成：

    {{ $currentPage := . }}
    {{ $siteTitle := .Site.Title }}
    {{ range .Site.Menus.main }}
    {{ $active := or (eq $currentPage.Title .Name) (or ($currentPage.HasMenuCurrent "main" .) ($currentPage.IsMenuCurrent "main" .)) }}
    {{ $active := or ($active) (and (eq $currentPage.Title $siteTitle ) (eq .Identifier "home")) }}
    

13. 目录的行间距：layout/article.scss 里 .widget–toc#TableOfContents 里面有个 margin 后面带四个数的，分别是上边缘、右边缘、每行下方、左边缘。

14. 左侧边栏图标与文字的距离：variables.scss 里 :root 的 –menu-icon-separation。

15. 最后修改时间：https://shitao5.org/posts/hugo-stack/

16. branch 页面的标题形式：在 layout/_default/list.html 里，我是直接把 section-title 注释掉的（因为无论如何它都只会显示章节两字），希望这个自定义的话我也不大会，但是网上好像可以查到？https://discourse.gohugo.io/t/how-can-i-get-a-user-friendly-section-name-title/10880/3

17. 段内行距：variables.scss 里 :root 的 –article-line-height。段间行距：layout/article.scss 里 .article-content 里有个 margin: 1.5em 0;

18. 关于段首缩进：爆了，下面这个方法会导致列表的编号和内容间有过大的距离，应该无解。

    在 layout/article.scss 里 .article-content 里加一句 text-indent: 2em; 这样会发现它缩进过度了。在 variables.scss 里改 –card-padding。

    这里有两个注意点，一个是你发现 F12 之后两侧 padding 变了，这个在不是 layout 里的 article.scss 里 .article-list–tile 的 .article-details 的 padding 改。

    一个是注意到包括标题、图片在内的东西都会被缩进，标题我觉得这样挺好看的，图片的话会导致右侧被遮，这里我的解决方法是用 html 格式的图片，还可以调大小，更好用，唯一可惜的是用不上 stack 自带的图片文字描述下方显示，不过这个也可以写一段 html。

19. 大标题大小：不是 layout 里的 article.scss 里 .article-title 的 font-size。

20. F12 时头像不居中问题：sidebar.scss 里 .sidebar header 的 .site-avatar 的 margin 改成 auto（注意这类 margin 的东西如果不填 0 或 auto，则必须填四个数，分别代表上右下左）。

21. 网站名称颜色：光把 sidebar.scss 里 .site-name 的 color 改掉没用，还要把 left.html 里 site-name 的链接去掉。

22. 文章主题图片的高度：layout/article.scss 里 .article-page 的 .article-header 的 .article-image 的 img 的 max-height。

23. 回到顶部：https://www.blain.top/p/renovation/#%E8%BF%94%E5%9B%9E%E9%A1%B6%E9%83%A8%E6%8C%89%E9%92%AE 配合 https://yelleis.top/p/61fdb627/#%E8%BF%94%E5%9B%9E%E9%A1%B6%E9%83%A8。可以平滑的。

24. 左边栏项过多但不想滚轮：sidebar.scss 里 .left-sidebar 的 max-height。左边栏各项间距：menu.scss 里 #main-menu 的 gap。

25. 归档里 CATEGORIES 不是中文：archives.html 里改 <h2 class="section-title">{{ $taxonomy.Title }}</h2>。

26. 归档的分类卡片大小：list.scss 里 .subsection-list 的 .article-list–tile 的 article 的 width、height。

27. 文章先后（默认按时间）、左侧栏、归档分类等都可以用 md 开头 yaml 里 weight 调优先级。

28. 左侧栏“个性签名”换行：不知为何 \n 会被空格代替，<br/> 没用。我找遍了整个 theme 文件夹只找到一处把换行替换为空格的代码，去掉之后还是没用。所以只能在 left.html 里硬编码了。

29. 归档分类卡片渐变颜色：main.ts 里 articleDetails.style.background。我觉得不改也挺好看。

30. 归档多栏：https://blog.grew.cc/posts/stack#%E5%BD%92%E6%A1%A3%E9%A1%B5%E5%8F%8C%E6%A0%8F。

31. 图标可以在 https://tablericons.com/ 找，放在主题的 assets/icons 里。

32. 关闭 toc 的编号：layout/article.scss 里 li a:first-of-type::before 部分注释掉。

33. 代码行号：配置里 markup:highlight:lineNos。

34. “评论”标题：在 layouts/partials/comments/include.html 的第一二行间加 <h2 style="color: var(--card-text-color-main)">评论</h2>。这样暗色模式不会还是黑的。

35. 如果觉得 ![]() 图片和封面图片糊得不正常且难看，可以把配置里的 imageProcessing 下面两个改成 false。

36. 阅读量：https://hyrtee.github.io/2023/start-blog/#%E7%BB%9F%E8%AE%A1%E5%88%86%E6%9E%90。这里有个问题就是首页的每篇文章的阅读量是无法正常显示的，这个我也不会解决，只能只在具体文章页面显示该阅读量。但是问题在于首页的卡片的 details 和文章的 details 是共用 layout/partials/article/components/details.html 的，就无法区别处理。我的处理方法是复制一份 header.html 和 details.html 然后改一份有统计量的。显然这并不是个简介的解决方案，主要我不会 html 里 partial 情况下的传参。

37. 内嵌 pdf：https://github.com/anvithks/hugo-embed-pdf-shortcode。Better choice：https://bugdrivendevelopment.net/pdf-reader-hugo-sites/，如果希望像我一样在 pdf 下面再显示一个原文件的链接，可以加一行 <a href="{{ .Get 0 }}" style="display:block;text-align:center;"><b>[PDF file]</b></a>。

content 目录结构

1. 博客里的页面分为 branch 和 leaf 两类，branch 就是下面还有子页面的页面。

2. content 文件夹对应 home 页面，是 branch 类型。home 就是主页。

3. content 的文件夹结构与网站链接结构完全对应，一个文件夹一个页面，branch 对应的文件夹下如果有其他 md 或含 index.md 的子文件夹，就会在对应页面也显示出来。

4. content 内所有想要能显示出来的页面，必须要包含 index.md 或 _index.md 文件，前者是给 leaf 用的，后者是给 branch 用的。这个 md 的开头应当有一段 yaml（或其他格式）给出其相关信息。对于 branch，就不用写别的东西了（写了也没用）；对于 leaf，yaml 之后就是正文。

   实际上 leaf 页面可以在 post 或对应的 branch 文件夹里直接放 md，但是最好还是按照上面的习惯来。

   这样的一段 yaml 应当符合 https://stack.jimmycai.com/writing/frontmatter 的格式（有漏，可以看 https://zhuanlan.zhihu.com/p/688275787 里“我的模板”，注意冒号之后必须加空格！复杂字符串如果出问题需要两边打引号！）。特殊地，有几类特殊的布局，可以加上 layout 信息，参见 exampleSite 的 page/。

5. 建议建文件夹 content/page/ 以存放所有出现在左边栏内的页面。所有希望出现在左边栏中的页面（包括 home 的 _index.md 以及 page 的 index.md），它们开头的 yaml 需要额外以 https://stack.jimmycai.com/config/menu 里 first method 的方法写一下。second method 是直接写在配置里的，配合上面第 10 点。

6. 主页的中间，会显示所有属于 content/post/ 里的内容——这是由配置里 params.mainSection 决定的。

7. 除了按上述方式配置的 content/_index.md、post（mainSection 的条目）、page 内 md 外，其余东西一律没有导航界面（包括别的 branch），只能在浏览器上改链接来访问，因此其实可以在博客里“藏”东西。

8. 然后还有一个特殊的文件夹 content/categories，这里面放的东西会和每个文章的分类联系在一起，参见 exampleSite。如果不用这个文件夹，直接写每篇文章的 categories 也是没问题的，就是归档里会没图片。如果用这个文件夹，可以设置 categories 的标签颜色、图片等，而且可以将一个类别的 id 和名称分开来，文件夹名、slug、调用时用 id，title 写名称。

Markdown、KaTeX 相关

无论如何要当心任何位置出现的特殊字符，尤其是 Typora 里没出问题的 \。

1. 支持内嵌 html。
2. 同普通 Markdown，如果两段间不留空行且第一段末尾没有俩空格，则渲染出来是不换行的。
3. 关于列表的分段，Typora 是显示出来一律是分段的行距，但对于从未在标号（或项目点）前退格的列表，源码会不留空行，在网页里是不分段的行距（对比本列表和上一个列表）。这个可能会有点难看，如果介意的话，要手动改一下。另外列表内分段是按照缩进来的。
4. 公式支持 KaTeX 功能（如果没渲染检查一下配置和 frontmatter 里有没有开 math），行间公式上下不留空行也没事。
5. 如果要利用全局 \def，必须使用 \gdef。这个和 Typora 是不一样的，Typora 不识别 \gdef 但 \def 是全局的。
6. 矩阵等多行的东西，需要打三个 \ 后再来个空格，以换行。这个很奇怪。
7. \,、\; 之类的小空格必须改成 \\,、\\;。这个也很奇怪。
8. 表格里公式偷懒不用 \lvert\rvert 直接打 | 时会出现与表格边界混淆的情况（Typora 会自动正确处理），这时要加转义 \。\set 里第一个 | 会被识别为“满足”符号，自动适应左右高度。
9. 公式内星号 *、百分号 % 要加转义 \（Typora 会自动正确处理）。
10. 还有很多不加 \ 就会爆的情况。我遇到最诡异的是 ${a}_{b}{c}_{d}$ 无法渲染。这种是因为垃圾 Markdown 渲染器把公式内外搞混了（两个下划线之间被识别为斜体，一般会出现在 |_（代入值）和 }_ 这种地方）。遇到这种情况反正就在各个特殊字符前试着加 \ 就行。甚至多行推不等式出现多个 > 会识别成引用，无语。
11. 连接自动识别在遇到标点时会有问题，建议还是用 <> 括起来。
12. 撇号如果直接用 ' 会很丑（$’$），必须用 ^\prime。
13. html 格式的图片要居中必须单独写 center。
14. 如果希望强制调整表格列宽，可以用 <div style="width: 宽度"></div>。注意其副作用是在不同宽度的屏幕上可能会显示得不好看。

Github 部署

Github 部署的思路如下：

1. Github 上一个公开的 repo 放网页文件。
2. 每次 hugo 完，把 public/ 内东西放到 repo 里。
3. 如果不想手动操作，可以再建一个（可以私有）放整个博客的 repo，每次 push 之后用 github action 自动编译、更新到网页 repo 里。

由于我想经常调试博客的 theme，而且第三步略麻烦，所以我就是手动更新。

总的操作方法见 https://zhuanlan.zhihu.com/p/568470172（有三篇）。

注意：

1. 网址只能是 github用户id.github.io，github settings pages 里改域名的选项是得自己先买域名的。
2. hugo 编译后，public 里老的文件是会留着的（例如你反复给一篇文章换主题图片，它都会留着）。如果你不希望别人来翻你的 github repo 看到这些，得每次手动删除。
3. 每次把网页复制到本地仓库前，最好先删光（别手动删！git 会自动追踪仓库里的文件，可能会出问题。具体处理方法见下文）。

评论

1. disqus 有广告。
2. giscus 必须登录 github 才能评论。
3. twikoo 似乎有审查。

cusdis 万岁！

免费版 cusdis 一个月 10 条 quick approve 和 100 条需要 approve 的评论（大概就是你得在邮箱的评论通知里点一下），完全够。

upd：但是有个缺点，就是选填的 Email 谁也看不到，而且 reply 也不会通知评论者，相当于没用。

upd：似乎 quick approve 界面可以看到。

操作非常简单：

1. 注册个账号。输入博客网址与 notification 邮箱。
2. 配置里 params 的 comments 的 provider 改成 cusdis，下面 cusdis 里 host 和 id 改一下，具体改的内容看 cusdis 里你的 dashboard 上方的 Embeded Code。
3. 如果想改中文，在 layout/partial/comments/provider/cusdis.html 里 <script async defer src="{{ $host }}/js/cusdis.es.js"></script> 的上面加一句 <script async defer src="https://cusdis.com/js/widget/lang/zh-cn.js"></script>。

Cusdis 的块非常矮，目前我没有找到一个能使块长随着评论数量变化的方法，一个差一点的解决方法见 https://barthpaleologue.github.io/Blog/posts/add-and-customize-cusdis-hugo/。upd：问题已解决，见该博客评论。强迫症会发现暗色模式时底部有一像素高的区域会是纯黑（#121212），这个似乎没法解决。

日常维护

我一般习惯这样：

1. 在另外的文件夹里写博客。

2. 每次手动新建文章文件夹，md 复制过去改名成 index.md，开头加上那段 yaml（我不习惯 hugo new）。yaml 我用的模板：

   title: 
   description: 
   date: 
   slug: 
   image: 
   categories: 
   toc: true
   math: true
   comments: true
   

3. 更新到 github。我写了以下脚本（须在 git bash 下运行，我的博客文件夹和 repo 文件夹并列）：

   cd blog/
   rm public/* -r
   hugo
   cd ../LittleReuben.github.io/
   git rm * -r
   cd ../
   cp -rf blog/public/* LittleReuben.github.io/
   cd LittleReuben.github.io/
   git add --all
   git commit -m "upd"
   git push -u origin main
   

   注意博客网页更新较慢，大概要等个 2min。

我这边发现一个问题：一旦 commit 了过大的文件并 push 失败，这个文件就会永远存在历史记录 .git/object/ 里，导致后续就算删了也无法 push。其实博客这种东西本身没必要记录每次 commit 的 history，但是 git 要删 history 很麻烦，所以我的思路是，直接把整个 *.github.io/ 文件夹删空（包括 .git/），然后重新远程 clone 过来上一个正常的版本。

如果想搭博客也可以直接问我要魔改的 theme。

参考链接

https://thirdshire.com/hugo-stack-renovation-part-two/

https://xrg.fj.cn/p/hugo-stack%E4%B8%BB%E9%A2%98%E6%9B%B4%E6%96%B0%E5%B0%8F%E8%AE%B0/

https://munlelee.github.io/post/hugo%E5%8D%9A%E5%AE%A2-stack%E4%B8%BB%E9%A2%98%E4%BF%AE%E6%94%B9%E7%AC%AC%E4%B8%80%E7%AB%99/

https://zhixuan2333.github.io/posts/ac760353/

https://blog.linsnow.cn/p/modify-hugo/

https://zhuanlan.zhihu.com/p/685991593

https://yelleis.top/p/61fdb627/