技术的路上奔跑

入门

0%

hugo搭建笔记

发表于 更新于 分类于 ， Valine：
本文字数： 7k 阅读时长 ≈ 6 分钟

一、安装

1. 首先安装golang

2. 安装hugo

1
2
3
4
# 标准版
go install github.com/gohugoio/hugo@latest
# 扩展版
CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest

3. 将$GOPATH/bin加到PATH中

二、配置

1. 初始化工程

1
2
# --force 在非空目录创建
hugo new site /path/to/site

2. 安装皮肤

1
git submodule add https://github.com/alex-shpak/hugo-book themes/book

2.1. 类似gitbook的主题 hugo-book

https://github.com/alex-shpak/hugo-book

  • 使用时先将exampleSite里面内容拷贝到项目根目录
  • 剩下的自己diy吧

3. 本地调试

1
2
#  --disableFastRender 重新生成页面，不使用缓存
hugo server --theme book --disableFastRender

4. 生成静态页面

  • 直接执行，会生成在工程目录的public下面
1
2
#  --cleanDestinationDir 重新生成页面，清空目录
hugo --cleanDestinationDir

三、个性化配置

1. 页面内跳转

1
2
3
# 查看当前配置
=> hugo config | grep -i relative
relativeurls: true

1.1. 使用相对路径

  • 需要在config.yaml添加relativeurls: true
  • 使用hugo server是不会生效的，但是使用hugo生成的页面会生效

1.2. 使用绝对路径

  • 同上，设置relativeurls: false
  • 并且要设置baseURL: https://githubwyb.github.io/
  • 重新生成即可

2. latex支持

  • 使用katex进行latex支持
  • 先下载https://github.com/KaTeX/KaTeX/releases
  • 解压后拷贝katex到项目的static/lib/katex中
  • 拷贝主题里面的layouts/partials/docs/html-head.html到项目根目录的layouts/partials/docs/html-head.html
  • 在模板文件html-head.html中添加以下代码，同样实现了行内的解析
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<link rel="stylesheet" href="/lib/katex/katex.min.css">
<script src="/lib/katex/katex.min.js"></script>
<script src="/lib/katex/contrib/auto-render.min.js"></script>

<script>
  document.addEventListener("DOMContentLoaded", function () {
    renderMathInElement(document.body, {
      delimiters: [
        { left: "$$", right: "$$", display: true },
        { left: "$", right: "$", display: false }
      ]
    });
  });
</script>

注意

想要使用换行，需要使用\\\\换行，使用\\不行

3. 添加静态文件

将文件放到static目录下面就可以直接添加到生成的文件里面

4. plantuml支持

参考 在hugo博客里面使用plantuml

  • 加快速度就下载https://cdn.jsdelivr.net/gh/jmnote/plantuml-encoder@1.2.4/dist/plantuml-encoder.min.js
  • 放到/static/lib下面
  • 拷贝主题里面的layouts/partials/docs/html-head.html到项目根目录的layouts/partials/docs/html-head.html
  • 将下面的代码放到html-head.html里面
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
{{ if or .Page.Params.plantuml .Site.Params.plantuml }}
<!-- PlantUML -->
<script src="/lib/plantuml-encoder.min.js" integrity="sha256-Qsk2KRBCN5qVZX7B+8+2IvQl1Aqc723qV1tBCQaVoqo=" crossorigin="anonymous"></script>
<script>
document.addEventListener("DOMContentLoaded", function(){
  let plantumlPrefix = "language-plantuml";
  Array.prototype.forEach.call(document.querySelectorAll("[class^=" + plantumlPrefix + "]"), function(code){
    let image = document.createElement("IMG");
    image.loading = 'lazy'; // Lazy loading
    image.src = 'http://www.plantuml.com/plantuml/svg/~1' + plantumlEncoder.encode(code.innerText);
    code.style.display = 'none';
    code.parentNode.style = 'text-align: center; margin: 0; padding: 0; background-color: transparent;';

    {{ if .Page.Site.Params.fancybox }}
    // 对图片添加fancybox
    let div = document.createElement("DIV");
    div.className = "post-img-view";
    let a = document.createElement("A");
    a.setAttribute("data-fancybox", "gallery");
    a.setAttribute("href", image.src);
    a.appendChild(image);
    div.appendChild(a);
    code.parentNode.insertBefore(div, code);
    {{ else }}
    code.parentNode.insertBefore(image, code);
    {{ end }}
  });
});
</script>
{{ end }}
  • 全局开启就在配置config.yaml中添加
1
2
params:
  plantuml: true
  • 单个页面开启就在页面头部添加
1
plantuml: true

5. fancybox 图片添加放大效果

参考 Hugo 使用 Fancybox 实现图片灯箱/放大功能

  1. 下载下面几个文件，放到/static/lib/fancybox下面
  • https://cdn.jsdelivr.net/npm/jquery@3.5.1/dist/jquery.min.js
  • https://cdn.jsdelivr.net/gh/fancyapps/fancybox@3.5.7/dist/jquery.fancybox.min.css
  • https://cdn.jsdelivr.net/gh/fancyapps/fancybox@3.5.7/dist/jquery.fancybox.min.js
  1. 复制一份themes/book/layouts/_default/_markup/render-image.html到layouts/_default/_markup/render-image.html
  2. 编辑layouts/_default/_markup/render-image.html
1
2
3
4
5
6
7
8
9
10
11
12
<!-- 找到下面一段 -->
<img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title }}title="{{ . }}"{{ end }}/>
<!-- 修改为 -->
{{- if .Page.Site.Params.fancybox }}
  <div class="post-img-view">
  <a data-fancybox="gallery" href="{{ .Destination | safeURL }}">
  <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}"{{ end }} />
  </a>
  </div>
{{- else }}
  <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title }}title="{{ . }}"{{ end }}/>
{{- end }}
  1. 复制一份themes/book/layouts/partials/docs/html-head.html到layouts/partials/docs/html-head.html
  2. 编辑layouts/partials/docs/html-head.html，末尾追加
1
2
3
4
5
{{if .Page.Site.Params.fancybox }}
<script src="/lib/fancybox/jquery.min.js"></script>
<link rel="stylesheet" href="/lib/fancybox/jquery.fancybox.min.css" />
<script src="/lib/fancybox/jquery.fancybox.min.js"></script>
{{ end }}
  1. markdown中引入图片需要使用<img src="imgs/1.png" />，使用img标签不支持
  2. 重新生成看效果

6. 代码块格式

  • 配置如下config.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Needed for mermaid/katex shortcodes
markup:
  highlight:
    # lineAnchors: ""
    # anchorLineNos: false
    codeFences: false         # 是否使用代码围栏，默认true，不使用将没有行号高亮等风格
    guessSyntax: false        # 不标识代码类型，不自动猜测，默认true
    # hl_Lines: ""            # 高亮的行号，一般不设置，每个块应该都不一样，不需要统一
    lineNoStart: 1            # 行号开始于1，默认1
    lineNos: true             # 是否显示行号，默认false
    lineNumbersInTable: false # 是否以表格<tr>的形式展示行号，false使用<span>，表格方式行号好像有问题，默认true
    # noClasses: true
    # noHl: false
    style: dracula            # 代码高亮主题，参考 https://xyproto.github.io/splash/docs/all.html
    tabWidth: 4

7. 右侧文章大纲配置

1
2
3
4
5
6
# Needed for mermaid/katex shortcodes
markup:
  tableOfContents:
    ordered: false    # 是否添加序号，默认false
    startLevel: 1     # 展示的开始级别，默认1
    # endLevel: 3     # 结束级别，默认3

四、主题配置

1. hugo-book

1.1. 目录树

  • 需要目录下存在_index.md才会呈现树状，否则就是平铺
  • _index.md头部配置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
---
# Set type to 'docs' if you want to render page outside of configured section or if you render section other than 'docs'
type: 'docs'
# Set page weight to re-arrange items in file-tree menu (if BookMenuBundle not set)
weight: 1
# true就是不和同级的文档在一起，单独形成一个节点，虽然属于父级可折叠，但是展开后和父级效果一样
bookFlatSection: true
# 此目录是否可以折叠，右边是否显示三角
bookCollapseSection: true
# (Optional) Set true to hide page or section from side menu (if BookMenuBundle not set)
bookHidden: false
# (Optional) Set 'false' to hide ToC from page
bookToC: true
# (Optional) If you have enabled BookComments for the site, you can disable it for specific pages.
bookComments: true
# (Optional) Set to 'false' to exclude page from search index.
bookSearchExclude: true
# (Optional) Set explicit href attribute for this page in a menu (if BookMenuBundle not set)
bookHref: ''
---

小技巧和踩坑记

1. hugo内嵌html代码

  • config.yaml中配置
1
2
3
4
markup:
  goldmark:
    renderer:
      unsafe: true