5.8 KiB

Raw Blame History

Hugo 使用说明

Hugo 使用说明

Hugo 是由 Go 语言实现的静态网站生成器。简单、易用、高效、易扩展、快速部署。对比 Hexo，Hugo 仅需一个二进制文件（hugo.exe）即可实现网站生成的生成。而且就如它官网介绍：The world’s 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. 创建站点

hugo new site <site name>

4. 创新新文章

hugo new <dir and file name>

5. 发布站点

hugo --buildDrafts --buildExpired --buildFuture

6. 支持百度搜索

进入 Baidu 搜索资源平台->用户中心->站点管理->添加网站。

选择 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，内容如下：

<!-- CSS -->
<link rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/katex@0.13.2/dist/katex.min.css"
    integrity="sha384-Cqd8ihRLum0CCg8rz0hYKPoLZ3uw+gES2rXQXycqnL5pgVQIflxAUDS7ZSjITLb5"
    crossorigin="anonymous">
<!-- The loading of KaTeX is deferred to speed up page rendering -->
<script defer
    src="https://cdn.jsdelivr.net/npm/katex@0.13.2/dist/katex.min.js"
    integrity="sha384-1Or6BdeNQb0ezrmtGeqQHFpppNd7a/gw29xeiSikBbsb44xu3uAo8c7FwbF5jhbd"
    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.13.2/dist/contrib/auto-render.min.js"
    integrity="sha384-vZTG03m+2yp6N6BNi5iM4rW4oIwk5DfcNdFfxkk9ZWpDriOkXX8voJBFrAO7MpVl"
    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 都引用了网络资源，因此无需将相关文件下载到本地。

7.2. 引用 KaTeX 文件

需要在每个静态页的 header 或 footer 部分引用 katex.html 文件，这样才能正确渲染 LaTex 公式。以下以修改 header 为例，修改 <Hugo>/themes/<hugo-theme-xxx>/layouts/partials/head.html 文件，在 OGP 部分的末尾处增加如下内容：

{{ if .Page.Params.math }}
  {{ partial "katex.html" . }}
{{ end }}

这段代码使用了 Go 的模板库，在 hugo build 时，能够依据 Markdown 文件的设定来判断是否需要使用 KaTeX。

7.3. 如何激活 KaTeX

在便携 Markdown 内容时，可以决定是否激活 KaTeX 功能，通常，在 Markdown 文件的头部存在一个 Hugo 的 Front Matter 区域，通常以“---”符号包围起来，例如：

---
layout:      post
published:   true
...
<!-- Other front matter -->
---

添加以下内容则意味着在该静态页中使用 KaTeX 插件渲染 LaTex 公式，否则该页不对 LaTex 公式进行渲染：

---
<!-- Other front matter -->
math:        true
---

7.4. 在 Markdown 中编写 LaTex 公式

语法与 LaTex 语法一致，只需要使用“$”或“$$”将公式包围即可，“$”为行内公式，“$$”为行间公式。

5.8 KiB Raw Blame History Unescape Escape