Reveal.js - Markdown을 프레젠테이션 웹페이지로 만들기

Reveal.js는 Markdown 파일을 프레젠테이션용 웹 페이지로 만들어주는 플러그인 입니다. 급하게 PT를 해야 할 경우 상당히 유용하게 사용할 수 있습니다.

Posted Aug 19, 2025

16 min read

1. Reveal.js란?

Reveal.js는 HTML 기반의 오픈소스 프레젠테이션 프레임워크임. 개발자에게 친화적이며, 마크다운 지원, 다양한 테마, 플러그인, Jekyll 등 정적 블로그와의 호환성이 특징임.

주요 특징

마크다운 지원: 간단한 문법으로 슬라이드 작성 가능
다양한 테마/전환 효과: 여러 내장 테마와 전환 효과 제공
플러그인 생태계: 메뉴, 발표자 노트, 코드 하이라이트 등 확장 가능
정적 사이트와 호환: Jekyll, Hugo 등과 연동 쉬움

2. 설치 방법

Reveal.js는 CDN 또는 npm 등으로 설치해 사용할 수 있음.

CDN 사용

별도 설치 없이 HTML에서 바로 불러와 사용함.

  
<!-- Reveal.js core CSS -->
<link rel="stylesheet" href="https://unpkg.com/reveal.js/dist/reveal.css" />
<!-- Reveal.js 테마 CSS (예: black, white 등) -->
<link rel="stylesheet" href="https://unpkg.com/reveal.js/dist/theme/black.css" id="theme" />
<!-- 코드 하이라이트 CSS (선택) -->
<link rel="stylesheet" href="https://unpkg.com/reveal.js/plugin/highlight/monokai.css" />

<!-- Reveal.js core JS -->
<script src="https://unpkg.com/reveal.js/dist/reveal.js"></script>
<!-- 플러그인 JS (마크다운, 하이라이트, 노트 등) -->
<script src="https://unpkg.com/reveal.js/plugin/markdown/markdown.js"></script>
<script src="https://unpkg.com/reveal.js/plugin/highlight/highlight.js"></script>
<script src="https://unpkg.com/reveal.js/plugin/notes/notes.js"></script>

npm으로 로컬 설치

npm install reveal.js

설치 후, 아래와 같이 import해서 사용함.

  
import Reveal from 'reveal.js';
import Markdown from 'reveal.js/plugin/markdown/markdown.esm.js';

const deck = new Reveal({
    plugins: [ Markdown ]
});
deck.initialize();

3. 기본 사용법

Reveal.js는 HTML 파일 하나만으로도 바로 프레젠테이션을 만들 수 있음. 아래는 CDN 방식 예시임.

HTML 기본 구조

아래 코드는 Reveal.js를 CDN으로 불러와 외부 마크다운 파일(slides.md)을 슬라이드로 보여주는 기본 예시임.

  
<!doctype html>
<html lang="ko">
<head>
        <meta charset="utf-8" />
        <title>Reveal.js Markdown Deck</title>
        <meta name="viewport" content="width=device-width, initial-scale=1" />

        <!-- Reveal core CSS -->
        <link rel="stylesheet" href="https://unpkg.com/reveal.js/dist/reveal.css" />
        <!-- Reveal theme (black, white, league, beige, sky, night, serif, simple, solarized ...) -->
        <link rel="stylesheet" href="https://unpkg.com/reveal.js/dist/theme/black.css" id="theme" />

        <!-- Code highlight theme -->
        <link rel="stylesheet" href="https://unpkg.com/reveal.js/plugin/highlight/monokai.css" />
</head>
<body>
        <div class="reveal">
                <div class="slides">
                        <!-- 외부 Markdown 파일 로드 -->
                        <section data-markdown="slides.md"
                                         data-separator="^\s*---\s*$"
                                         data-separator-vertical="^\s*--\s*$"
                                         data-separator-notes="^Notes?:">
                        </section>
                </div>
        </div>

        <!-- 또는 HTML 내에 직접 마크다운 작성도 가능함 -->
        <!--
        <section data-markdown>
            <textarea data-template>
                # 첫 슬라이드
                ---
                # 두 번째 슬라이드
            </textarea>
        </section>
        -->

        <!-- Reveal core JS -->
        <script src="https://unpkg.com/reveal.js/dist/reveal.js"></script>
        <!-- Plugins -->
        <script src="https://unpkg.com/reveal.js/plugin/markdown/markdown.js"></script>
        <script src="https://unpkg.com/reveal.js/plugin/highlight/highlight.js"></script>
        <script src="https://unpkg.com/reveal.js/plugin/notes/notes.js"></script>

        <script>
                Reveal.initialize({
                        hash: true,
                        plugins: [ RevealMarkdown, RevealHighlight, RevealNotes ]
                });
        </script>
</body>
</html>

위 코드는 외부 마크다운 파일(slides.md) 또는 HTML 내 textarea에 직접 작성한 마크다운을 슬라이드로 변환해 보여줌.

4. 옵션 및 상세 설정

Reveal.initialize 함수에 다양한 옵션을 전달해 슬라이드의 동작과 외형을 세밀하게 제어할 수 있음. 주요 파라미터는 아래 표 참고.

기본 설정

속성	타입	설명	기본값
`width`	`number`	프레젠테이션의 기본 너비 (px)	`960`
`height`	`number`	프레젠테이션의 기본 높이 (px)	`700`
`margin`	`number`	슬라이드 콘텐츠와 가장자리 사이의 여백	`0.04`
`minScale`	`number`	최소 허용 스케일	`0.2`
`maxScale`	`number`	최대 허용 스케일	`2.0`

네비게이션 및 제어

속성	타입	설명	기본값
`controls`	`boolean`	컨트롤 화살표 표시 여부	`true`
`controlsLayout`	`string`	컨트롤 화살표 위치 (‘bottom-right’ 또는 ‘edges’)	`'bottom-right'`
`progress`	`boolean`	진행률 표시줄 표시 여부	`true`
`slideNumber`	`boolean` / `string`	슬라이드 번호 표시. `c/t` 형식으로 포맷 지정 가능	`false`
`history`	`boolean`	브라우저 히스토리에 슬라이드 변경 기록	`false`
`hash`	`boolean`	URL 해시에 슬라이드 상태 반영	`false`
`keyboard`	`boolean`	키보드 단축키 활성화	`true`
`mouseWheel`	`boolean`	마우스 휠을 이용한 슬라이드 이동 활성화	`false`
`loop`	`boolean`	프레젠테이션 무한 반복	`false`
`rtl`	`boolean`	오른쪽에서 왼쪽으로 텍스트 방향 설정	`false`

외형 및 효과

속성	타입	설명	기본값
`center`	`boolean`	슬라이드 수직 가운데 정렬	`true`
`transition`	`string`	전역 슬라이드 전환 효과. (‘none’, ‘fade’, ‘slide’, ‘convex’, ‘concave’, ‘zoom’)	`'slide'`
`transitionSpeed`	`string`	전환 속도. (‘default’, ‘fast’, ‘slow’)	`'default'`
`backgroundTransition`	`string`	배경 전환 효과.	`'fade'`
`fragments`	`boolean`	프래그먼트(점진적 표시) 전역 활성화	`true`
`embedded`	`boolean`	다른 웹 페이지에 임베드된 경우	`false`

자동 슬라이드

속성	타입	설명	기본값
`autoSlide`	`number`	자동 슬라이드 전환 딜레이 (ms). `0`이면 비활성화.	`0`
`autoSlideStoppable`	`boolean`	사용자가 상호작용하면 자동 슬라이드 중지	`true`

이 외에도 플러그인별 설정을 추가할 수 있음. 예) menu, math 플러그인은 아래처럼 추가함.

전체 파라미터 샘플 코드

아래는 Reveal.js의 주요 옵션을 모두 포함하고, 각 파라미터별로 적용 가능한 값과 기본값을 주석으로 표기한 샘플 코드임.

  
Reveal.initialize({
    // 기본 설정
    width: 960, // number, 기본값 960
    height: 700, // number, 기본값 700
    margin: 0.04, // number, 기본값 0.04
    minScale: 0.2, // number, 기본값 0.2
    maxScale: 2.0, // number, 기본값 2.0

    // 네비게이션 및 제어
    controls: true, // boolean, 기본값 true
    controlsLayout: 'bottom-right', // 'bottom-right' | 'edges', 기본값 'bottom-right'
    progress: true, // boolean, 기본값 true
    slideNumber: false, // boolean | 'c/t' | 'h.v' | 'c', 기본값 false
    history: false, // boolean, 기본값 false
    hash: false, // boolean, 기본값 false
    keyboard: true, // boolean, 기본값 true
    mouseWheel: false, // boolean, 기본값 false
    loop: false, // boolean, 기본값 false
    rtl: false, // boolean, 기본값 false

    // 외형 및 효과
    center: true, // boolean, 기본값 true
    transition: 'slide', // 'none' | 'fade' | 'slide' | 'convex' | 'concave' | 'zoom', 기본값 'slide'
    transitionSpeed: 'default', // 'default' | 'fast' | 'slow', 기본값 'default'
    backgroundTransition: 'fade', // 'none' | 'fade' | 'slide' | 'convex' | 'concave' | 'zoom', 기본값 'fade'
    fragments: true, // boolean, 기본값 true
    embedded: false, // boolean, 기본값 false

    // 자동 슬라이드
    autoSlide: 0, // number(ms), 기본값 0 (비활성화)
    autoSlideStoppable: true, // boolean, 기본값 true

    // 플러그인
    plugins: [ RevealMarkdown, RevealHighlight, RevealNotes ],

    // 플러그인별 추가 옵션 예시
    menu: {
        side: 'left', // 'left' | 'right', 기본값 'left'
        numbers: false, // boolean, 기본값 false
        markers: true, // boolean, 기본값 true
        openButton: true, // boolean, 기본값 true
        titleSelector: 'h1, h2, h3, h4, h5, h6' // string, 기본값
    },
    math: {
        mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js',
        config: 'TeX-AMS_HTML-full'
    }
});

위 샘플은 Reveal.js의 주요 옵션과 플러그인 옵션을 한눈에 볼 수 있도록 정리한 예시임. 실제로는 필요한 옵션만 골라서 사용하면 됨.

5. 마크다운으로 슬라이드 작성하기

data-markdown 속성으로 외부 마크다운 파일을 불러오거나, HTML 내에 직접 마크다운을 작성할 수 있음.

슬라이드 구분

수평 슬라이드: --- (세 개의 하이픈)
수직 슬라이드: -- (두 개의 하이픈)

외부 파일 예시 (slides.md)

  
# 첫 번째 슬라이드

---

# 두 번째 슬라이드

--

## 두 번째 슬라이드의 하위 슬라이드

HTML 내 직접 작성 예시

  
<section data-markdown>
    <textarea data-template>
        # 첫 슬라이드
        ---
        # 두 번째 슬라이드
    </textarea>
</section>

위 코드는 별도 파일 없이 HTML 내에서 바로 마크다운 슬라이드를 작성하는 방법임.

발표자 노트

슬라이드에 발표자 노트를 추가하려면 Notes: 키워드를 사용함. 발표자 모드에서만 노트를 볼 수 있음.

# 슬라이드 제목

여기에 내용이 들어감.

Notes:
이것은 발표자 노트임.

점진적 표시 (Fragments)

콘텐츠를 순차적으로 표시하려면 HTML 주석으로 fragment 클래스를 추가함. 아래 예시처럼 사용함.

  
- 첫 번째 항목
- 두 번째 항목 <!-- .element: class="fragment" -->
- 세 번째 항목 <!-- .element: class="fragment" -->

6. 플러그인 활용

메뉴 플러그인

슬라이드 개요를 보여주는 메뉴를 추가할 수 있음.

HTML 설정

  
<!-- Menu plugin CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/reveal.js-menu@2.1.0/menu.css" />

<!-- Menu plugin JS -->
<script src="https://cdn.jsdelivr.net/npm/reveal.js-menu@2.1.0/menu.js"></script>

<script>
    Reveal.initialize({
        plugins: [ RevealMarkdown, RevealHighlight, RevealNotes, RevealMenu ],
        menu: {
            side: 'left',
            numbers: true,
            markers: true,
            openButton: true
        }
    });
</script>

위 코드는 메뉴 플러그인을 추가해 슬라이드 왼쪽에 개요 메뉴를 표시함. 메뉴 위치, 번호, 마커, 버튼 등 다양한 옵션을 조정할 수 있음.

주요 메뉴 설정

속성	설명	기본값
`side`	메뉴가 표시될 위치 (`'left'` 또는 `'right'`)	`'left'`
`numbers`	메뉴 항목에 슬라이드 번호를 표시함.	`false`
`markers`	현재 슬라이드를 마커로 표시함.	`true`
`openButton`	메뉴를 여는 버튼을 표시함.	`true`
`titleSelector`	메뉴 제목으로 사용할 HTML 태그를 지정함.	`'h1, h2, h3, h4, h5, h6'`

7. 테마와 전환 효과

테마

다양한 내장 테마를 사용할 수 있음. 테마를 변경하려면 CSS 파일의 링크를 수정하면 됨.

테마	설명
`black`	어두운 배경, 흰색 텍스트
`white`	밝은 배경, 검은색 텍스트
`league`	회색 배경, 흰색 텍스트
`beige`	베이지색 배경, 어두운 텍스트
`sky`	하늘색 배경, 어두운 텍스트
`night`	어두운 배경, 밝은 파란색 텍스트
`serif`	갈색 배경, 흰색 텍스트
`simple`	간단한 스타일
`solarized`	Solarized 색상 팔레트

전환 효과

슬라이드 간 전환 효과를 설정할 수 있음.

효과	설명
`none`	효과 없음
`fade`	서서히 사라지고 나타남
`slide`	슬라이드
`convex`	볼록한 효과
`concave`	오목한 효과
`zoom`	확대/축소 효과

8. 고급 기능

수학 공식 (MathJax)

Reveal.js는 MathJax 플러그인을 통해 LaTeX 수학 공식을 렌더링할 수 있음.

HTML 설정

  
<!-- MathJax 플러그인 추가 -->
<script src="https://unpkg.com/reveal.js/plugin/math/math.js"></script>

<script>
    Reveal.initialize({
        plugins: [ RevealMarkdown, RevealHighlight, RevealNotes, RevealMath.MathJax2 ],
        math: {
            mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js',
            config: 'TeX-AMS_HTML-full'
        }
    });
</script>

위 코드는 Reveal.js에서 수학 공식을 LaTeX 문법으로 표현할 수 있게 해줌. 인라인($ ... $)과 블록($$ ... $$) 모두 지원함.

마크다운 예시

  
인라인 공식: \( E = mc^2 \)

블록 공식:
$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$

9. PDF 내보내기 및 배포

PDF 내보내기

Reveal.js는 슬라이드를 PDF로 내보내는 기능을 지원함. 슬라이드 페이지에서 URL 뒤에 ?print-pdf를 붙여 접속한 뒤 브라우저 인쇄(Ctrl+P)로 PDF로 저장할 수 있음.

https://your-site.com/slides.html?print-pdf

배포 및 호스팅 팁

Reveal.js 프레젠테이션은 정적 HTML 파일이므로 GitHub Pages, Netlify, Vercel 등 정적 사이트 호스팅 서비스에 바로 배포 가능함. Jekyll, Hugo 등 정적 블로그와도 쉽게 연동됨.

10. 결론

Reveal.js는 마크다운 기반으로 프레젠테이션을 만들고 관리할 수 있는 강력한 도구임. 특히 버전 관리가 중요한 개발 프로젝트나 기술 발표 자료를 만들 때 매우 유용함. Jekyll 블로그에 통합하여 기술 포스트를 더욱 동적으로 만들 수도 있음.

05.Frontend, Javascript

This post is licensed under CC BY 4.0 by the author.