Markdown Rendering Guide

이 글은 새 글을 작성할 때 확인할 수 있는 Markdown 렌더링 샘플이다. frontmatter 작성법부터 본문에서 자주 쓰는 문법까지 한 번에 확인하는 용도로 둔다.

Frontmatter

글은 src/content/posts/<postSlug>/index.mdx에 작성한다. 폴더 이름이 글의 주소가 되고, 공개 글은 status: "published"를 사용한다.

---
title: '글 제목'
description: '목록과 메타 태그에 쓰이는 짧은 설명'
publishedAt: 2026-05-21T01:20:00+09:00
updatedAt: 2026-05-21T01:20:00+09:00
category: 'dev'
tags:
    - markdown
    - mdx
series:
    slug: 'optional-series'
    title: '선택 시리즈 제목'
    description: '시리즈 설명은 첫 번째 글 기준으로 사용된다'
    order: 1
status: 'published'
---

필수에 가깝게 쓰는 값은 title, description, publishedAt, category, tags, status다. 시리즈가 아니면 series는 쓰지 않는다.

status는 글의 공개 범위를 결정한다.

published: 목록, 상세 페이지, 카테고리, 태그, 시리즈에 공개한다.
draft: 작성 중인 글이다. 로컬 개발 환경에서 미리보기 용도로만 사용한다.
hidden: 공개 목록과 상세 페이지 어디에도 노출하지 않는다.

발행할 글은 published, 아직 쓰는 중인 글은 draft, 임시로 완전히 숨길 글은 hidden으로 둔다.

Headings

본문에서는 보통 ##부터 시작한다. 페이지의 큰 제목은 상세 페이지 헤더에서 이미 렌더링되기 때문이다.

H3 heading

세부 섹션은 ###를 사용한다.

H4 heading

더 작은 단위가 필요하면 ####를 사용할 수 있지만, 너무 깊어지면 글 구조를 다시 나누는 편이 낫다.

Paragraphs and Text Styles

문단은 빈 줄로 구분한다. 한 문단 안에서는 너무 많은 스타일을 섞지 않는 편이 읽기 쉽다.

굵은 글씨는 중요한 용어에 사용한다. 기울임은 뉘앙스나 짧은 강조에 사용한다. 굵은 기울임도 가능하지만 자주 쓰지는 않는다.

인라인 코드는 src/lib/posts.ts, publishedAt, npm run build처럼 파일명, 필드명, 명령어를 표시할 때 쓴다.

링크는 Astro documentation처럼 작성한다.

Lists

순서가 없는 목록은 항목을 빠르게 훑게 할 때 좋다.

frontmatter를 먼저 작성한다.
본문은 큰 섹션부터 나눈다.
이미지가 있으면 글 폴더 안에 함께 둔다.

순서가 중요한 흐름은 번호 목록을 사용한다.

글 폴더를 만든다.
index.mdx를 작성한다.
npm run build로 확인한다.
필요한 경우 미리보기에서 레이아웃을 점검한다.

중첩 목록도 가능하다.

Markdown
- heading
- paragraph
- list
MDX
- local image
- inline HTML

Blockquote

인용문은 글 안에서 원칙이나 요약을 강조할 때 사용한다.

좋은 작성 경험은 문법을 많이 외우는 것이 아니라, 반복해서 쓰는 구조가 예측 가능해지는 것이다.

여러 줄 인용도 가능하다.

글의 주소는 폴더명으로 고정한다.

제목, 카테고리, 태그는 나중에 바뀔 수 있지만 URL은 쉽게 바꾸지 않는다.

Code Blocks

코드 블록에는 언어 이름을 붙인다.

type PostStatus = 'published' | 'draft' | 'hidden';

function isPublicPost(status: PostStatus) {
    return status === 'published';
}

명령어는 bash로 표시한다.

npm run build
npm run test:e2e

긴 줄이 있는 코드도 가로 스크롤로 확인할 수 있다.

src/content/posts/markdown-rendering-guide/index.mdx -> /posts/markdown-rendering-guide

Images

글에 쓰는 이미지는 같은 폴더 안에 둔다. 아래 이미지는 diagram.svg를 Markdown 이미지 문법으로 불러온 것이다.

Frontmatter, Markdown body, and rendered blog page flow

Horizontal Rule

구분선은 긴 글에서 흐름을 잠깐 끊을 때만 사용한다.

구분선 뒤의 문단은 새로운 장면처럼 읽힌다. 너무 자주 쓰면 글이 조각나 보인다.

GitHub Flavored Markdown Check

아래 문법은 GitHub에서 자주 쓰지만, 프로젝트 설정에 따라 다르게 렌더링될 수 있다. 이 블로그에서 실제로 어떻게 보이는지 확인하기 위해 남겨둔다.

Task List

frontmatter 작성
본문 작성
최종 미리보기 확인

Table

문법	용도	사용 빈도
`##`	큰 섹션	높음
`>`	인용	중간
code fence	코드 블록	높음

Strikethrough

~~삭제된 문장처럼 보이는지 확인한다.~~

Inline HTML in MDX

MDX에서는 간단한 HTML도 사용할 수 있다.

접힌 내용을 열어보기

이 영역은 MDX 안에 작성한 HTML이다. 복잡한 UI가 필요하면 Astro 컴포넌트로 분리하는 편이 낫다.

Writing Checklist

새 글을 발행하기 전에 아래 순서로 확인한다.

publishedAt에 시간대가 포함되어 있는지 확인한다.
목록에서 보일 description이 너무 길지 않은지 확인한다.
카테고리와 태그가 기존 분류와 맞는지 확인한다.
이미지가 글 폴더 안에 있는지 확인한다.
npm run build로 MDX 파싱과 타입 검사를 통과하는지 확인한다.