Hugo 不完美教程 - VIII: Functions 内置函

前言

shot.jpg

本静态站点用于演示之用，使用 Hugo 构建，以及 Markdown 供应内容。

流行的静态站点框架有以下几个：

• Jekyll (基于 Ruby 容易上手) https://www.jekyll.com.cn/docs/home/
• Hexo (基于 Node.js 容易上手) https://hexo.io/docs/
• Hugo (基于 Go) https://gohugo.io/documentation/

演示站点有两个访问入口：

• https://jimbowhy.gitee.io/
• https://jimboyeah.github.io/

此站点提供了一篇关于 Hugo 静态站点生成框架的入门教程。

• Hugo 不完美教程 - IX: Menus 菜单组织
• Hugo 不完美教程 - VIII: Functions 内置函数
• Hugo 不完美教程 - VII: Variables 对象变量
• Hugo 不完美教程 - VI: Multilingual 多语言支持
• Hugo 不完美教程 - V: Templates 模板机制
• Hugo 不完美教程 - V: Templates 其它模板
• Hugo 不完美教程 - IV: Hugo Pipes 管道处理
• Hugo 不完美教程 - III: Hugo Modules 模块
• Hugo 不完美教程 - II: Hugo 目录组织
• Hugo 不完美教程 - I: Hugo Web Framework

代码仓库地址如下，查看 hugo-project 分支是原文件，master 分支是发布的静态站点文件：

• https://github.com/jimboyeah/jimboyeah.github.io/tree/hugo-project
• https://gitee.com/jimbowhy/jimbowhy/tree/hugo-project/
  shot.jpg

---

title: "VIII: Functions 内置函数"
description: "坚果的 Hugo 教程"
date: 2020-08-06T12:09:08-04:00
featured_image_: "/assets/IMG_20181101_233654_s.jpg"
tags: ["hugo"]
disable_share: false
summary: "Hugo 导出的函数有许多，这里提供一个以内置函数实现的 Markdown 目录生成功能，使用目录生成时，只需要在 MD 文件中定义目录点位符 [TOC] 即可在对应位置生成目录。"

---

Hugo 提供的对象及变量就是 Go 语言实现的各种对象对外公开的函数方法或属性，了解这些对象是用好模板的基础。

目录：

[TOC]

markdownify 内置函数

讲几个常用的内置函数，首先是 Markdown processor 函数，必用的，通过调用 markdownify 将输入的 MD 字符串转化为 HTML 字符串。

用法如下：

{{ .Title | markdownify }}
{{ "[link](http://abc.com/)" | markdownify }}

具体参考 markdownify.md 文档和配置文档。

Blackfriday 是旧版 Hugo 默认的 Markdown 渲染引擎，现在替换为 Goldmark，但还是可以通过 defaultMarkdownHandler 设置使用 blackfriday：

{{<code file="demo.toml">}}
[markup]
  [markup.blackFriday]
    angledQuotes = false
    footnoteAnchorPrefix = ""
    footnoteReturnLinkContents = ""
    fractions = true
    hrefTargetBlank = false
    latexDashes = true
    nofollowLinks = false
    noreferrerLinks = false
    plainIDAnchors = true
    skipHTML = false
    smartDashes = true
    smartypants = true
    smartypantsQuotesNBSP = false
    taskLists = true
{{</code>}}     

Goldmark 中提供了 Markdown Render Hooks 回调实现自定义的内容渲染，目前支持 image、link、heading：

layouts
└── _default
    └── _markup
        ├── render-image.html
        ├── render-image.rss.xml
        └── render-link.html

i18n 国际化函数

国际化函数 i18n 参考 multilingual.md。

Hugo 使用类似 PHP 系统中的 .po 文件来实现字符串在不同语言间的转换，字符串定义文件保存在 /i18n 目录下。

假设配置文件 /i18n/en-US.toml:

[home]
other = "Home"

[wordCount]
other = "This article has {{ .WordCount }} words."

[readingTime]
one = "One minute to read"
other = "{{.Count}} minutes to read"

那么，获取 ID 为 home 的字符串这样表达：

{{ i18n "home" }}
{{ T "home" }}.

字符串中可以使用模板，用变量去替换生成，比如单数、复数 singular、plural 处理：

{{ i18n "wordCount" . }}
{{ i18n "readingTime" .ReadingTime }}

i18n 函数并不判断数值，而是通过传入参数来使用 other 关联的字符串，然后将传入参数远的 {{.Count}} 点位符号。

if i18 integer argument == 1 👉 one
else - - - - - - - - - - - - 👉 other

还好，可以使用 Nick Snyder 实现的 go-i18n，它提供了更丰富的支持，zero one two few many other 等。

config.toml 配置中，设置默认的语言：

DefaultContentLanguage = "zh"

MD5 摘要生成函数

MD5 摘要生成函数，参考 functions\md5.md 文档：

{{ md5 "Hello world, gophers!" }}
<!-- returns the string "b3029f756f98f79e7f1b7f1d1f0dd53b" -->

如果用到 Gravatar 头像服务，那么这个函数非常有用：

<img src="https://www.gravatar.com/avatar/{{ md5 "your@email.com" }}?s=100&d=identicon">

htmlEscape 和 htmlUnescape 进行 HTML 编码和解码:

{{ htmlEscape "Hugo & Caddy > WordPress & Apache" }}

"Hugo & Caddy > WordPress & Apache"

{{ htmlUnescape "Hugo & Caddy > WordPress & Apache" }}

"Hugo & Caddy > WordPress & Apache"

编码后 & 变成 &，还有 <, >, &, ', " 等符号，解码过程中为了输出原样 HTML 可以再通过 safeHTML 函数处理。

[TOC] 使用函数生成目录

Hugo 导出的函数有许多，可以参考文档列表，这里以内置函数来实现 Markdown 的目录生成功能。

首先，在 MD 文件中定义目录点位符：

[TOC]

然后，在 single.html 即页面模板文件中添加目录生成代码，列表页面不用不考虑：

{{<code file="demo.html">}}    {{$contents := ""}}
{{range (split .RawContent "\n")}}
  {{if (hasPrefix . "# ")}}
    {{ $item := replace (lower .) "#" ""}}
    {{ $item = trim $item " \n\r"}}
    {{- $trimed := replace $item " " "-" -}}
    {{ $contents = printf "%s<a href=\"#%s\">%s</a><br>" $contents $trimed .}} 
    {{else if hasPrefix . "## "}}
    {{ $item := replace (lower .) "##" ""}}
    {{ $item = trim $item " \n\r"}}
    {{- $trimed := replace $item " " "-" -}}
    {{ $contents = printf "%s<a href=\"#%s\">%s</a><br>" $contents $trimed .}} 
  {{end}}
{{end}}
{{- replaceRE "<p>\\[TOC\\]</p>" (printf "<div class=\"contents\">%s</div>" $contents) .Content | safeHTML -}}
{{</code>}}     

替换时注意内容是转换后带 HTML 标签的字符串，原始的 Markdown 内容可以通过 .RawContent 获取。

注意，以上 range 结构直接在模板中使用会导致页面产生许多换行符，可以将其用模板片断包装。因为，模板片断可以当作函数一样使用，可以获取其 return 语句返回的内容。

如下，将代码保存了模板片断目录下的 GetTOC.html 文件中，然后再调用：

{{<code file="/partial/func/GetTOC.html">}}
{{$contents := ""}}
{{/* 
    GetTOC

    This partial gets the url for [TOC] for a given page. 
    
    {{$contents := partial "func/GetTOC.html" .}}
    {{- replaceRE "<p>\\[TOC\\]</p>" (printf "<div class=\"contents\">%s</div>" $contents) .Content | safeHTML -}}

    @return Permalink list string

*/}}

{{/* Declare a new string variable */}}
{{ $contents := "" }}

{{range (split .RawContent "\n")}}
{{if (hasPrefix . "# ")}}
    {{ $item := replace (lower .) "#" ""}}
    {{ $item = trim $item " \n\r"}}
    {{- $trimed := replace $item " " "-" -}}
    {{ $contents = printf "%s<a href=\"#%s\">%s</a><br>" $contents $trimed .}} 
    {{else if hasPrefix . "## "}}
    {{ $item := replace (lower .) "##" ""}}
    {{ $item = trim $item " \n\r"}}
    {{- $trimed := replace $item " " "-" -}}
    {{ $contents = printf "%s<a href=\"#%s\">%s</a><br>" $contents $trimed .}}
{{end}}
{{end}}

{{ return $contents }}
{{</code>}}