Markdown • Sep 24, 2026 • 4 min read

Soolog Markdown Master Reference

Soolog에서 글을 작성할 때 필요한 Markdown, Hugo shortcode, HTML, Mermaid, 수식, 코드, 미디어 기능을 한 파일에서 확인하는 실전 레퍼런스

Soolog Markdown Master Reference🔗

이 파일 하나만 열어두고 글을 작성하기 위한 치트시트입니다. 기본 Markdown → Hugo 확장 → Soolog 커스텀 shortcode → HTML → Mermaid → 수식 → 코드 → 미디어 순서로 정리했습니다.

0. 새 글 기본 템플릿🔗

---
title: "제목"
description: "검색 결과와 글 목록에 보이는 짧은 설명"
date: 2026-09-24
draft: true
tags: ["Tag1", "Tag2"]
categories: ["Development"]
# math: true       # 수식이 있을 때만
---

# 제목

한 줄 요약.

## 본문

여기에 작성합니다.

작성 중에는 draft: true
발행할 때 draft: false
수식이 있을 때만 math: true
date는 실제 작성/발행 기준 날짜를 사용

1. 제목🔗

# H1
## H2
### H3
#### H4

Hugo는 제목에 자동 ID를 만들고 Soolog에는 제목 앵커 복사 기능이 있습니다.

2. 글자 꾸미기🔗

목적	문법
굵게	`굵게`
기울임	`기울임`
굵게+기울임	`*둘 다*`
취소선	`~~취소~~`
인라인 코드	`code`
강조	`==강조==`
위첨자	`x^2^`
아래첨자	`<sub>2</sub>`
링크	`[텍스트](https://example.com)`
이미지	`![설명](/images/a.jpg)`

굵게, 기울임, 둘 다, 취소, code, 강조, x², H₂O

Soolog에서는 ~~ 취소선과 충돌하기 때문에 아래첨자는 <sub>를 사용합니다.

3. 목록🔗

- 항목
- 항목
  - 하위 항목

1. 첫 번째
2. 두 번째

- [x] 완료
- [ ] 미완료

4. 링크🔗

[Hugo](https://gohugo.io/)
[내 글](/post/sample/)
<https://gohugo.io/>

Soolog의 render hook은 외부 링크를 새 탭으로 열도록 처리합니다.

5. 이미지🔗

![대체 텍스트](/images/example.jpg)

이미지 파일은 일반적으로 static/images/에 넣습니다.

HTML이 필요하면:

<figure>
  <img src="/images/example.jpg" alt="설명" loading="lazy">
  <figcaption>사진 설명</figcaption>
</figure>

6. 인용🔗

> 한 줄 인용
>
> 여러 줄도 가능합니다.

7. 코드🔗

인라인🔗

`hugo server -D`

코드 블록🔗

```bash
hugo server -D
hugo --gc --minify
```

줄 번호🔗

```javascript {linenos=true}
const answer = 42;
console.log(answer);
```

특정 줄 강조🔗

Hugo의 Chroma 설정/코드 블록 옵션을 사용할 수 있습니다. 복잡한 옵션은 Hugo 공식 문서를 확인합니다.

8. 표🔗

| 항목 | 가격 | 상태 |
|---|---:|:---:|
| A | 10000 | ✅ |
| B | 20000 | ❌ |

항목	가격	상태
A	10,000	✅
B	20,000	❌

9. 체크리스트🔗

- [x] 완료
- [ ] 할 일

완료
할 일

10. 구분선🔗

---

11. 각주🔗

Hugo는 정적 사이트 생성기입니다.[^1]

[^1]: 공식 문서를 기준으로 작성했습니다.

Hugo는 정적 사이트 생성기입니다.¹

12. 내부 링크🔗

[이 섹션으로 이동](#12-내부-링크)
[맨 위로](#)

13. HTML을 직접 사용하기🔗

Soolog는 unsafe = true이므로 직접 HTML을 사용할 수 있습니다.

<kbd>Ctrl</kbd> + <kbd>K</kbd>

<details>
  <summary>눌러서 펼치기</summary>
  숨겨진 내용입니다.
</details>

<mark>형광펜</mark>

<small>작은 글씨</small>

unsafe = true는 본인이 작성하는 신뢰할 수 있는 Markdown에만 사용합니다. 외부 사용자의 입력을 그대로 HTML로 렌더링하는 용도로 사용하면 안 됩니다.

14. Soolog 커스텀 Shortcode🔗

14-1. 키보드🔗


Ctrl+Shift+P

CtrlShiftP

14-2. 약어🔗

UDS

UDS

14-3. Callout🔗


  💡TIP
  여기에 내용을 작성합니다.

지원 type: note, tip, warning, danger

14-4. 형광펜🔗

민트 강조

지원 색상은 현재 shortcode 파일의 정의를 기준으로 사용합니다.

14-5. 탭🔗



기본
내용 A



상세
내용 B

14-6. 스포일러🔗

눌러서 보기
숨겨진 내용

14-7. 홀로그램 카드🔗


  
  
    ✈️
    서울 → 도쿄
    Soolog
    여기에 카드 내용

14-8. 별점 표시🔗

가성비
    ★★★★★
    ★★★★★
  
  4.5 / 5

주의: 이것은 시각적 표시용 shortcode이며 방문자 투표 시스템이 아닙니다.

14-9. 진행 바🔗


  완료율80%

14-10. 카운트다운🔗


  D-Day
  
    --일
    --시간
    --분
    --초
  
  🎉 디데이가 지났습니다!

14-11. 원클릭 복사🔗


  복사할 내용

14-12. 컨페티🔗

14-13. QR🔗



  
  https://8d69f7f6.soolog.pages.dev/ko/post/markdown-reference/

14-14. 반응 버튼🔗

이 shortcode는 기존 버전에서 localStorage 기반입니다. 전체 방문자에게 공유되는 진짜 집계가 필요하면 새로 추가된 likes 기능을 사용합니다.

14-15. 실제 공유 좋아요🔗


  
  불러오는 중…

Firebase 설정이 완료된 사이트에서만 표시됩니다.

15. Mermaid🔗

Soolog는 Mermaid 11.17.2를 hugo.toml의 [params.mermaid].version으로 고정합니다. 렌더링은 Hugo의 전역 layouts/_markup/render-codeblock-mermaid.html hook에서 Mermaid 블록을 표시하고, 게시글 템플릿에서 해당 버전을 CDN으로 불러옵니다. 버전을 바꿀 때는 hugo.toml의 한 곳만 수정하세요.

Soolog에서는 다음처럼 작성합니다.

```mermaid
flowchart LR
    A[시작] --> B[작성]
    B --> C{검토}
    C -->|통과| D[발행]
    C -->|수정| B
```

flowchart LR
    A[시작] --> B[작성]
    B --> C{검토}
    C -->|통과| D[발행]
    C -->|수정| B

Mermaid에서 오류가 날 때🔗

먼저 이 레퍼런스의 위 예제를 그대로 붙여 테스트합니다.
한글/이모지/괄호/특수문자를 하나씩 제거합니다.
노드 텍스트가 복잡하면 A[텍스트]처럼 단순하게 만듭니다.
flowchart LR, sequenceDiagram, mindmap처럼 다이어그램 종류를 정확히 적습니다.
Soolog의 Mermaid render hook이 활성화되어 있어야 합니다.

권장 최소 문법:

flowchart TD
    A[Start] --> B[End]

16. 수식 (KaTeX)🔗

front matter:

math: true

인라인:

\(E = mc^2\)

$E = mc^2$

블록:

$$
E = mc^2
$$

$$ E = mc^2 $$

17. HTML로 만들 수 있는 재미있는 기능🔗

접기/펼치기🔗

<details>
  <summary>상세 내용 보기</summary>

  숨겨진 내용입니다.
</details>

상세 내용 보기

숨겨진 내용입니다.

진행률🔗

<label>진행률</label>
<progress value="72" max="100">72%</progress>

진행률 72%

범위 슬라이더🔗

<input type="range" min="0" max="100" value="70" disabled>

18. 미디어🔗

YouTube🔗

테마/사이트에서 지원하는 shortcode가 없다면 HTML iframe을 사용합니다.

<iframe
  src="https://www.youtube.com/embed/VIDEO_ID"
  title="YouTube video"
  loading="lazy"
  allowfullscreen>
</iframe>

오디오🔗

<audio controls preload="none">
  <source src="/audio/sample.mp3" type="audio/mpeg">
</audio>

19. 특수문자 그대로 출력하기🔗

\*별표 그대로\*
\# 샵 그대로
\[대괄호 그대로\]

20. 글 작성용 추천 순서🔗

Front Matter
    ↓
제목 / 요약
    ↓
핵심 내용
    ↓
이미지 / 표 / 코드
    ↓
Callout / Tabs / Details
    ↓
Mermaid / 수식
    ↓
태그 / 카테고리 확인
    ↓
좋아요 / 댓글 확인
    ↓
hugo server -D
    ↓
draft: false
    ↓
Git push

자주 쓰는 것만 다시 보기🔗

**굵게**
*기울임*
~~취소선~~
==강조==
`code`

[링크](https://example.com)
![이미지](/images/example.jpg)

> 인용

- 목록
- [ ] 체크
- [x] 완료


  💡TIP
  TIP



Ctrl+K

보기
내용


  
  불러오는 중…

이 레퍼런스의 예시입니다. ↩︎

0 불러오는 중…