Hugo

Hugo releated notes. Current take some notes when reading official docuemts

Tips

Footnotes

This is a footnote.[^1]

[^1]: the footnote text.

Not only number, words work too.¹

Github task list

- [ ] a task list item
- [ ] list syntax required
- [ ] incomplete
- [x] completed

• a task list item
• list syntax required
• incomplete
• completed

Reading documents

目录结构

.
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

archetypes: 用于hugo new，Lookup Order for Archetypes：

• archetypes/posts.md
• archetypes/default.md
• themes//archetypes/posts.md
• themes//archetypes/default.md (Auto-generated with hugo new site)

配置

• Configuration Lookup Order:
  • ./config.toml
  • ./config.yaml
  • ./config.json
• All Configuration (TOML)：config.toml
• The values under [params] will populate the .Site.Params variable for use in templates.
• 官方文档里面的toml配置有点过时了，不少配置项在新版本的hugo中已经废弃了。下面的是beautifulhugo主体里面示例网站的配置：config.toml
• Blackfriday is Hugo’s built-in Markdown rendering engine. 看起来是个不错的东西。
  • Mmark: fork from blackfriday
    • 不支持shortcodes等feature，放弃
  • 对嵌套列表有一点问题，用小书匠默认的Tab设置似乎正常：Deep nested lists don’t output correctly
  • Blackfriday Options & extensions
  • Awesome mardown extended features:
    • Github-styled task lists (TODO lists)
    • emojis
    • shortcodes: if you find yourself frequently embedding your content with raw HTML
  • MathJax似乎有坑 MathJax with Hugo

文档组织

Hugo believes that you organize your content with a purpose. The same structure that works to organize your source content is used to organize the rendered site.

• content/[section]/[post-title.md] 对应 [website-url]/[section]/[post-title]/
• 每个section都可以有一个_index.md，不是十分明白，似乎可以自定义section主页的内容？
• 在.md头部添加 slug: [new-title] 可以定义新的链接地址，对应 [website-url]/[section]/[new-title]/
• url: /new/url 对应 [website-url]/new/url

扉页 - Front Matter

Front Matter Variables

模板

Base Template Lookup Order

• /layouts/section/<TYPE>-baseof.html
• /themes/<THEME>/layouts/section/<TYPE>-baseof.html
• /layouts/<TYPE>/baseof.html
• /themes/<THEME>/layouts/<TYPE>/baseof.html
• /layouts/section/baseof.html
• /themes/<THEME>/layouts/section/baseof.html
• /layouts/_default/<TYPE>-baseof.html
• /themes/<THEME>/layouts/_default/<TYPE>-baseof.html
• /layouts/_default/baseof.html
• /themes/<THEME>/layouts/_default/baseof.html

这意味着，对于每一个section都可以有自己独立的模板。我可以为笔记，项目展示提供不同的网页样式。

Hugo 的模板函数：

• Hugo template functions: https://gohugo.io/functions/
• Go template documentation: https://golang.org/pkg/text/template/#hdr-Functions

路径

{{ "mystyle.css" | absURL  }} → "https://example.com/hugo/mystyle.css"
{{ "mystyle.css" | relURL  }} → "/hugo/mystyle.css"

Functions and variables

• Hugo template functions

Filter posts

{{ if or ( eq .Kind "page" ) ( eq .Kind "section" ) }}
    {{ $.Scratch.Set "posts" (where .Site.RegularPages "Section" .Section) }}
{{ else if eq .Kind "home" }}
    {{ $post_section := where .Site.RegularPages "Section" "post" }}
    {{ $post_true := where .Site.RegularPages ".Params.post" true }}
    {{ $post_all := union $post_section $post_true }}
    {{ $.Scratch.Set "posts" $post_all }}
{{ else }}
    {{ $.Scratch.Set "posts" .Data.Pages }}
{{ end }}

{{ $posts := (.Paginate ($.Scratch.Get "posts")).Pages }}

IsMenuCurrent

This function has strict request for config.toml, the example below will works.

[[menu.main]]
    name = "Post"
    url = "/"
    weight = 1

[[menu.main]]
    name = "Note"
    url = "/note/"
    weight = 2

intersect and union

When filter where with and or in hugo, we use intersect and union.

{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}

The above fetches regular pages not of page or about type unless they are pinned. And finally, we exclude all pages with no images set in Page params.

Multi-level sections

https://github.com/bep/hugotest