Woodencross's
文章 标签 分类 关于
Woodencross's

个人博客小站建设记录

 收录于  类别 小站纪念墙
     约 3916 字  预计阅读 8 分钟    次阅读     条评论  

一个重要的原因是因为想有一个地方可以自己记录一些东西，而各种现成的平台一是觉得自定义程度不够高，二是内容又会经过层层审核甚至被夹掉，所以到最后就选择了自建一个博客小站。看着小站在自己手中逐渐完善，就好像自己逐渐装修起来一个精致舒适的小屋一样，会真正有一种“属于我”的归属感，这也是这个小站叫做“Woodencross’s Cyber Home”的原因。寄蜉蝣于天地，渺沧海之一粟，希望这个小站能够成为QC在赛博空间里的“锚”。

当然还有一个原因是忙完前一段突然得了点闲，就想折腾了😅。

自建博客当然要先选择一个框架啦，于是Google了一下目前主流的博客框架，再上Github看了一下⭐，Hugo的星最多，那么就决定是你了！

至于Github Pages，白嫖嘛，多是一件美事啊。

由于编译静态网站后文件结构不同，因此在文章的.md中使用相对路径插入图片是行不通的，如下：

posts
    |-article
        |-article.md
        |-img.png

此时在article.md中使用![](./img.png)引用图片会404。

那么正确的图片引用姿势有这几种：

  1. 使用图床，然后引用图片网址。这样的风险就是万一图床挂了或者网址变动就全完了。

  2. 使用绝对路径。Hugo在构建静态网页时会将content/下的文件夹和static文件本身都拷贝到网址之下（应该是基于设定的baseUrl？），所以如果图片是这样放的：

    posts
    |-article
        |-article.md
        |-img.png

    那么在article.md中可以使用![](/posts/article/img.png)来引用图片。

    如果图片是这样放的：

    static
    |-images
        |-img.png

    那么在article.md中可以使用![](/images/img.png)来引用图片。

不过在这个动荡的时代，资源还是自己掌握最好哇！说到这我又想起来以后自己搞一个家用NAS的Flag，想必又是一个大坑……

顺便一提，如果要调整插入图片的位置和大小的话，markdown自身语法支持并不好，而使用html的话Hugo好像支持也不太完善，因此使用Hugo提供的Shortcodes是一个不错的选择，回头专开一章写一写（挖坑不填警告）。

Hugo提供了Shortcodes支持代码块高亮，但是Shortcodes我还没搞明白……

万幸的是，Hugo从v0.60.0开始支持如下写法：

1
2
3

    ```python {linenos=true, hl_lines=[1, "15-17"], linenostart=199}
    //code
    ```

这种写法好像只有goldmark渲染器支持。解释一下大括号中的元素：

  • linenos：布尔值，是否显示行号。
  • hl_lines：需要高亮渲染的行号。
  • linenostart：行号开始显示的值。

PaperMod主题内置了Fuse.js搜索功能，首先需要在config.yaml加入：

1
2
3
4
5

outputs:
    home:
        - HTML
        - RSS
        - JSON # is necessary

之后需要在content/下新建一个search.md（我的是search/_index.md），表示一个新页面，并添加如下内容：

1
2
3
4
5
6
7

---
title: "Search" # in any language you want
layout: "search" # is necessary
# url: "/archive"
# description: "Description for Search"
summary: "search"
---

其中layout: "search"是必要的，它指定了要以“search”的页面结构来渲染这一页。

其实主题作者基本把搜索都给弄好了，但是我一开始傻傻地把.yaml里要加代码的位置搞错了，把outputs加到了param参数下，人家应该在根下自成一个参数的。因此搜索不好使，我还把搜索页面的描述改成了“随时失灵……”。

一开始每篇文章最下面都会有一行分享按钮，我觉得不好看而且实用性不高（都是些Twitter、Facebook啥的），就想给它禁用掉。为此经历了三个阶段：

  1. 在项目内搜索twitter.com，发现themes/PaperMod/layouts/partials/share_icons.html包含这一字段，于是新建layouts/partials/share_icons.html并置为空文件，这样可以覆盖主题里的对应文件。为防止误删我还特意写了一段注释（# 不要删除这段空循环否则后果自负.jpg）。
  2. 可是马上我就发现，可以通过在文章.md的front matter（即前缀）中声明disableShare: true来禁用当前页面的分享按钮，于是我把第一步的空文件删掉，给目前的每篇文章都加上这个声明，并且给archetypes/default.md里也加了一下。这个文件是每次运行Hugo new新建文章时的模板，这样我的新文章也都能不显示分享了。
  3. 一天后，我在翻阅config.yaml时发现一行 
    1

    ShowShareButtons: true
    啊这，难道是【那个功能】！改成false试了一下果然……

大概这就是“认识的波浪式前进与螺旋式上升吧”。

Hogo对评论的支持与主题有关。我用的PaperMod虽然没有内置主题，但是它留下了自定义的接口，既然有接口那可不能浪费了啊。

首先按照PaperMod主题的文档新建一个layouts/partials/comments.html文件，还要修改config.yaml：

1
2

params:
    comments: true

接着按照Hugo的文档去注册一个Disqus账号获得disqus-short-name，这是什么呢？原来Disqus会对我登记的每一个站点生成一个disqus-short-name.disqus.com的管理页面，这个short name就是里面的三级域名，当然这是可以在登记网站时自定义的。

获得short name之后，需要回config.yaml中把它记下来：

1

disqusShortname: disqus-short-name

之后再根据Hugo官方的这个文档，复制里面的layouts/partials/disqus.html到我前面创建的comments.html里（不能改名，这个文件会按名字在layouts/_default/single.html中被调用渲染），之后注释掉里面检测localhost的if语句，就可以本地调试看到评论区出现啦。

PS：disqus.html的内容在Disqus的上手文档里也有提供，好像叫做Universal Code，两者大差不差，区别就是Hugo的代码调用了.Site.DisqusShortname来获取short name而Disqus的代码是直接把short name写在链接里了。

为了防止评论出bug，我还配置了一下disqus_identifier和disqus_url，具体是在comments.html中script一开始加入代码：

1
2
3
4
5

var disqus_config = function() {
    this.page.title = '{{ .Title }}';
    this.page.url = '{{ .Permalink }}';
    this.page.identifier = '{{ .Permalink }}';
};

不过效果如何还有待验证，也可能就是个安慰剂，反正有备无患嘛。

还有，Disqus默认的评论区总感觉有种湾湾风格不知道为啥……回头看看能不能美化一点，或者看别人用的Waline挺好看的说不定换一下。

Push到网站上后才发现Disqus在国内被墙了，还是换一个吧……先试试Gitalk，这是一个基于Github issue的评论服务，正好可以使用网站的公开仓库issue存放评论，官方文档在这里，但是对我来说写的不够傻瓜，于是又在别人的博客上找到了这个。

设置步骤如下：

  1. 在GithubSettings->Developer settings->OAuth Apps中新建一个授权，其中Homepage URL和Authorization callback URL都填主页的地址，并记住生成的clientID和clientSecret。
  2. 更改comments.html为 
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

     <div id="gitalk-container"></div>
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.css">
 <script src="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js"></script>
 <script>
   const gitalk = new Gitalk({
     clientID: '{{ .Site.Params.Gitalk.clientID }}',
     clientSecret: '{{ .Site.Params.Gitalk.clientSecret }}',
     repo: '{{ .Site.Params.Gitalk.repo }}',
     owner: '{{ .Site.Params.Gitalk.owner }}',
     admin: ['{{ .Site.Params.Gitalk.owner }}'],
     id: location.pathname, // Ensure uniqueness and length less than 50
     distractionFreeMode: false // Facebook-like distraction free mode
   });
   (function() {
     if (["localhost", "127.0.0.1"].indexOf(window.location.hostname) != -1) {
       document.getElementById('gitalk-container').innerHTML = 'Gitalk comments not available by default when the website is previewed locally.';
       return;
     }
     gitalk.render('gitalk-container');
   })();
 </script>
  3. 在config.yaml中加入相关参数： 
    1
2
3
4
5
6
7

     params:
   Gitalk:
     clientID: your clientID
     clientSecret: your clientSecret
     repo: "Woodencross.github.io"
     owner: "Woodencross"
     admin: ["Woodencross"]
    并设置 
    1

     comments: true

设置好之后，本地调试的话需要把检测localhost的代码删掉。建议是push到网站上再调试，因为评论需要登陆Github账号。Gitalk会给每一篇文章新建一个issue来存放评论，初始化时需要身份为admin的用户打开文章评论区才会自动新建一个issue。

效果如下：

https://img.woodencross.cn/blog/个人博客小站建设记录-2023-11-20-12-19-48.png
亮色

与主题契合的挺好！美中不足的就是在暗色模式下评论依旧是亮色，有些违和：

https://img.woodencross.cn/blog/个人博客小站建设记录-2023-11-20-12-41-01.png
暗色

只能说还是不够好呀。

同时 @waline/client 还带来了内置的暗黑模式支持。——Waline

于是我又来折腾辣。官方手册在此，这个写的很傻瓜基本上照做就没啥问题。

结束后我的comments.html是这样的：

1
2
3
4
5
6
7
8

<script src="//cdn.jsdelivr.net/npm/@waline/client"></script>
<div id="waline-container"></div>
<script>
    Waline({
      el: '#waline-container',
      serverURL: 'my server URL',
    });
</script>

但是在网站暗色模式下依旧是亮色

https://img.woodencross.cn/blog/个人博客小站建设记录-2023-11-20-12-41-52.png
依旧是亮色

于是来看手册：

通常网站会通过两种方式启用暗黑模式支持:

  • 使用@media选择器通过prefers-color-scheme来根据设备颜色模式状态自动切换
  • 通过修改dom根元素(html或body)的属性与class来动态应用或取消暗黑模式的颜色样式。 如果你在第一种方式的站点上启用Waline，你只需将dark设置为’auto’。 对于第二种站点，你需要将dark设置为令暗黑模式生效的CSS选择器。

首先尝试在Waline()中添加

1

dark: 'auto'

发现无效，说明我的网站应该是第二种情况，那就是说要填一个CSS选择器的名字？继续看手册的例子：

vuepress-theme-hope: 它会在<body>上添加theme-dark class来开启暗黑模式。那么你需要将dark选项设置为body.theme-dark。

在<body>上添加？依照我贫瘠的html知识的指引，我打开了f12开发者模式，并尝试切换主题：

https://img.woodencross.cn/blog/个人博客小站建设记录-2023-11-20-12-42-50.png
亮色主题
https://img.woodencross.cn/blog/个人博客小站建设记录-2023-11-20-12-43-42.png
暗色主题

我超，还真有。于是添加

1

dark: 'body.dark'
https://img.woodencross.cn/blog/个人博客小站建设记录-2023-11-20-12-44-21.png
终于暗了

大功告成！心里终于舒坦了~而且Waline还支持表情，感觉挺不赖，就先用着它了。

相关内容

切换主题——从PaperMod到LoveIt

更改博客目录结构与字体

修改文章post_meta信息

更新于 2023-12-20
阅读原始文档
 Hugo, Github, Disqus, Gitalk, Waline
返回 | 主页