前言
本静态站点用于演示之用,使用 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: "V: Templates 其它模板"
description: "坚果的 Hugo 教程"
date: 2020-08-06T20:14:08-04:00
featured_image_: "/assets/IMG_20190117_123248_s1.jpg"
summary: Hugo 直接使用了 Golang 的模板语法,表达能力很强大,配合 Hugo 预定义变量或自定义变量实现非常强大的静态站点功能。Mardown 文件提共内容数据,而模板则是数据的消化系统。这部分介绍其它各种模板的使用。
tags: ["hugo", "menu"]
目录:
[TOC]
Homepage Template 主页模板
根据不同的内容,对应的不同的主页面,下面是其中的 Home 和 JSON 的主页定位方式,这里并没有列出主题目录,因为主题的 layouts 目录结构意义是一样的:
{
"Example": "Home page",
"Kind": "home",
"OutputFormat": "HTML",
"Suffix": "html",
"Template Lookup Order": [
"layouts/index.html.html",
"layouts/home.html.html",
"layouts/list.html.html",
"layouts/index.html",
"layouts/home.html",
"layouts/list.html",
"layouts/_default/index.html.html",
"layouts/_default/home.html.html",
"layouts/_default/list.html.html",
"layouts/_default/index.html",
"layouts/_default/home.html",
"layouts/_default/list.html"
]
},
{
"Example": "JSON home",
"Kind": "home",
"OutputFormat": "JSON",
"Suffix": "json",
"Template Lookup Order": [
"layouts/index.json.json",
"layouts/home.json.json",
"layouts/list.json.json",
"layouts/index.json",
"layouts/home.json",
"layouts/list.json",
"layouts/_default/index.json.json",
"layouts/_default/home.json.json",
"layouts/_default/list.json.json",
"layouts/_default/index.json",
"layouts/_default/home.json",
"layouts/_default/list.json"
]
},
一个主页面模板参考:
{{ define "main" }}
{{.Title}}
{{ with .Params.subtitle }}
{{.}}
{{ end }}
{{.Content}}
{{ range first 10 .Site.RegularPages }}
{{ .Render "summary"}}
{{ end }}
{{ end }}
shortcode 短代码模板
短代码模板 shortcode 用来生成定义一段功能代码,供内容文件调用生成页面。
Hugo 提供了几个内置的 shortcode,可是在国内网络环境却不太好用:
-
figure 使用语法及对应生成
{{}}
Steve Francia
-
gist 用于生成 Git 版本仓库中的 URL
{{}} https://gist.github.com/spf13/7896402 {{}}
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters<!-- image --> <figure {{ if isset .Params "class" }}class="{{ index .Params "class" }}"{{ end }}> {{ if isset .Params "link"}}<a href="{{ index .Params "link"}}">{{ end }} <img src="{{ index .Params "src" }}" {{ if or (isset .Params "alt") (isset .Params "caption") }}alt="{{ if isset .Params "alt"}}{{ index .Params "alt"}}{{else}}{{ index .Params "caption" }}{{ end }}"{{ end }} /> {{ if isset .Params "link"}}</a>{{ end }} {{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} <figcaption>{{ if isset .Params "title" }} <h4>{{ index .Params "title" }}</h4>{{ end }} {{ if or (isset .Params "caption") (isset .Params "attr")}}<p> {{ index .Params "caption" }} {{ if isset .Params "attrlink"}}<a href="{{ index .Params "attrlink"}}"> {{ end }} {{ index .Params "attr" }} {{ if isset .Params "attrlink"}}</a> {{ end }} </p> {{ end }} </figcaption> {{ end }} </figure> <!-- image --> -
param 获取页面扉页参数
假设,设置了页面扉页参数 testparam: Hugo Rocks! 那么就可以通过将其输出到页面:
{{}} {{}}
-
ref 和 relref 根据页面文件生成相对或绝对页面引用 URL
[Neat]({{< ref "blog/neat.md" >}}) [Who]({{< relref "about.md#who" >}}) Neat Who
highlight 生成高亮代码块
-
instagram 生成 Instagram 图片 URL,国内墙
{{}} https://www.instagram.com/p/BWNjjyYFxVx/
tweet 国内墙
vimeo 国内墙
youtube 国内墙
这些被墙的应用可能会导致 Hugo 运行失败,因为网站访问超时导致,如 twitter.html 定义使用了 api.twitter.com:
{{- $pc := .Page.Site.Config.Privacy.Twitter -}}
{{- if not $pc.Disable -}}
{{- if $pc.Simple -}}
{{ template "_internal/shortcodes/twitter_simple.html" . }}
{{- else -}}
{{- $url := printf "https://api.twitter.com/1/statuses/oembed.json?id=%v&dnt=%t" (index .Params 0) $pc.EnableDNT -}}
{{- $json := getJSON $url -}}
{{ $json.html | safeHTML }}
{{- end -}}
{{- end -}}
可以将有问题 API 调用注解掉,Hugo Docs 项目就使用了它们:
{{/*< instagram_simple BGvuInzyFAe hidecaption >*/}}
{{/*< twitter_simple 1085870671291310081 >*/}}
{{/*< youtube ZJthWmvUzzc >*/}}
{{/*< vimeo_simple 48912912 >*/}}
另外,对于 MD 生成的标准的 HTML 标签,像表格,或列表,无法直接在 MD 设置样式:
{{}}
| Key | Value |
|---|---|
| Static Site Generator | Hugo |
| Language | Go |
{{}}
那么可以通过定义 shortcodes 的方式来加外层 DIV 通过 CSS 级联样式去定义,也可以使用
{{ $table := .Inner | markdownify | safeHTML }}
{{ $tableBulma := $table | replaceRE "" "
" }}
{{ $tableBulma | safeHTML }}
用户定义短代码模板的定位按以下顺序:
/layouts/shortcodes/.html
/themes//layouts/shortcodes/.html
先定义一个 shortcode 模板 layouts\shortcodes\page-kinds.html:
所有页面 Page 对象都有一个 .Kind 属性变量,如下:
| Kind | 说明 | 例子 |
|------------|------------------------|----------------------------------------------------------------|
| `home` | 正在加载的是首页 | `/index.html` |
| `page` | 正在加载的指定页面 | `my-post` page (`/posts/my-post/index.html`) |
| `section` | 正在加载的是分区页 | `posts` section (`/posts/index.html`) |
| `taxonomy` | 正在加载的是分类页 | `tags` taxonomy (`/tags/index.html`) |
| `term` | 正在加载的是分类术语页 | term `awesome` in `tags` taxonomy (`/tags/awesome/index.html`) |
然后在 MD 内容页面中调用 shortcode 以生成对应的内容:
{{ page-kinds %}}
sometext
{{ /page-kinds %}}
shortcode 短代码模板可使用的属性变量,以上面的调用方法作为参考,对应值如下:
{{
}}
属性
说明
参考值
.Name
Shortcode 名字
page-kinds
.Ordinal
基于 0 的序号,表示 shortcode 在页面内容的位置
1
.Parent
嵌套的 parent shortcode
.Position
所在页面文件名和行列号,常用于调试
"C:\quickstart\content\posts\2nd-post.md:29:5"
.IsNamedParams
指示是否使用命名参数,而不是位置化参数
false
.Inner
在 shortcode 标签之间的的内容
sometext
{{}}
Hugo 官方文档项目中提供了很好的 shortcode 模板学习示例,例如,最常用来展示高亮代码片段 code 为例,当你在查看官方文档 MD 文件时,看到以下这样的内容:
{{}}
...
{{}}
这就表示,MD 文件正使用 code 生成相应的内容,来看看它的定义 layouts_default\shortcodes\code.html:
{{}} {{ codeLang := "" }}
{{ " suffix }}
{{ codeLang = . }}{{ end }}
{{ if eq codeLang = "go-html-template" }}
{{ end }}
{{.}}
{{- end -}}
{{ if ne (.Get "copy") "false" }}
{{/* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */}}
{{end}}
{{ if .Get "nocode" }}{{ $.Inner }}{{ else }}{{ with $codeLang }}{{- highlight $.Inner . "" | -}}{{ else }}
{{- .Inner | string -}}
{{ end }}{{ end }}