/writing /hugo

front-matter 로 hugo content 의 메타데이터 설정하기

·updated
#hugo#blog
// INDEX

Hugo 로 컨텐츠 작성하기

hugo 는 다양한 서브 커맨드를 지원한다. 그 중 하나가 새로운 컨텐츠를 만드는 커맨드이다.

hugo 는 블로그, document 등과 같은 용도로 많이 사용되며, 이와 같은 용도의 정적 페이지들은 전달하는 내용이 반드시 마련이다.

hugo new content <path>

간단한 커맨드를 통해서 원하는 형식의 컨텐츠를 생성할 수 있다.

hugo 에서 지원하는 컨텐츠 format

hugo 는 여러 마크업 언어를 지원한다.

  • Markdown
  • HTML
  • Emacs Org Mode
  • AsciiDoc
  • Pandoc
  • reStructuredText

사실 마크다운과 html 을 제외한 나머지 마크업 언어는 뭔지 잘 모르겠다. 중요한 것은 익숙한 마크다운과 HTML 을 지원한다는 것이다.

컨텐츠를 적절한 방식으로 변경해서 보여주기 위해선 변경을 도와주는 렌더링 도우미가 필요하다. 마크다운을 페이지로 변환하는 것과 HTML 을 페이지로 변환하는데 필요한 로직은 다르기 때문에, 적절한 렌더링을 도와주는 친구를 선택해야 한다. 어떤 방식으로 선택하느냐하면 파일의 확장자 혹은 front matter 의 markup 식별자이다.

먼저 확장자에 대해서 알아보자.

확장자 혹은 extension

hugo 가 지원하는 컨텐츠 포멧에 대한 정보는 공식 홈페이지에서 확인해 볼 수 있다.

콘텐츠 형식식별자파일 확장자
Markdownmarkdownmarkdown, md, mdown
HTMLhtmlhtm, html

주요 두 마크업 언어를 확인해보면 다음과 같다. 식별자에 대해선 잠시후 알아보도록하자.

hugo 커맨드를 사용해서 컨텐츠를 만들땐 파일의 제목과 확장자까지 지정해줘야한다.

hugo new content path/to/your/content.html
hugo new content path/to/your/content.md

front matter 에 markup 식별자가 존재하지 않는 경우, hugo 는 컨텐츠의 확장자를 통해서 어떤 렌더링을 도와줄 친구를 찾을지 정한다.

markup 식별자

확장자보다 우선 순위가 있는 것은 front matter 의 markup 식별자이다. \a 선언은 front matter 에 선언이 가능하다.

콘텐츠 형식식별자파일 확장자
Markdownmarkdownmarkdown, md, mdown
HTMLhtmlhtm, html

여기서 식별자란 front matter 에 선언하는 markup 식별자에 들어갈 내용이다.

+++
date = '{{ .Date }}'
draft = true
title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
markup = 'markdown'
+++

위처럼 markup 식별자에 넣을 내용으로 md 파일로 생성한 콘텐츠도 markup 식별자가 html 인 경우 html 로 렌더링된다.

이는 확장자보다 front matter 의 markup 에 들어가는 식별자가 우선되어 렌더링을 도와줄 친구를 선택한다는 것이다.

front matter

front matter 는 hugo 에서 사용하는 콘텐츠에 메타데이터를 추가하는 방법이다.

front matter 은 머릿말 정도로 생각할 수 있는데 콘텐츠의 여러 메타 정보를 담고있다.
여기서 메타 정보란 데이터에 대한 설명을 하는 데이터로 콘텐츠에 대한 정보를 포함하여, 콘텐츠 사용에 대한 이해를 높이고 검색 엔진 최적화에도 많은 도움이 된다.
hugo 의 front matter 에 대한 정보는 공식 페이지에서 확인해 볼 수 있다.

hugo 에서 사용하는 front matter 형식은 json, toml, yaml 형식을 지원한다.
각각의 형식에 대한 구분 기호가 다르며 다음과 같이 사용할 수 있다.

참고 : 공식 홈페이지

---
date: 2024-02-02T04:14:54-08:00
draft: false
params:
  author: John Smith
title: Example
weight: 10
---
+++
date = 2024-02-02T04:14:54-08:00
draft = false
title = 'Example'
weight = 10
[params]
  author = 'John Smith'
+++
{
   "date": "2024-02-02T04:14:54-08:00",
   "draft": false,
   "params": {
      "author": "John Smith"
   },
   "title": "Example",
   "weight": 10
}

content 생성 시 front matter 적용하기

hugo 에서 제공하는 콘텐츠 생성 커맨드를 이용할 때 기본적으로 사용 가능한 front matter 를 설정할 수 있다.

archetypes 라는 폴더를 프로젝트의 루트에 생성해보자. archetypes 라는 폴더는 hugo 에서 새로운 콘텐츠를 만들떄 사용하는 템플릿을 선언하는 디렉토리이다.

archetypes 디렉토리에 만들 파일은 default.md 파일이다.

front matter 적용을 위한 파일 검색 순서는 아래와 같다.

  1. archetypes/posts.md
  2. archetypes/default.md
  3. themes/my-theme/archetypes/posts.md
  4. themes/my-theme/archetypes/default.md

posts 등에 적용할 수 있는 콘텐츠 생성 템플릿을 별도로 지정할 수 있으며, 각각의 콘텐츠에 대해 특정한 front matter 를 적용하지 않을 예정이라면 default.md 만 만들어도 충분하다.

default.md 에 선언할 수 있는 front matter 포멧은 앞서 말했듯이 3가지가 존재한다. json, toml, yaml 이 있으며 익숙한 포멧을 사용하면 된다. 여기선 toml 로 설명하지만 형식만 다를 뿐 같은 문법을 적용할 수 있다.

archetypes/default.md

+++
date = '{{ .Date }}'
draft = true
title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
+++

위에서 정의한 front matter 는 날짜, 발행 여부, 제목을 담고있다. hugo 의 템플릿 문법을 사용하여 콘텐츠 생성시에 만들어지는 데이터에 대한 정의가 가능하다.

front matter 정의하고 content 생성

내가 설정한 front matter 는 다음과 같다.

+++
date = '{{ .Date }}'
draft = true
title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
description = '{{ replace .File.ContentBaseName `-` ` ` }}'
summary = '{{ replace .File.ContentBaseName `-` ` `  }}'
markup = 'markdown'
slug = '{{ .File.ContentBaseName }}'
tags = ['']
lastmod = '{{ .Date }}'
[params]
  author = 'hippo-an'
  toc = true
  subtitle = ''
+++
  • date : 콘텐츠 발행 기준 날짜 설정
  • draft : 발행 여부 설정
  • title : 콘텐츠 제목 설정
  • description : 콘텐츠 설명 설정
  • summary : 콘텐츠 요약 설정
  • markup : 마크업 식별자 설정
  • slug : url 의 컨텐츠 엔드포인트로 사용되는 내용
  • tag : 콘텐츠 분류를 위한 태그 설정
  • lastmod : 파일의 마직막 수정일
  • param.author : 글 작성자 parameter
  • param.toc : table of content 렌더링 조건 처리를 위한 parameter
  • param.subtitle : 글의 부제목 설정

위와 같은 설정으로 hugo 를 이용해서 콘텐츠를 생성하면 다음과 같은 결과가 나온다.

$ hugo new content posts/test.md
+++
date = '2024-07-13T12:40:17+09:00'
draft = true
title = 'Test'
description = 'test'
summary = 'test'
markup = 'markdown'
slug = 'test'
tags = ['']
lastmod = '2024-07-13T12:40:17+09:00'
[params]
  author = 'hippo-an'
  toc = true
  subtitle = ''
+++

hugo 의 문법이 적용된 부분은 필요한 값으로 변환이 된다. 추가적으로 필요한 콘텐츠의 내용이 있다면 내용을 추가할 수도 있다.

콘텐츠의 메타데이터인 front matter 를 통해 html 메타 태그 설정을 추가해보자. 나같은 경우 theme 의 head 부분을 partials 로 관리하고 있기 때문에 다음과 같은 경로에 해당 내용을 추가할 수 있다.

./themes/theme/layouts/partials/head.html

<head>
    {{/*  다른 head 내 태그 설정  */}}

    {{- with .Params.description }}
        <meta name="description" content="{{ . }}" />
    {{ end -}}
    {{- with .Params.summary }}
        <meta name="summary" content="{{ . }}" />
    {{ end -}}
    {{- with .Params.subtitle }}
        <meta name="subtitle" content="{{ . }}" />
    {{ end -}}
    {{- with .Params.author }}
        <meta name="author" content="{{ . }}" />
    {{ end -}}

    {{/*  다른 head 내 태그 설정  */}}
</head>

위와 같은 코드를 선언하여 html 의 content 에 대한 metadata 를 추가할 수 있다. front matter 에 선언한 값은 .Params.<front matter 에 선언한 이름> 으로 접근 가능하다.