hugo 설정파일

2023년 6월 3일

설정파일에서는 프로젝트에서 사용할 변수들의 값을 미리 정의할 수 있다.
이 변수들은 js 파일, layouts 파일, archetypes 파일, content의 frontmatter에서 사용 가능하다.

정말 많은 기능들이 이미 변수와 매핑되어 config 파일에서 컨트롤 가능하다. 원하는 기능이 있다면 이곳저곳 찾아보기 전에 config 파일먼저 확인해보자.

config 파일의 적용 #

코드 편집기나 도구들이 hugo 프로젝트임을 쉽게 확인하기 위해 hugo 0.110.0 버전부터 config.toml 에서 hugo.toml 파일로 변경됐다.
config.toml도 아직 사용이 가능하지만, 변경하는걸 추천
파일을 config/ 폴더에 나눠서 저장할수도 있다. config/xx/params.toml은 [Params], config/xx/menu.toml은 [Menu]의 설정파일이 된다.

 1├─ config
 2│   ├─ _default
 3│   │   ├─ hugo.toml
 4│   │   ├─ menu.toml
 5│   │   └─ params.toml
 6│   ├─ production
 7│   │   ├─ hugo.toml
 8│   │   └─ params.toml
 9│   └─ staging
10│       ├─ hugo.toml
11│       └─ params.toml

hugo --environment [config section] 으로 환경을 지정할 수 있는데, _default가 모두 적용되고 그 위에 섹션의 환경설정이 적용된다.
예를 들어서 나머진 같고 googleAnalytics만 프로덕션환경에서 적용하고 싶다면 production의 hugo.toml에 googleAnalytics 설정 하나만 추가하면 된다.

기본값으로도 잘 동작하는 설정들이 많기 때문에 필요해보이는 설정만 추가할 예정이다.
이 설정들은 테마 안에서도 사용될 수 있다.

참고링크 : https://gohugo.io/getting-started/configuration/
설정파일이 버전에 따라 달라질 수 있어서 다른 링크는 주의해서 읽어야한다.

Site #

사이트 전반적으로 사용될 변수들이다. .Site.변수명 으로 접근할 수 있으며, .Site는 생략이 가능하다.

baseURL ("") #

웹사이트 루트에 대한 호스트이름과 경로를 지정한다. 웹페이지 생성 시 링크, 이미지 등에 대한 URL은 이 경로를 기준으로 한다.

title ("") #

웹사이트의 타이틀을 지정

defaultContentLanguage (“en”) #

웹사이트의 기본 언어를 지정한다. hugobook 테마 기준으로 한글검색을 지원할 수 있게 하는 옵션이다.
한글은 ko로 지정하면된다.

theme ("") #

hugo에서 사용하는 theme를 지정하는데, themes/ 폴더의 적용할 테마 폴더이름과 일치해야한다.

googleAnalytics ("") #

google Analytics 계정을 생성하고 키값을 지정하면 페이지의 방문자를 추적해준다.

enableEmoji (false) #

이모지를 콘텐츠에 포함할 수 있게 한다. :truck: => 🚚

disableLiveReload (false) #

라이브리로드 속성을 제거한다.

watch (true) #

변경사항이 감지되면 웹사이트를 다시 빌드한다. disableLiveReload 설정으로 제거해도 빌드는 계속하기 때문에 같이 설정해줘야한다.

disablePathToLower (false) #

false로 설정된 경우 경로에 대문자가 포함되면 소문자로 변경한다.

newContentEditor ("") #

hugo new 명령을 입력했을때 자동으로 열릴 에디터

paginate (10) #

페이징이 필요한 곳 ex)리스트페이지 에서 페이지의 단위를 지정

paginatePath (“page”) #

페이징에서 추가될 url 경로

hasCJKLanguage (false) #

한중일어를 감지하도록한다. .Summary나 .WordCount같은 페이지 변수가 제대로 동작하게 된다.

disableKinds ([]) #

렌더링하지 않아야 하는 페이지 종류를 지정한다.
참고링크 : https://kodify.net/hugo/config/disablekinds-option/

taxonomyTerm: 분류 용어 페이지 (/categories/, /tags/)
taxonomy: 분류 페이지 (/categories/movie/, /tags/goods/)
term: 분류에 대한 방문페이지 (/tags/awesome/index.html)
section: 특정 섹션 페이지 (/blog/)
robotsTXT: robots.txt 파일 렌더링 비활성화
404: 휴고 자체적인 404 오류페이지 서버를 재시작해야 적용된다.

taxonomies #

기본값으로 category, tag를 사용할 수 있는데, 사용자지정분류도 추가할 수 있다.

1[taxonomies]
2  # 표시될 taxonomy = 콘텐츠 헤더에서 사용될이름
3  category = 'categories'
4  series = 'series'     # series 추가
5  tag = 'tags'

콘텐츠의 메타데이터에 추가하면 된다.

1---
2title: "good taxonomies test"
3categories = ['Development']
4series = ['Go Web Dev']
5tags = ['Development', 'Go', 'fast', 'Blogging']
6---

permalinks ("") #

토큰을 이용해서 콘텐츠를 렌더링할떄 사용되는 URL링크방식을 지정할 수 있다.
https://gohugo.io/content-management/urls/#tokens

1[permalinks]
2  blog = '/:section/:year/:month/:title/'

이렇게 지정하면 content/blog 하위의 콘텐츠 렌더링 시 http://example.org/blog/2023/06/03/post3 형식으로 URL이 지정된다.

markup #

 1[markup]
 2  defaultMarkdownHandler = 'goldmark'
 3  [markup.asciidocExt]
 4    backend = 'html5'
 5    extensions = []
 6    failureLevel = 'fatal'
 7    noHeaderOrFooter = true
 8    preserveTOC = false
 9    safeMode = 'unsafe'
10    sectionNumbers = false
11    trace = false
12    verbose = false
13    workingFolderCurrent = false
14    [markup.asciidocExt.attributes]

goldmark #

hugo 0.60 에서 마크다운 디폴트 라이브러리로 가져왔다.
참고링크: https://gohugo.io/getting-started/configuration-markup/#goldmark
extensions: https://github.com/yuin/goldmark/#built-in-extensions

 1[markup]
 2  [markup.goldmark]
 3    [markup.goldmark.extensions]
 4      definitionList = true
 5      footnote = true
 6      linkify = true
 7      linkifyProtocol = 'https'
 8      strikethrough = true
 9      table = true
10      taskList = true
11      [markup.goldmark.extensions.typographer]
12        apostrophe = '&rsquo;'
13        disable = false
14        ellipsis = '&hellip;'
15        emDash = '&mdash;'
16        enDash = '&ndash;'
17        leftAngleQuote = '&laquo;'
18        leftDoubleQuote = '&ldquo;'
19        leftSingleQuote = '&lsquo;'
20        rightAngleQuote = '&raquo;'
21        rightDoubleQuote = '&rdquo;'
22        rightSingleQuote = '&rsquo;'
23    [markup.goldmark.parser]
24      autoHeadingID = true
25      autoHeadingIDType = 'github'
26      wrapStandAloneImageWithinParagraph = true
27      [markup.goldmark.parser.attribute]
28        block = false
29        title = true
30    [markup.goldmark.renderer]
31      hardWraps = false
32      unsafe = false
33      xhtml = false

highlight #

Hugo는 Go에 내장된 Chroma를 코드 하이라이터로 사용한다.
참고링크: https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode
스타일: https://github.com/alecthomas/chroma/tree/master/styles

 1[markup]
 2  [markup.highlight]
 3    anchorLineNos = false
 4    codeFences = true
 5    guessSyntax = false
 6    hl_Lines = ''
 7    hl_inline = false
 8    lineAnchors = ''
 9    lineNoStart = 1
10    lineNos = false
11    lineNumbersInTable = true
12    noClasses = true
13    noHl = false
14    style = 'monokai'
15    tabWidth = 4

Params #

템플릿에서 사용할 변수들을 모아둔 곳. .Site.Params로 접근할 수 있는데, 보통은 테마에서 사용하는 변수들이 모여있어서 테마마다 다르다.
컨텐츠의 frontmatter 에서 정의된 변수들도 .Params 영역으로 포함된다.

1# hugo.toml
2[params]
3  BookToC = true
4  BookTheme = 'light'
5  BookServiceWorker = true

템플릿 변수로 사용하는 방법 #

1// 1. themes/hugo-book/assets/sw.js
2const pages = [
3{{ if eq .Site.Params.BookServiceWorker "precache" }}
4  {{ range .Site.AllPages -}}
5  "{{ .RelPermalink }}",
6  {{ end -}}
7{{ end }}
8];

1<!-- 2. themes/hugo-book/layouts/_default/baseof.html -->
2    {{ if default true (default .Site.Params.BookToC .Params.BookToC) }}
3    <aside class="book-toc">
4      <div class="book-toc-content">
5        {{ template "toc" . }} <!-- Table of Contents -->
6      </div>
7    </aside>