Hugo

개요

Hugo는 매우 인기 있는 오픈 소스 웹사이트 배포 시스템입니다. Hugo 웹사이트의 페이지는 보통 순수 마크다운으로 작성되므로, 계산 결과를 자동으로 재현 가능하게 포함하는 간단한 방법이 없습니다.

Quarto hugo-md 형식을 사용하면 계산 결과(예: 플롯을 생성하는 R/Python 코드)를 Hugo 웹사이트에 포함할 수 있습니다. 이 문서에서 그 방법을 설명합니다.

Hugo와 함께 Quarto를 사용할 때는 테마, 페이지 레이아웃, 내비게이션과 관련된 많은 Quarto 기능이 적용되지 않는다는 점을 기억하세요. Hugo에는 자체 테마 시스템, 구문 강조, 목차, 페이지 레이아웃, 내비게이션 메뉴, 전체 텍스트 검색이 있습니다. Quarto의 자체 프레임워크가 아니라 Hugo의 HTML 배포 프레임워크 내에서 렌더링되는 마크다운을 생성하기 위해 Quarto를 사용하게 됩니다.

사이트 설정

Hugo에서 Quarto를 사용하기 전에 Hugo config.toml에 몇 가지 변경을 해야 합니다. 먼저 .qmd와 .ipynb 파일, 그리고 기타 소스 코드나 데이터 파일이 사이트의 일부로 배포되지 않도록 하세요. 예:

ignoreFiles = [ "\\.qmd$", "\\.ipynb$", "\\.py$" ]

다음으로 Hugo의 마크다운 렌더러가 raw HTML을 허용하도록 설정합니다(많은 R/Python 패키지가 마크다운이 아닌 raw HTML로 계산 결과를 출력하기 때문입니다):

[markup.goldmark.renderer]
unsafe= true

페이지 만들기

Quarto를 사용하는 Hugo 기사나 포스트는 자체 디렉터리에 두는 것이 좋습니다(Hugo Page Bundles 기능 활용). 이렇게 하면 페이지가 생성하거나 참조하는 콘텐츠(예: 플롯 출력)가 마크다운 소스와 함께 배치됩니다.

Hugo 사이트에 Quarto 문서를 추가하려면:

content 아래에 Quarto 문서를 담을 디렉터리를 생성합니다.
해당 디렉터리에 index.qmd 문서를 추가합니다. 이를 렌더링하면 index.md가 생성되고, Hugo는 이를 Page Bundle로 취급하여 이미지와 기타 참조 리소스를 배포 디렉터리로 자동 복사합니다.
필요한 Hugo front matter를 추가한 다음 format: hugo-md와 필요한 Quarto 옵션을 지정합니다.

예를 들어 content 디렉터리에 hello-quarto라는 새 문서를 만든다고 가정하면 파일 시스템은 다음과 같습니다:

mysite/
  content/
    hello-quarto/
      index.qmd

index.qmd의 소스 코드는 다음과 같을 수 있습니다:

---
title: Hello, Quarto
date: "2012-04-06"
categories: 
  - Matplotlib
  - Coordinates
format: hugo-md
jupyter: python3
---

## 극좌표 축

극좌표 축에서의 선 그래프 예시는 @fig-polar 를 참고하세요.

```{python}
#| label: fig-polar
#| fig-cap: "극좌표 축에서의 선 그래프"

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(subplot_kw={'projection': 'polar'})
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```

워크플로

Hugo와 함께 Quarto를 사용하는 기본 개념은 계산 마크다운 문서(.qmd)나 Jupyter 노트북(.ipynb)을 사용해 Hugo가 HTML로 렌더링하는 일반 마크다운 파일(.md)을 생성하는 것입니다.

index.qmd quarto => index.md hugo => index.html

quarto render와 quarto preview 명령은 .qmd 또는 .ipynb 파일을 Hugo 호환 마크다운(.md)으로 변환하는 데 사용됩니다. 계산 파일은 일반 마크다운 파일을 두는 위치(예: blog 디렉터리)에 함께 위치합니다.

렌더링 후에는 계산 문서 옆에 일반 .md 파일이 생성됩니다. 이 마크다운 파일은 Hugo에서 처리됩니다.

실시간 미리보기

quarto preview 명령은 Hugo 웹사이트가 있는 디렉터리에서 실행될 때 이를 자동으로 인식합니다:

Terminal

cd my-hugo-website
quarto preview

이는 로컬 미리보기 서버를 띄우기 위해 hugo serve를 자동으로 실행합니다. 또한 파일 시스템에서 .qmd 및 .ipynb 입력 변경을 감시하고 변경 시 Hugo 호환 .md 파일로 자동 렌더링합니다.

이 기능은 VS Code 또는 Positron의 Quarto VS Code 확장에 포함된 통합 Preview 명령에서도 동작합니다.

렌더링

미리보기를 사용하지 않고 사이트의 모든 Quarto 문서(.qmd)와 노트북(.ipynb)을 렌더링하려면 사이트 루트 디렉터리에서 quarto render를 실행하세요:

Terminal

cd my-hugo-website
quarto render

보통 배포용 사이트를 빌드하기 전에 사이트 수준에서 quarto render를 실행하는 것이 좋습니다:

Terminal

quarto render && hugo

개별 문서나 노트북만 렌더링할 수도 있습니다:

Terminal

quarto render blog/2022-07-26/hello-quarto/index.qmd

계산 비용이 큰 문서가 있다면 문서 소스 코드가 변경될 때만 코드가 재실행되도록 Quarto의 freeze 기능을 사용하는 것을 고려하세요.

프로젝트 수준에서 렌더링하지 않고 Quarto로 개별 파일만 렌더링하려면 다음과 같이 hugo-md 형식을 지정해야 합니다:

---
title: "My Blog Post"
format: hugo-md
---

구성

Quarto는 _quarto.yml 프로젝트 설정 파일이 없는 Hugo 사이트에서도 잘 동작하지만, 기본 동작을 사용자 지정하거나 참고문헌을 추가하려면 _quarto.yml 파일을 추가할 수 있습니다. 예를 들어 간단히 사용자 지정한 _quarto.yml 파일은 다음과 같습니다:

_quarto.yml

project:
  type: hugo
      
format: 
  hugo-md:
    code-fold: true
  
execute: 
  warning: false

bibliography: references.bib

명시적 _quarto.yml 파일을 제공하는 경우, 위와 같이 프로젝트 유형(type: hugo)을 반드시 명시해야 합니다.

외부 디렉터리

Quarto 문서/노트북을 Hugo 웹사이트와 분리된 별도 디렉터리에 두고 싶을 수도 있습니다. 이 구성에서는 Quarto 디렉터리에 사이트의 디렉터리 구조를 그대로 반영한 뒤, 프로젝트 파일의 output-dir을 Hugo 디렉터리를 가리키도록 설정합니다. 예:

_quarto.yml

project:
  type: hugo
  output-dir: ../hugo-site

쇼트코드

Hugo shortcodes와 Quarto shortcodes는 동일한 기본 문법을 공유합니다(예: {{< var foo >}}). 보통 Quarto가 인식하지 못하는 shortcode는 변경 없이 Hugo로 전달되므로 문제가 되지 않습니다.

하지만 경우에 따라 Hugo shortcode 사용이 Pandoc의 마크다운 처리를 방해할 수 있으며, Pandoc 처리로부터 Hugo shortcode를 “보호”해야 합니다. 이는 보통 괄호를 하나 더 추가해 이스케이프하는 방식으로 처리할 수 있습니다. 예:

{{{< ref "foo/index.md" >}}}

shortcode의 존재로 인해 Pandoc가 주변 마크다운을 처리하는 방식이 바뀌면(예: 링크에서 이런 문제가 알려져 있음) 이것만으로는 충분하지 않을 수 있습니다. 이 경우 전체 구문을 마크다운 raw 블록으로 감싸야 합니다. 예:

```{=markdown}
[click here]({{< ref "foo/index.md" >}})
```

또는 인라인 콘텐츠의 경우 마크다운 raw 인라인을 사용하세요:

자세한 내용은 `[click here]({{< ref "foo/index.md" >}})`{=markdown}

WebTeX 수식

hugo 형식은 표준 달러 구분 인라인( $...$ )과 디스플레이($$...$$) 문법으로 LaTeX 수식을 렌더링합니다. 그러나 배포 대상 웹 환경에서 달러 구분 수식을 지원하지 않는다면 WebTeX를 사용해 수식을 표시할 수 있습니다. 이는 Pandoc의 html-math-method를 webtex로 설정하면 됩니다. 예:

format:
  hugo:
    html-math-method: webtex

WebTeX는 이미지를 표시할 수 있는 모든 웹 페이지에서 동작하며, 특별한 JavaScript나 CSS가 필요하지 않습니다. 문서에 포함된 모든 인라인 또는 디스플레이 수식은 렌더링된 수식을 요청하는 이미지 URL로 변환됩니다. 예를 들어 다음 마크다운은:

$x + 1$

다음으로 변환됩니다:

![](https://latex.codecogs.com/svg.latex?x%20%2B%201)

렌더링 결과는 다음과 같습니다:

다크 모드

SVG는 전체적인 외관이 가장 좋기 때문에 기본 렌더링 방식으로 사용됩니다. 하지만 hugo 문서를 어두운 배경에 렌더링한다면, 어두운 배경을 지정한 PNG로 전환하는 것이 좋습니다. 다음과 같이 설정할 수 있습니다:

format:
   hugo:
     html-math-method: 
       method: webtex
       url: https://latex.codecogs.com/png.image?%5Cbg_black&space;