hugo

1. 目录结构：

archetypes :  hugo new content content/posts/my-first-post.md命令需要用到的模板
assets ： 包含全局资源，例如images, CSS, Sass, JavaScript, 和TypeScript
config ： 包含站点配置
content ： 包含构成网站内容的标记文件（通常为 Markdown）和页面资源
data ：包含数据文件（JSON、TOML、YAML 或 XML），用于扩充内容、配置、本地化和导航
i18n ：多语言网站的翻译表
layouts ：用于将内容、数据和资源转换为完整网站的模板
resources ：在hugo或者hugo server命令运行时，缓存asset管道的输出。
static：在构建站点时要复制到public目录的文件

hugo版本：hugo v0.121.2-6d5b44305eaa9d0a157946492a6f319da38de154

go install github.com/gohugoio/hugo@v0.121.2

专业术语：

page bundle: 页面捆绑包，就是一个封装内容和相关资源的目录。分为分支捆绑包和叶子捆绑包。
    - branch bundle: 包含_index文件的目录，或者没有包含_index文件的顶级目录。
    - leaf bundle：包含_index文件的目录，但是它没有子bundle。

2. 配置相关

配置文件： config.toml或config.yaml或config.json

配置目录：

+-- config
|   +-- _default    # 目录名表示环境名
|   |   +-- config.toml
|   |   +-- languages.toml
|   |   +-- menus.en.toml   # 对应不同的语言
|   |   +-- menus.zh.toml
|   |   +-- params.toml   # 这里存放的是以`params.`为前缀的配置
|   +-- production   # hugo --environment staging
|   |   +-- config.toml
|   |   +-- params.toml
|   +-- staging
|       +-- config.toml
|       +-- params.toml

所有的配置设置:

baseURL
buildDrafts (false)
buildExpired (false)
buildFuture (false)
canonifyURLs (false)  规范化URLs
defaultContentLanguage (“en”)
defaultContentLanguageInSubdir (false)
disableAliases (false)
disableHugoGeneratorInject (false) 取消hugo生成器的注入
disableKinds ([])
disableLiveReload (false)
disablePathToLower (false)
enableEmoji (false)
enableGitInfo (false)
enableInlineShortcodes (false)
enableMissingTranslationPlaceholders (false)
enableRobotsTXT (false)
footnoteAnchorPrefix ("")  脚注锚点前缀
footnoteReturnLinkContents ("")
googleAnalytics ("")
hasCJKLanguage (false)
imaging
languages
languageCode ("")
languageName ("")
disableLanguages
layoutDir (“layouts”)
log (false)
logFile ("")
newContentEditor ("")
noChmod (false)
noTimes (false)
paginate (10)   标页数
paginatePath (“page”)
permalinks   永久链接
pluralizeListTitles (true)  复数列表标题
publishDir (“public”)
related
relativeURLs (false)
refLinksErrorLevel (“ERROR”)
refLinksNotFoundURL
rssLimit (unlimited)
sectionPagesMenu ("")
sitemap
staticDir (“static”)
summaryLength (70)
taxonomies  分类
theme ("")
themesDir (“themes”)
timeout (10000)
title ("")
titleCaseStyle (“AP”)
uglyURLs (false)
verbose (false)
verboseLog (false)
watch (false)
build
caches
frontmatter
menu
minify  缩小

module
- Module Mounts Config
archetypeDir (“archetypes”)  原型
assetDir (“assets”)  资产
contentDir (“content”)
dataDir (“data”)

markup  标记
- markup
blackfriday  黑色星期五

3. 内容相关

预定义的Front Matter变量:

1. aliases: 将在输出目录结构中创建的一个或多个别名（例如，重命名内容的旧发布路径）的数组。
2. audio
3. cascade：给当前页面的所有子页面设置变量，只能出现在_index.md文件上
4. date: in the future, Hugo will not publish content
5. description
6. draft(草稿): when true, Hugo will not publish content
7. expiryDate: when in the past, Hugo will not publish content
8. headless
9. images: 与页面相关的图像路径数组； 由内部模板使用，例如 _internal/twitter_cards.html。
10. isCJKLanguage
11. keywords
12. layout
13. lastmod
14. linkTitle
15. markup
16. outputs
17. publishDate: when in the future, Hugo will not publish content
18. resources
19. series: 此页面所属的series数组，作为series分类法(taxonomy)的子集； 由 opengraph 内部模板进行填充
20. slug: 显示为输出 URL 的尾部。 在前面指定的值将覆盖基于文件名的 URL 段。
21. summary:
22. title
23. type
24. url
25. videos
26. weight：给不同的目录下的weight设置不同的值，同一目录下的weight保持一致，而同一目录的页面顺序由Date来控制

4. layout模板和函数

4.1 markdown文件所对应的访问url:

+-- content
    +-- _index.md     // <- https://example.com/index.html
    +-- about
    |   +-- index.md  // <- https://example.com/about/
    +-- posts
    |   +-- _index.md   // <- https://example.com/posts/index.html
    |   +-- firstpost.md   // <- https://example.com/posts/firstpost/
    |   +-- happy
    |   |   +-- ness.md  // <- https://example.com/posts/happy/ness/
    |   +-- secondpost.md  // <- https://example.com/posts/secondpost/
    +-- quote
        +-- first.md       // <- https://example.com/quote/first/
        +-- second.md      // <- https://example.com/quote/second/

1. section

content/ 下的所有一级目录都是Section，也叫做root section。

content/ 下的二级目录或者更深层的目录，如果目录包含 _index.md 文件，就也是section。

content
+-- blog        <-- Section, because first-level dir under content/
    +-- funny-cats
    |   +-- mypost.md
    |   +-- kittens         <-- Section, because contains _index.md
    |       +-- _index.md
    +-- tech                <-- Section, because contains _index.md
        +-- _index.md

使用section page variables and methods可以轻松实现导航栏：

<ol  class="nav navbar-nav">
  {{ template "breadcrumbnav" (dict "p1" . "p2" .) }}
</ol>
{{ define "breadcrumbnav" }}
{{ if .p1.Parent }}
{{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 )  }}
{{ else if not .p1.IsHome }}
{{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 )  }}
{{ end }}
<li{{ if eq .p1 .p2 }} class="active"{{ end }}>
  <a href="{{ .p1.Permalink }}">{{ .p1.Title }}</a>
</li>
{{ end }}

1. .CurrentSection: 该页面的当前section
2. .FirstSection: 该页面的root section
3. .InSection $anotherPage: 判断$anotherPage是否在当前section下。
4. .IsAncestor $anotherPage: 判断该页面是否是$anotherPage的祖先页面
5. .IsDescendant $anotherPage: 判断该页面是否是$anotherPage的子孙页面
6. .Parent: A section’s parent section or a page’s section.
7. .Section: The section this content belongs to. Note: For nested sections, this is the first path element in the directory, for example, /blog/funny/mypost/ => blog.
8. .Sections: The sections below this content.

2. slug 一个content的slug要么是name.extension（例如lollapalooza.md），要么是name/（例如lollapalooza/）。

slug的值由下面两者之一决定：

• the name of the content file
• front matter overrides

3. path 基于该content的文件路径，但是不包含_index.md和index.md部分。

4. url 是该content的相对URL，由以下两者之一决定：

• 由于content的路径决定
• 在front matter中指定，它的优先级更高

5. type hugo首先会从内容文件的元信息里找type属性，如果没有找到，hugo会将section作为content type。

在下面的例子中，先创建一个layout: layouts/new/mylayout.html 那么下面的content将被该layout所渲染：

content/posts/my-post.md

---
title: My Post
type: new
layout: mylayout
---

6. permalinks配置

[permalinks]
  posts = "/:year/:month/:title/"

只有posts/目录下的content会被设置新的URL，例如，这个文件content/posts/sample-entry.md，包含date: 2017-02-27T19:20:00-05:00这个front matter，该markdown文件将被渲染为public/2017/02/sample-entry/index.html。

对于"root" section，可以如下配置：

[permalinks]
  "/" = "/:year/:month/:filename/"

解析特殊的时间格式：

[permalinks]
  posts = "/:06/:1/:2/:title/"

支持的标签：

• :year, the 4-digit year
• :month, the 2-digit month
• :monthname, the name of the month
• :day, the 2-digit day
• :weekday, the 1-digit day of the week (Sunday = 0)
• :weekdayname, the name of the day of the week
• :yearday, the 1- to 3-digit day of the year
• :section, the content’s section
• :sections
• :title, the content’s title
• :slug,
• :filename

4.1 图片处理

Image资源可以被调整大小，被裁剪，注意Image资源也属于Page Resource的一种，要和/static文件夹下的图片区分开。

支持Page Resource的所有方法，还有图片大小调整和裁剪的特殊方法

{{ $image := resources.Get "images/logo.jpg" }}

图片经过处理之后，这些Metadata将不再保留：EXIF,IPTC,XMP等等。 可以使用Exif方法来获取原始图片的EXIF的metadata。

1. Resize

// Resize to a width of 600px and preserve ratio
{{ $image := $resource.Resize "600x" }}

// Resize to a height of 400px and preserve ratio
{{ $image := $resource.Resize "x400" }}

// Resize to a width 600px and a height of 400px
{{ $image := $resource.Resize "600x400" }}

2. Fit 缩小图片以适应给定的尺寸，同时保持纵横比。使用时必须同时设置宽度和高度

{{ $image := $resource.Fit "600x400" }}

3. Fill 调整和裁剪图像以匹配给定的尺寸。使用时必须同时设置宽度和高度

4.2 i18n函数

基于全局配置文件的i18n配置，对指定key进行翻译。

1. 语法： i18n KEY

这会根据您的 i18n/en-US.yaml（文件名遵循RFC 5646规范，但是必须使用小写否则无法识别）文件来翻译一段内容。 您可以使用 go-i18n 工具来管理您的翻译(/i18n目录)。 翻译(/i18n目录)可以存在于主题和hugo项目的根目录中。

2. 使用：
   在/i18n目录下创建zh-cn.yaml文件，并在config.yaml文件中添加如下的配置：

defaultContentLanguage: "zh-cn"

5. 布局相关

5.1

Layout定位布局

由下列6个因素决定，优先级由高到低：

1. Kind single page: _default/single.html list page: _default/list.html

2. Layout 可以在md文件的front matter上设置layout

3. Output Format

4. Language

5. Type 如果md文件上使用front matter指定了type，就使用这个值； 否则就使用root section；它的默认值是: page

6. Section

Regular Pages:
    Single page in "posts" section: 
        - layouts/posts/single.html
        - layouts/_default/single.html

    Base template for single page in "posts" section:
        - layouts/posts/single-baseof.html
        - layouts/posts/baseof.html
        - layouts/_default/single-baseof.html
        - layouts/_default/baseof.html

    Single page in "posts" section with layout set:
        - layouts/posts/demolayout.html
        - layouts/posts/single.html
        - layouts/_default/demolayout.html
        - layouts/_default/single.html

    Base template for single page in "posts" section with layout set:
        - layouts/posts/demoleyout-baseof.html
        - layouts/posts/single-baseof.html
        - layouts/posts/baseof.html
        - layouts/_default/demolayout-baseof.html
        - layouts/_default/single-baseof.html
        - layouts/_default/baseof.html

Home Page:
    Home page:
        - layouts/index.html
        - layouts/home.html
        - layouts/list.html
        - layouts/_default/index.html
        - layouts/_default/home.html
        - layouts/_default/list.html
    Base template for home page:
        - layouts/index-baseof.html
        - layouts/home-baseof.html
        - layouts/list-baseof.html
        - layouts/baseof.html
        - layouts/_default/index-baseof.html
        - layouts/_default/home-baseof.html
        - layouts/_default/list-baseof.html
        - layouts/_default/baseof.html
    Home page with  type set:
        - layouts/demotype/index.html
        - layouts/demotype/home.html
        - layouts/demotype/list.html
        - layouts/index.html
        - layouts/home.html
        - layouts/list.html
        - layouts/_default/index.html
        - layouts/_default/home.html
        - layouts/_default/list.html
    Base template for home page with type set:
        - layouts/demotype/index-baseof.html
        - layouts/demotype/home-baseof.html
        - layouts/demotype/list-baseof.html
        - layouts/demotype/baseof.html
        - layouts/index-baseof.html
        - layouts/home-baseof.html
        - layouts/list-baseof.html
        - layouts/baseof.html
        - layouts/_default/index-baseof.html
        - layouts/_default/home-baseof.html
        - layouts/_default/list-baseof.html
        - layouts/_default/baseof.html
    Home page with layout set:
        - layouts/demolayout.html
        - layouts/index.html
        - layouts/home.html
        - layouts/list.html
        - layouts/_default/demolayout.html
        - layouts/_default/index.html
        - layouts/_default/home.html
        - layotus/_default/list.html
    
Section Page:
    Section list for "posts" section:
        - layouts/posts/posts.html
        - layouts/posts/section.html
        - layouts/posts/list.html
        - layouts/section/posts.html
        - layouts/section/section.html
        - layouts/section/list.html
        - layouts/_default/posts.html
        - layouts/_default/section.html
        - layouts/_default/list.html
    Section list for "posts" section with type set to "blog":
        - layouts/blog/posts.html
        - layouts/blog/section.html
        - layouts/blog/list.html
        - layouts/posts/posts.html
        - layouts/posts/section.html
        - layouts/posts/list.html
        - layouts/section/posts.html
        - layouts/section/section.html
        - layouts/section/list.html
        - layouts/_default/posts.html
        - layouts/_default/section.html
        - layouts/_default/list.html
    Section list for "posts" section with layout set to "demolayout":
        - layouts/posts/demolayout.html
        - layouts/posts/posts.html
        - layouts/posts/section.html
        - layouts/posts/list.html
        - layouts/section/demolayout.html
        - layouts/section/posts.html
        - layouts/section/section.html
        - layouts/section/list.html
        - layouts/_default/demolayout.html
        - layouts/_default/posts.html
        - layouts/_default/section.html
        - layouts/_default/list.html
Taxonomy(=category) Pages:
    Taxonomy list in categories:
        - layouts/categories/category.terms.html
        - layouts/categories/terms.html
        - layouts/categories/taxonomy.html
        - layouts/categories/list.html
        - layouts/category/category.terms.html
        - layouts/category/terms.html
        - layouts/category/taxonomy.html
        - layouts/category/list.html
        - layouts/taxonomy/category.terms.html
        - layouts/taxonomy/terms.html
        - layouts/taxonomy/taxonomy.html
        - layouts/taxonomy/list.html
        - layouts/_default/category.terms.html
        - layouts/_default/terms.html
        - layouts/_default/taxonomy.html
        - layouts/_default/list.html

Term Pages:
    Taxonomy term in categories:
        - layouts/categories/term.html
        - layouts/categories/category.html
        - layouts/categories/taxonomy.html
        - layouts/categories/list.html
        - layouts/term/term.html
        - layouts/term/category.html
        - layouts/term/taxonomy.html
        - layouts/term/list.html
        - layouts/taxonomy/term.html
        - layouts/taxonomy/category.html
        - layouts/taxonomy/taxonomy.html
        - layouts/taxonomy/list.html
        - layouts/category/term.html
        - layouts/category/category.html
        - layouts/category/taxonomy.html
        - layouts/category/list.html
        - layouts/_default/term.html
        - layouts/_default/category.html
        - layouts/_default/taxonomy.html
        - layouts/_default/list.html

Page Bundles 捆绑页

捆绑页分为：

• 叶子捆绑（没有儿子）：
  • A Leaf Bundle is a directory at any hierarchy within the content/ directory, that contains an index.md file.
  • A leaf bundle can be made headless by adding below in the Front Matter (in the index.md): headless = true
    • It will have no Permalink and no rendered HTML in public/.
    • It will not be part of .Site.RegularPages, etc.
    • 可以通过.Site.GetPage来访问它们

  content/
  +-- about    //< 叶子捆绑
  |   +-- index.md
  +-- posts
  |   +-- my-post  //< 叶子捆绑
  |   |   +-- content1.md
  |   |   +-- content2.md
  |   |   +-- image1.jpg   //< image1.jpg和image2.png只能被index.md访问
  |   |   +-- image2.png
  |   |   +-- index.md
  |   +-- my-other-post  //< 叶子捆绑
  |       +-- index.md
  |
  +-- another-section
      +-- ..
      +-- not-a-leaf-bundle
          +-- ..
          +-- another-leaf-bundle  //< 叶子捆绑
              +-- index.md
  

• 分支捆绑（home page, section, taxonomy terms, taxonomy list）
  • A Branch Bundle is any directory at any hierarchy within the content/ directory, that contains at least an _index.md file.

  content/
  +-- branch-bundle-1   //< 分支捆绑
  |   +-- branch-content1.md
  |   +-- branch-content2.md
  |   +-- image1.jpg
  |   +-- image2.png
  |   +-- _index.md
  +-- branch-bundle-2  //< 分支捆绑
      +-- _index.md
      +-- a-leaf-bundle
          +-- index.md
  

对比：

Content Format

上面是以markdown文件为例子进行讲解的，其实还可以是html文件，它们都属于Content Format。

Hugo 会使用markup这个front matter和文件的扩展名来决定是否执行如下操作：

• 将Markdown转换为HTML
• 处理Shortcodes
• 提供Layout作为模板进行渲染

默认支持的Content Format

markup配置:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

markup:
  asciidocExt:
    attributes: {}
    backend: html5
    extensions: []
    failureLevel: fatal
    noHeaderOrFooter: true
    preserveTOC: false
    safeMode: unsafe
    sectionNumbers: false
    trace: false
    verbose: false
    workingFolderCurrent: false
  defaultMarkdownHandler: goldmark
  goldmark:
    extensions:
      definitionList: true
      footnote: true
      linkify: true
      strikethrough: true
      table: true
      taskList: true
      typographer: true
    parser:
      attribute:
        block: false
        title: true
      autoHeadingID: true
      autoHeadingIDType: github
    renderer:
      hardWraps: false
      unsafe: false
      xhtml: false
  highlight:
    anchorLineNos: true
    codeFences: true
    guessSyntax: false
    hl_Lines: ""
    lineAnchors: ""
    lineNoStart: 1
    lineNos: false
    lineNumbersInTable: true
    noClasses: true
    style: github
    tabWidth: 4
  tableOfContents:
    endLevel: 2
    ordered: true
    startLevel: 2

Page资源只能被捆绑页(其所在目录下要么含有index.md要么含有_index.md)所访问。

属性

1. Name: filename，对于Markdown类型的资源，可以在front matter中设置Name
2. Title: 同Name
3. Permalink: 资源的绝对URL
4. RelPermalink: 资源的相对URL
5. Content: 资源内容本身

<script>{{(.Resources.GetMatch "myscript.js").Content | safeJS }}</script>
OR
<img src="{{ (.Resources.GetMatch "mylogo.png").Content | base64Encode }}">

6. MediaType: 使用MIME类型
7. MediaType.MainType: 例如，application/pdf的主类型就是application
8. MediaType.SubType: 例如，application/pdf的子类型就是pdf
9. MediaType.Suffixes: 可能的文件后缀
10. ResourceType: 同MediaType.MainType

方法

1. ByType: {{ .Resources.ByType "image" }}，根据ResourceType进行过滤
2. Match: {{ .Resources.Match "images/*" }}，通过对Name进行Glob模式匹配来过滤
3. GetMatch: 和Match一样，但是只返回第一个资源

什么是Glob模式匹配：

// Using Match/GetMatch to find this images/sunset.jpg ?
.Resources.Match "images/sun*" ✅
.Resources.Match "**/sunset.jpg" ✅
.Resources.Match "images/*.jpg" ✅
.Resources.Match "**.jpg" ✅
.Resources.Match "*" 🚫
.Resources.Match "sunset.jpg" 🚫
.Resources.Match "*sunset.jpg" 🚫

Page Resources Metadata

放在_index.md和index.md文件的front matter下 0. url: 要被设置的资源的位置

1. name: 设置资源的Name
2. title: 设置资源的Title
3. params: 设置资源的自定义key/value对

---
title: Application
date: "2018-01-25"
resources:
- name: header
  src: images/sunset.jpg
- params:
    icon: photo
  src: documents/photo_specs.pdf
  title: Photo Specifications
- src: documents/guide.pdf
  title: Instruction Guide
- src: documents/checklist.pdf
  title: Document Checklist
- src: documents/payment.docx
  title: Proof of Payment
- name: pdf-file-:counter
  params:
    icon: pdf
  src: '**.pdf'
- params:
    icon: word
  src: '**.docx'
---

hugo deploy

1. hugo项目根目录下的config.toml配置:

baseURL = "https://jiaweicheng.site/"
languageCode = "en-us"
title = "My New Hugo Site"

[deployment]
order = [".jpg$", ".gif$"]

[[deployment.targets]]
name = "mydeployment"
URL = "s3://blog?endpoint=minio.jiaweicheng.site&disableSSL=false&s3ForcePathStyle=true&region=cn-east-1"

# If you are using a CloudFront CDN, deploy will invalidate the cache as needed.
# cloudFrontDistributionID = <ID>

[[deployment.matchers]]
# Set custom content type for /sitemap.xml
pattern = "^.+\\.xml$"
contentType = "application/xml"
gzip = true

或者修改config.yaml配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

deployment:
  order:
  - ".jpg$"
  - ".gif$"
  targets:
  - name: "mydeployment"
    URL: "s3://blog?endpoint=minio.jiaweicheng.site&disableSSL=false&s3ForcePathStyle=true&region=cn-east-1"
  matchers:
  - pattern: "^.+\\.xml$"
    contentType: "application/xml"
    gzip: true

2. hugo deploy

1

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE AWS_SECRET_ACCESS_KEY='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' hugo deploy

上一篇 « 多巴胺 下一篇 » agpl开源协议