配置 Hugo

通常的使用情况下,一个网站并不需要一个配置文件,因为它的目录结构和模板就提供了主要的配置。

Hugo 需要在源目录查找一个 config.toml 的配置文件。如果这个文件不存在,将会查找 config.yaml,然后是 config.json

这个配置文件是一个整站的配置。它给 Hugo 提供了如何构建站点的方式,比如全局的参数和菜单。

示例

下面是一个典型的 yaml 格式的配置文件的示例:

---
baseurl: "http://yoursite.example.com/"
...

下面是一个 toml 格式的带了一些默认值的配置文件。 在 [params] 下面的值将会构成模板里的 .Site.Params 变量:

contentdir = "content"
layoutdir = "layouts"
publishdir = "public"
builddrafts = false
baseurl = "http://yoursite.example.com/"
canonifyurls = true

[taxonomies]
  category = "categories"
  tag = "tags"

[params]
  description = "Tesla's Awesome Hugo Site"
  author = "Nikola Tesla"

这是一个 yaml 格式的配置文件,设置了一些更多的选项:

---
baseurl: "http://yoursite.example.com/"
title: "Yoyodyne Widget Blogging"
footnotereturnlinkcontents: "↩"
permalinks:
  post: /:year/:month/:title/
params:
  Subtitle: "Spinning the cogs in the widgets"
  AuthorName: "John Doe"
  GitHubUser: "spf13"
  ListOfFoo:
    - "foo1"
    - "foo2"
  SidebarRecentLimit: 5
...

配置变量

下面是 Hugo 定义好的变量列表,以及他们的默认值,你可以设置他们:

---
archetypedir:               "archetype"
# hostname (and path) to the root, e.g. http://spf13.com/
baseURL:                    ""
# include content marked as draft
buildDrafts:                false
# include content with publishdate in the future
buildFuture:                false
# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs.
relativeURLs:               false
canonifyURLs:               false
# config file (default is path/config.yaml|json|toml)
config:                     "config.toml"
contentdir:                 "content"
dataDir:                    "data"
defaultExtension:           "html"
defaultLayout:              "post"
disableLiveReload:          false
# Do not build RSS files
disableRSS:                 false
# Do not build Sitemap file
disableSitemap:             false
# edit new content with this editor, if provided
editor:                     ""
footnoteAnchorPrefix:       ""
footnoteReturnLinkContents: ""
# google analytics tracking id
googleAnalytics:            ""
languageCode:               ""
layoutdir:                  "layouts"
# Enable Logging
log:                        false
# Log File path (if set, logging enabled automatically)
logFile:                    ""
# "yaml", "toml", "json"
metaDataFormat:             "toml"
newContentEditor:           ""
# Don't sync modification time of files
noTimes:                    false
paginate:                   10
paginatePath:               "page"
permalinks:
# Pluralize titles in lists using inflect
pluralizeListTitles:        true
# Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu")
preserveTaxonomyNames:      false
# filesystem path to write files to
publishdir:                 "public"
# color-codes for highlighting derived from this style
pygmentsStyle:              "monokai"
# true: use pygments-css or false: color-codes directly
pygmentsUseClasses:         false
# default sitemap configuration map
sitemap:
# filesystem path to read files relative from
source:                     ""
staticdir:                  "static"
# display memory and timing of different steps of the program
stepAnalysis:               false
# theme to use (located in /doc/themes/THEMENAME/)
theme:                      ""
title:                      ""
# if true, use /filename.html instead of /filename/
uglyURLs:                   false
# Do not make the url/path to lowercase
disablePathToLower:         false
# if true, auto-detect Chinese/Japanese/Korean Languages in the content. (.Summary and .WordCount can work properly in CJKLanguage)
hasCJKLanguage              false
# verbose output
verbose:                    false
# verbose logging
verboseLog:                 false
# watch filesystem for changes and recreate as needed
watch:                      true
---

编译时忽略的文件

使用 hugo 编译时,将忽略 config.toml 文件中指定的内容,比如:以 .foo.boo 结尾的文件。

ignoreFiles = [ "\\.foo$", "\\.boo$" ]

上面使用了正则表达式,使用 \ 转义是因为在 TOML 里。

设置 Blackfriday 渲染

Blackfriday 是 Hugo 中使用的 Markdown 渲染引擎。 Hugo 中的 Blackfriday 的默认设置已经很健全,可以适用于大多数的情况。

但是同时 Hugo 还提供了一些选项 — 正如下面的表格里的所示的, 对应于 Blackfriday 源码里的选项。 (html.gomarkdown.go):

FlagDefaultBlackfriday flag
smartypants true HTML_USE_SMARTYPANTS
Purpose: Enable/Disable smart punctuation substitutions such as smart quotes, smart dashes, etc. May be fine-tuned with the angledQuotes, fractions, smartDashes and latexDashes flags below.
angledQuotes false HTML_SMARTYPANTS_ANGLED_QUOTES
Purpose: Enable/Disable smart angled double quotes.
Example: "Hugo" renders to «Hugo» instead of “Hugo”.
fractions true HTML_SMARTYPANTS_FRACTIONS
Purpose: Enable/Disable smart fractions.
Example: 5/12 renders to 512 (<sup>5</sup>&frasl;<sub>12</sub>)
Caveat: Even with fractions = false, Blackfriday would still convert 1/2, 1/4 and 3/4 to ½ (&frac12;), ¼ (&frac14;) and ¾ (&frac34;) respectively, but only these three.
smartDashes true HTML_SMARTYPANTS_DASHES
Purpose: Enable/Disable smart dashes, i.e. turning hyphens into en dash or em dash.
Its behavior can be modified with the latexDashes flag listed below.
latexDashes true HTML_SMARTYPANTS_LATEX_DASHES
Purpose: Choose between LaTeX-style smart dashes and “conventional” smart dashes.
If true, -- is translated into “–” (&ndash;), and --- is translated into “—” (&mdash;).
If false, -- is translated into “—” (&mdash;), whereas a spaced single hyphen between two words is turned into an en dash, e.g. 12 June - 3 July becomes 12 June &ndash; 3 July.
hrefTargetBlank false HTML_HREF_TARGET_BLANK
Purpose: Open external links in a new window/tab.
plainIDAnchors false FootnoteAnchorPrefix and HeaderIDSuffix
Purpose: If true, then header and footnote IDs are generated without the document ID.
Example: #my-header instead of #my-header:bec3ed8ba720b9073ab75abcf3ba5d97.
extensions [] EXTENSION_*
Purpose: Use non-default additional extensions.
Example: Add "hardLineBreak" to use EXTENSION_HARD_LINE_BREAK.
extensionsmask [] EXTENSION_*
Purpose: Extensions in this option won't be loaded.
Example: Add "autoHeaderIds" to disable EXTENSION_AUTO_HEADER_IDS.

注意

  1. 这些 flags 是非常大小写敏感的!(Hugo v0.15版本)
  2. 这些选项必须在 blackfriday 项下面,可以 同时用在 site 和 page 级别 。如果在 page 级别设置了,将会覆盖 site 上的设置。比如:
TOMLYAML
[blackfriday]
  angledQuotes = true
  fractions = false
  plainIDAnchors = true
  extensions = ["hardLineBreak"]
blackfriday:
  angledQuotes: true
  fractions: false
  plainIDAnchors: true
  extensions:
    - hardLineBreak