前言

  元旦的时候回家看 Houdini 的教程。
  看的过程中萌生了一个想法，始终挥之不去。
  那就是能否做一个网站，将 Houdini 的知识点全部总结归纳起来。
  这样就可以将视频的知识和 Houdini 的节点连接起来。
  让 Houdini 复杂的知识脉络更加清晰。
  越是看教程，这个想法越是强烈，以至于教程都看不进去了(:з」∠)。

  所以为了实现这个效果，就开始在网上查阅有没有好的文档制作工具。
  在使用 Maya 的 C++ 文档的时候，体验过每个函数都能够自动生成链接到案例的标签。
  找相关联的案例就非常方便。
  我也希望能够制作一个 HoudiniWiki 的网站实现类似的效果。

  开始是在网上找相关的文档生成工具，我之前也有做过 基于 Docsify 前端技术来生成文档网站 链接
  但是 Docsify 无法做到将关联的信息自动生成出来，只能手动添加。

  于是到头来我还是想到了 Hexo ，毕竟 Html 模板还是有很多操作可以坐上去的。
  但是 Hexo 相关的文档主题就很少，唯一找到一个比较完善的文档博客 链接
  但是要实现我上面说的效果还是差了点。

  于是又去找，找着想起了当时 Hexo 太重想换 Hugo 的时候， Hugo 也有很多主题，说不定就有我想要的 文档 主题。
  于是我就去尝试 Hugo 的主题，才发现 Hugo 果真有我想要的东西 链接

  我找到了几个不错的文档主题 docport Zdoc Learn
  我想让我的文档网站支持的侧边栏的收缩，当时使用 Docsify 的时候也为这个问题纠结了好长一段时间。
  最后也没有什么好的方案，所以这次选主题也重点参考了这点。

  后来使用 ZDoc 文档的时候找到 Github 作者，发现他还做了一个 Zzo 的主题。
  这个主题可就厉害了，里面整合了很多前端技术，借助 Hugo 只需要用 markdown 的编写即可方便

  为了将 Zzo 有的功能集成到 ZDoc 里面，我又花了很长的时间进行缝合，为此推荐 Youtube 上的一款教程 链接

  另外推荐 Hugo 比较有用的网站

Hugo 下载 & 使用

官方文档教程

  上面是官方教程链接，操作过程首先要去下载 Hugo.exe 可执行文件。
  Github 的 Release 是一个不错的选择 链接
  windows 下推荐下载 extend 的版本，虽然大小会大很多，同时会囊括更多的功能。

alt

  下载之后给 Hugo.exe 配置环境变量就可以在任意路径访问它了~

  Hugo 是个命令工具，简单的使用可以参照官方文档
  使用 Hugo new Site SiteName 创建一个 Hugo 生成目录
  然后在 themes 目录下 clone 一个 Hugo 主题的仓库
  修改 config.toml 的主题指向。
  在 content 目录下添加 md 文件。
  完成这些操作之后就可以直接在命令行输入 Hugo 命令生成网站了。
  当然也可以使用 Hugo server 部署一个本地服务器，在本地查看和更新网站。

  下载的主题如果想要直接查看网站的显示效果，可以跳转到 exampleSite 目录，然后使用命令行 Hugo server --themesDir ../..
  可以直接预览主题内置的网站效果。

  最后 Hugo 生成的时候可以使用 Hugo --minify 命令将网站全部压缩到最小状态
  Hugo 工具还有很多命令，其实日常根本不会用到，可以无需了解。

HoudiniWiki 文档构建

  了解了 Wiki 之后我就可以根据上面找到的主题进行去构建属于我自己的 Wiki 网站了。
  但是只是到这个程度还不及我的预期，我想要的效果正如上面所说的，想要将 Zzo 和 ZDoc 两个主题结合到一起。

Hugo Templates

  之前有接触过 Hexo 的 ejs 和 pug
  Hugo 则是直接使用 html ，可以通过 大括号 标记嵌入 Go 语言的相关逻辑。
  Hugo 内置了相关的 变量 和 方法进行操作。

  比如我魔改 HoudiniWiki 的时候，想要自定义 image 的渲染方式，让它自动识别 markdown 的 image 渲染并转为 video 标签。(只不过这个方案因为破坏了 Markdown 的语意，不便于文章迁移，所以作罢了)

  我可以在 layouts/_default/_markup/render-link.html 这个路径创建 html 文件，关于 Markdown Render Hooks 可以参考文档 链接

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<!-- 将视频格式的后缀制作成 Go 数组 -->
{{ $exts := slice "wmv" "asf" "asx" "mpg" "mpeg" "mpe" "rm" "rmvb" "mpg" "mpeg" "mpe" "3gp" "mov" "mp4" "m4v" "avi" "dat" "mkv" "flv" "vob"}}
<p class="md__image">
  <!-- 参考 Markdown Render Hooks 的文档 .Destination 是 ![alt](url) 是 url 的部分 -->
  <!-- 判断当前链接是否是视频的后缀 -->
  {{$destination := .Destination }} 
  {{$isVideo := false }} 
  {{ range $exts}}
    {{ if strings.HasSuffix $destination . }}
      {{$isVideo = true }} 
    {{ end }}
  {{ end }}
  
  {{$url := .Destination | default "" }}
  <!-- 如果是视频后缀用 video | 不是则 img -->
  {{if $isVideo}}
    <video src="{{ $url }}" autoplay="autoplay" loop="loop" style="width: 100%; height:100%;"></video>
  {{ else }}
    <img src="{{ $url }}" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}" {{ end }} />
  {{ end }}
</p>

  以上就是 Hugo templates 的一个简单案例，采用 Go 和 html 混写生成的模式。
  让 HTML 带有了逻辑语句功能，目的和 ejs 或是 pug 是一致的，但是 Hugo 还能实现 Markdown 特定的 hook ，这个功能更为方便。

Hugo shortcodes

  shortcodes 是文章里面调用 Go 写好的模板，可以让 Markdown 的写作更为便利。
  hexo 也有 Tag Plugins 的玩意，实现效果是差不多的，不过我还从来没有研究过。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{{< columns >}} <!-- begin columns block -->
# Left Content
Lorem markdownum insigne...

<---> <!-- magic separator, between columns -->

# Mid Content
Lorem markdownum insigne...

<---> <!-- magic separator, between columns -->

# Right Content
Lorem markdownum insigne...
{{< /columns >}}

  比如上面的写法，通过 大括号 标记 markdown 的入口，然后将相关的 markdown 填入到分割符对应的位置。
  就可以根据提供的 shortcode 模板生成页面。

alt

Hugo taxonomies

  Hugo 支持自定义分类。这个比 Hexo 要好， Hexo 要实现这个功能只能借助社区提供的插件。
  具体可以 Hugo 的文档 链接

1
2
3
4
[taxonomies]
  category = "categories"
  series = "series"
  tag = "tags"

  在配置文件里面配置这些分类标签之后，就可以在文章的 front-matter 里面添加相关的标记。

1
2
3
4
5
6
7
8
9
10
11
12
categories:
- Development
project_url: https://github.com/goHugoio/Hugo
series:
- Go Web Dev
slug: Hugo
tags:
- Development
- Go
- fast
- Blogging
title: 'Hugo: A fast and flexible static site generator'

  Hugo 会根据这些标记生成汇总页面。

  Hugo 有 Related 可以根据一定的权重比例生成关联文章的数组 文档
  Hexo 官方并没有提供这个功能，不过也可以通过 js 写一个，比如我现在这个主题就是自己写的，文章末尾会自动生成相关文章的推荐。

1
2
3
4
5
6
7
8
9
10
11
12
[related]
  includeNewer = false
  threshold = 80
  toLower = false

  [[related.indices]]
    name = "keywords"
    weight = 100

  [[related.indices]]
    name = "date"
    weight = 10

  相比较之下，Hugo 提供的功能更为方便且高效。

Hugo 于 Hexo 比较

  Hugo 的主题比起 Hexo 数量和质量都差了很多。
  并且 Hugo 扩展插件很麻烦，最近的新版本开始支持 Go 语言写扩展了，但是还是需要有 Go 开发的背景。
  而 Node.js 很多前端都会使用，相较于 Go 的混写， Hexo 显然更受欢迎。
  不过 Hugo 最大的卖点生成高效也的确是当之无愧。

  我思考在三，在文档生成领域里面的确 Hexo 这方面还是一片空白。
  相比较之下使用 Hugo 会更方便，博客方面的话就不打算迁移了，文章很多，迁移过去的代价有点大。
  现在用的主题经过我一点点的魔改，都不敢升级了(:з」∠)

Github Actions CI 网站自动部署

  很找就看到过有人用 Github 的 Actions 自动部署 Hexo 博客。
  而我目前走的方案还是沿用 hexo 官方提供的 deploy 部署，虽然效率比较低，但是好在管用。
  后来知道部署 QBinder 才开始稍微接触了一点 Github 的 CI 功能，的确是挺香的。
  于是这次 Hugo 的部署我就深入使用了 Github 的 Action CI。

  经过了我多次 push 测试之后，这是目前我走 CI 流程的配置文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
name: github pages

# 触发条件 | 每次 push 自动触发
on:
  push:
    branches:
      - master  

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      # 拉取仓库到 服务器上 这个是 Github 自带默认配置的
      - uses: actions/checkout@v2
        with:
          # 下面是基于 Hugo 部署仓库推荐的操作流程 https://github.com/peaceiris/actions-hugo
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
      
      # NOTE 跑 python 脚本生成 links.json 数据供 Hugo 调用
      - name: collect links.json
        run: python ${{ github.workspace }}/content/collect_link_data.py

      # 配置 服务器 Hugo 环境 | 直接调用别人做好的 actions
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      # 运行 Hugo 生成网站
      - name: Build
        run: hugo --minify

      # 将网站部署到 Github Pages 上 | 直接调用别人做好的 actions
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs
        
      # 部署 ssh Key | Github 将隐私数据通过 secrets 插入
      - name: Install SSH Key
        # You may pin to the exact commit or the version.
        # uses: shimataro/ssh-key-action@6f350ca8484d8d55c2e361e74d17e638dabe713a
        uses: shimataro/ssh-key-action@v2.1.0
        with:
          # SSH private key
          key: ${{ secrets.SERVER_SSH }}
          known_hosts: ${{ secrets.SERVER_SSH_PUB }}
          name: blog
          config: |                                         # will be appended!
            Host HoudiniWiki
              HostName ${{ secrets.SERVER_IP }}
              User git
              IdentityFile ~/.ssh/blog
          
      # 部署 ssh Key 就可以让服务器直接连接到我私人服务器的 HoudiniWiki 仓库了
      # 由于上面的 python 脚本生成了多余的数据，需要让仓库的修改全部放弃，然后将 仓库 gh-pages 分支同步到我服务器上的仓库上
      # 最后我在自己的服务器仓库上配置 Git 钩子，接受 push 就 checkout 数据到静态页面挂载的目录，实现网站 push 自动更新
      - name: push repo
        run: | 
          git remote add server git@HoudiniWiki:/home/git/repos/HoudiniWiki.git 
          git reset
          git checkout .
          git clean -fdx
          git checkout gh-pages
          git pull origin gh-pages
          git push server gh-pages

  其实 CI 配置就是指挥 Github 服务器的操作手册，上面的脚本可以让我 push 之后自动生成网站并且直接部署到我的个人服务器上。
  写法其实挺清晰的，而且编写界面还有别人写好的开源 CI ，可以直接套入使用。

alt

  不过刚开始总是出现各种配置错误，所以要 push 好几次才把流程跑通。

总结

  目前 HoudiniWiki 已经部署了，大家有兴趣可以访问 hou.l0v0.com 访问。
  目前网站的骨架基本架设好了，后续我还要多去看 Houdini 的教程，将内容填充进去。
  我以前也将一些 Houdini 的教程整理写在博客里，就不删除了，到时候会将教程重新看一遍。
  然后将所有的知识点重新写文章总结一波。

  近期会集中精力完善，所以博客大概会停更一段时间了~