NotePublic/Software/Applications/Hugo/Hugo_使用说明.md

145 lines
6.1 KiB
Markdown
Raw Normal View History

# Hugo 使用说明
- [Hugo 使用说明](#hugo-使用说明)
- [1. 目录结构介绍](#1-目录结构介绍)
- [2. 常用参数介绍](#2-常用参数介绍)
- [3. 创建站点](#3-创建站点)
- [4. 创新新文章](#4-创新新文章)
- [5. 发布站点](#5-发布站点)
- [6. 支持百度搜索](#6-支持百度搜索)
- [7. 支持 LaTex 公式](#7-支持-latex-公式)
- [7.1. 创建 KaTeX 文件](#71-创建-katex-文件)
- [7.2. 引用 KaTeX 文件](#72-引用-katex-文件)
- [7.3. 如何激活 KaTeX](#73-如何激活-katex)
- [7.4. 在 Markdown 中编写 LaTex 公式](#74-在-markdown-中编写-latex-公式)
- [8. 外部参考资料](#8-外部参考资料)
Hugo 是由 Go 语言实现的静态网站生成器。简单、易用、高效、易扩展、快速部署。对比 HexoHugo 仅需一个二进制文件hugo.exe即可实现网站生成的生成。而且就如它官网介绍The worlds fastest framework for building websites。Hugo 是目前最快的网站构建框架。凭借其惊人的速度和灵活性,解决了环境依赖、性能较差的问题,还有使用简单、部署方便等诸多优点,通过 LiveReload 实时刷新极大的优化文章的写作体验。Hugo 使建站再次变得有趣。
## 1. 目录结构介绍
- archetypes包括内容类型在创建新内容时自动生成内容的配置
- config.toml网站的主配置文件
- content网站内容全部使用 markdown 格式
- layouts网站模板文件决定内容如何呈现
- public包含了站点发布文件
- static图片、css、js 等静态资源
- img图像媒体资源
- themes存放主题
## 2. 常用参数介绍
| Options | Description |
|--------------------------------|----------------|
| --bind="127.0.0.1" | 服务监听 IP 地址 |
| -p, --port=1313 | 服务监听端口 |
| -w, --watch[=true] | 监听站点目录,发现文件变更自动编译 |
| -D, --buildDrafts | 包括被标记为 draft 的文章 |
| -E, --buildExpired | 包括已过期的文章 |
| -F, --buildFuture | 包括将在未来发布的文章 |
| -b, --baseURL="www.datals.com" | 服务监听域名 |
| --log[=false] | 开启日志 |
| --logFile="/var/log/hugo.log" | log 输出路径 |
| -t, --theme="" | 指定主题 |
| -v, --verbose[=false] | 输出详细信息 |
## 3. 创建站点
```bash
hugo new site <site name>
```
## 4. 创新新文章
```bash
hugo new <dir and file name>
```
## 5. 发布站点
```bash
hugo --buildDrafts --buildExpired --buildFuture
```
## 6. 支持百度搜索
进入 [Baidu 搜索资源平台](https://ziyuan.baidu.com)->用户中心->站点管理->添加网站。
选择 HTML 文件验证,将下载到的 baidu_verify_code-xxxxx.html 文件放置到 \<Hugo>/public 目录下即可。
## 7. 支持 LaTex 公式
Hugo 默认不支持 LaTex 的渲染,需要使用第三方插件如 KaTeX 等来进行支持。由于插件需要添加到 Hugo 生成的相关静态页中,这个动作需要在 hugo build 过程中自动完成,因此要修改 hugo 模板文件。
### 7.1. 创建 KaTeX 文件
首先需要在 \<Hugo>/themes/\<hugo-theme-xxx>/layouts/partials/ 目录下创建一个 katex.html 文件,该文件的用途是导入 KaTeX 的相关 JavaScript 和 CSS内容如下
```html
<!-- CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.2/dist/katex.min.css" integrity="sha384-bYdxxUwYipFNohQlHt0bjN/LCpueqWz13HufFEV1SUatKs1cm4L6fFgCi1jT643X" crossorigin="anonymous">
<!-- The loading of KaTeX is deferred to speed up page rendering -->
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.2/dist/katex.min.js" integrity="sha384-Qsn9KnoKISj6dI8g7p1HBlNpVx0I8p1SvlwOldgi3IorMle61nQy4zEahWYtljaz" crossorigin="anonymous"></script>
<!-- To automatically render math in text elements, include the auto-render extension -->
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.2/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"
onload="renderMathInElement(document.body);"></script>
<script>
document.addEventListener("DOMContentLoaded", function () {
renderMathInElement(document.body, {
delimiters: [
{ left: "$$", right: "$$", display: true },
{ left: "$", right: "$", display: false },
],
throwOnError : false
});
});
</script>
```
注意,以上的 href 和 src 都引用了网络资源,因此无需将相关文件下载到本地。
在 [这里](https://katex.org/docs/browser.html) 可以获得以上代码片段的更多参考。
### 7.2. 引用 KaTeX 文件
需要在每个静态页的 header 或 footer 部分引用 katex.html 文件,这样才能正确渲染 LaTex 公式。以下以修改 header 为例,修改 \<Hugo>/themes/\<hugo-theme-xxx>/layouts/partials/head.html 文件,在 OGP 部分的末尾处增加如下内容:
```html
{{ if .Page.Params.math }}
{{ partial "katex.html" . }}
{{ end }}
```
这段代码使用了 Go 的模板库,在 hugo build 时,能够依据 Markdown 文件的设定来判断是否需要使用 KaTeX。
### 7.3. 如何激活 KaTeX
在便携 Markdown 内容时,可以决定是否激活 KaTeX 功能,通常,在 Markdown 文件的头部存在一个 Hugo 的 Front Matter 区域,通常以“---”符号包围起来,例如:
```markdown
---
layout: post
published: true
...
<!-- Other front matter -->
---
```
添加以下内容则意味着在该静态页中使用 KaTeX 插件渲染 LaTex 公式,否则该页不对 LaTex 公式进行渲染:
```markdown
---
<!-- Other front matter -->
math: true
---
```
### 7.4. 在 Markdown 中编写 LaTex 公式
语法与 LaTex 语法一致,只需要使用“\$”或“\$\$”将公式包围即可,“\$”为行内公式,“\$\$”为行间公式。
## 8. 外部参考资料
1. [Rendering LaTeX with KaTeX on a Hugo blog](https://petercheng.me/rendering-latex-with-katex-on-a-hugo-blog/)