DocFlow
StaticSite
Advanced
Marp 렌더링

Marp 렌더링

title: Hugo에서 Marp 렌더링 description: “Hugo와 Marp를 통합하여 Markdown 기반 프레젠테이션을 렌더링하는 방법을 학습합니다. 설치, 설정, 확장, 그리고 실전 활용 사례까지 전 과정을 다룹니다.” categories:

  • 소프트웨어
  • 웹 개발
  • 도구
  • Hugo
  • Marp tags:
  • Hugo
  • Marp
  • Markdown
  • 프레젠테이션
  • 통합 toc: true sidebar: collapsed: true cascade: type: docs weight: 150

Marp는 Markdown 파일을 슬라이드 형식의 HTML로 변환할 수 있는 강력한 도구입니다. Hugo는 정적 사이트 생성기이므로, Marp를 활용해 Hugo 프로젝트에서 슬라이드 페이지를 효과적으로 생성하고 통합할 수 있습니다. 이 글에서는 Marp를 Hugo에 통합하는 전 과정을 자세히 다룹니다.

목표

  • Markdown 작성: 일반 문서처럼 Markdown으로 슬라이드를 작성.
  • 슬라이드 렌더링: Hugo에서 특정 type 값을 기준으로 Markdown 파일을 Marp로 변환하여 슬라이드로 표시.
  • 동일한 경로 유지: 슬라이드 파일은 static/slides에 저장되며, Hugo URL 구조를 그대로 반영.

환경 설정

Marp 설치

Marp는 Node.js 기반 CLI 도구입니다. Node.js와 npm이 설치되어 있어야 합니다.

Node.js 설치

Marp CLI 설치 

npm install -g @marp-team/marp-cli

Marp 설치 확인 

marp --version

Marp 통합

파일 구조 설계

Marp 통합을 위해 다음과 같은 파일 구조를 추천합니다:

/
├── content/
│   ├── slide/
│   │   ├── example-slide.md
├── layouts/
│   ├── _default/
│   │   └── single.html
├── static/
│   └── slides/
│       └── example-slide.html
├── script/
│   └── change_marp.py

Markdown 파일 작성

content/slide/example-slide.md:

---
title: Example Slide
type: slide
---

# 첫 번째 슬라이드

Marp는 Markdown을 슬라이드로 변환하는 강력한 도구입니다.

---

# 두 번째 슬라이드

Hugo와 함께 사용하면 훨씬 더 강력한 기능을 제공합니다.

Python 스크립트로 변환 자동화

Python 스크립트를 사용하여 Markdown 파일을 HTML 슬라이드로 변환하고 static/slides 폴더에 저장합니다.

script/change_marp.py:

import os
import subprocess
import yaml

SOURCE_DIR = "content"
TARGET_DIR = "static/slides"

MARP_CMD = "marp"  # Marp CLI 실행 경로

def convert_marp_files(source_dir, target_dir):
    for root, dirs, files in os.walk(source_dir):
        for file in files:
            if file.endswith(".md"):
                file_path = os.path.join(root, file)
                with open(file_path, "r", encoding="utf-8") as f:
                    metadata = yaml.safe_load_all(f.read())
                    metadata = list(metadata)[0]
                if metadata.get("type") == "slide":
                    relative_path = os.path.relpath(file_path, SOURCE_DIR)
                    output_path = os.path.join(
                        target_dir,
                        os.path.splitext(relative_path)[0].replace("\\", "/").lower() + ".html"
                    )
                    os.makedirs(os.path.dirname(output_path), exist_ok=True)
                    subprocess.run([MARP_CMD, file_path, "-o", output_path], check=True)

if __name__ == "__main__":
    convert_marp_files(SOURCE_DIR, TARGET_DIR)

이 스크립트는 content 폴더에서 type: slide가 설정된 Markdown 파일을 찾아 Marp를 사용해 HTML 슬라이드로 변환합니다.

Hugo 템플릿 설정

Hugo의 single.html 템플릿을 수정하여 type: slide가 설정된 페이지를 슬라이드로 렌더링합니다.

layouts/_default/single.html:

{{ define "main" }}
  <div class="content">
    <h1>{{ .Title }}</h1>
    {{ if eq .Params.type "slide" }}
      <iframe 
          src="/slides{{ .File.Dir | replace "content" "" | replace "\\" "/" | lower }}{{ .File.BaseFileName | lower }}.html" 
          width="100%" 
          height="800" 
          frameborder="0">
      </iframe>
    {{ else }}
      {{ .Content }}
    {{ end }}
  </div>
{{ end }}

Hugo 실행

  • 변환 스크립트 실행:
python script/change_marp.py
  • Hugo 서버 실행:
hugo server --gc --minify --ignoreCache --disableFastRender
  • 브라우저에서 확인
    • 슬라이드 경로: http://localhost:1313/slide/example-slide/

최종 확인

Markdown 파일 작성

  • content 폴더에 Markdown 파일 작성.
  • type: slide 설정으로 슬라이드 파일임을 명시.

HTML 파일 생성

  • Python 스크립트 실행으로 static/slides에 HTML 파일 생성.

Hugo 템플릿에서 iframe 렌더링

  • type: slide일 경우 iframe으로 슬라이드 렌더링.
Buy me a coffee Buy me a coffee
D2 다이어그램 렌더링