📝 Markdown 스타일 가이드

이 글은 Astro-Theme-Aither가 지원하는 모든 Markdown 기능을 보여줍니다. 글을 작성할 때 참고 자료로 활용하세요. 이 페이지를 북마크하세요 — 사용 가능한 모든 서식 옵션을 다룹니다.

제목

섹션 제목에는 ##을, 하위 섹션에는 ###을, 하위의 하위 섹션에는 ####을 사용하세요. 글 내용에서는 #을 피하세요 — 글 제목이 이미 최상위 제목으로 렌더링됩니다.

3단계 제목

3단계 제목은 섹션을 뚜렷한 주제로 나누는 데 적합합니다. 너무 눈에 띄지 않으면서 시각적 계층을 만들어줍니다.

4단계 제목

4단계 제목은 세부적인 하위 섹션에 적합합니다. 드물게 사용하세요 — 개요가 4단계보다 깊어진다면 콘텐츠 구조를 재검토하는 것이 좋습니다.

제목 모범 사례

효과적인 제목 사용을 위한 몇 가지 지침:

• 단계를 건너뛰지 마세요 — ##에서 ###으로, 절대 ##에서 바로 ####로 가지 마세요. 단계를 건너뛰면 문서 개요가 깨지고 스크린 리더를 혼란스럽게 할 수 있습니다.
• 제목을 설명적으로 유지하세요 — “설정 관련”보다 “환경 설정”이 좋습니다. 독자들은 섹션을 읽을지 결정하기 전에 제목을 훑어봅니다.
• 문장 표기법을 사용하세요 — 첫 단어와 고유명사만 대문자로 씁니다.

단락과 줄 바꿈

일반 단락 텍스트는 자연스럽게 흐릅니다. 단락을 구분하려면 빈 줄을 남기세요.

이것은 두 번째 단락입니다. 최상의 읽기 경험을 위해 단락은 하나의 아이디어에 집중하세요.

웹 글쓰기에서는 짧은 단락이 긴 텍스트 블록보다 잘 작동합니다. 화면에서 편안하게 읽을 수 있는 단위는 35문장입니다. 67문장을 넘어가면 분리를 고려하세요.

단락 내에서의 단일 줄 바꿈(빈 줄 없이)은 새 줄이 아닌 공백으로 처리됩니다. 새 단락 없이 강제 줄 바꿈이 필요하면 줄 끝에 공백 두 개를 넣거나 <br> 태그를 사용하세요 — 실제로는 거의 필요하지 않습니다.

강조

• 굵은 텍스트 **이중 별표**로 표시
• 기울임 텍스트 *단일 별표*로 표시
• 굵은 기울임 ***삼중 별표***로 표시
• 취소선 ~~이중 물결표~~로 표시

각 스타일 사용 시점

굵게는 핵심 용어, 중요한 경고, 정의 등 — 훑어봐도 놓치면 안 되는 것에 적합합니다. 단락에서 가장 중요한 문구에 사용하고, 전체 문장에는 사용하지 마세요.

기울임은 문장 내 강조, 책 및 출판물 제목, 처음 사용하는 기술 용어, 외국어 표현에 적합합니다. 굵게보다 부드러운 강조를 제공합니다.

취소선은 수정 사항, 더 이상 사용되지 않는 정보, 변경 로그의 완료 항목 표시에 유용합니다. 사용 범위는 좁지만 필요할 때 가치 있습니다.

링크

인라인 링크 [텍스트](url) 구문으로 작성합니다.

링크는 상대 경로를 사용하여 사이트의 다른 글을 참조할 수도 있습니다. 설명적인 링크 텍스트를 사용하세요 — “여기를 클릭하세요”보다 “마크다운 가이드를 읽어보세요”가 좋습니다. 좋은 링크 텍스트는 독자와 검색 엔진 모두 링크 목적지를 이해하는 데 도움이 됩니다.

문장 내에서 자연스럽게 읽히는 설명적 앵커 텍스트를 작성할 수도 있습니다. 예를 들어: Astro 공식 문서에서 모든 기능을 자세히 다룹니다.

목록

비순서 목록:

• 첫 번째 항목
• 두 번째 항목
  • 중첩 항목
  • 또 다른 중첩 항목
• 세 번째 항목

순서 목록:

1. 첫 번째 단계
2. 두 번째 단계
   1. 하위 단계 1
   2. 하위 단계 2
3. 세 번째 단계

작업 목록:

• 프로젝트 설정
• 첫 번째 글 작성
• 프로덕션 배포

목록 서식 팁

목록은 웹 글쓰기에서 가장 효과적인 도구 중 하나입니다. 밀도 높은 텍스트를 나누고, 정보를 훑어볼 수 있게 만들며, 순서나 항목 모음을 명확히 전달합니다.

비순서 목록은 항목에 순서가 없을 때 사용하세요 — 기능, 요구사항, 옵션, 예시.

순서 목록은 순서가 중요할 때 사용하세요 — 프로세스 단계, 순위, 순서대로 따라야 하는 지침.

작업 목록은 진행 상황 추적, 프로젝트 체크리스트, 할 일 항목에 사용하세요. 많은 Markdown 뷰어에서 인터랙티브 체크박스로 렌더링되지만, 정적 블로그에서는 시각적 지표로 나타납니다.

목록 항목의 구조를 일관되게 유지하세요. 첫 번째 항목이 동사로 시작하면 모든 항목이 동사로 시작해야 합니다. 첫 번째 항목이 명사구이면 그 패턴을 유지하세요.

인용문

추상화의 목적은 모호해지는 것이 아니라, 절대적으로 정확할 수 있는 새로운 의미 수준을 만드는 것이다.

— Edsger W. Dijkstra

중첩 인용문:

첫 번째 단계

두 번째 단계

세 번째 단계

인용문 사용법

인용문은 유명인의 말을 인용하는 것 외에도 여러 목적으로 사용됩니다:

• 출처 인용 — 다른 기사, 책, 문서를 참조할 때
• 콜아웃 — 중요한 정보나 경고를 강조할 때
• 이메일 스타일 인용 — 응답하는 대화에서 상대방이 한 말을 표시할 때
• 풀 인용 — 자신의 글에서 핵심 구절에 주의를 끌 때

인용문에 저자를 표기할 때는 위의 Dijkstra 예시처럼 별도의 줄에 엠 대시를 붙여 표기하세요.

코드

백틱으로 인라인 코드를 표시합니다. getPublishedPosts() 같은 함수 이름, src/content/posts/ 같은 파일 경로, pnpm dev 같은 명령줄 지시, 본문 중에 나타나는 리터럴 값에 인라인 코드를 사용하세요.

구문 하이라이팅이 적용된 코드 블록:

interface Post {
  title: string;
  date: Date;
  description?: string;
  tags?: string[];
  draft?: boolean;
}

function getPublishedPosts(posts: Post[]): Post[] {
  return posts
    .filter((post) => !post.draft)
    .sort((a, b) => b.date.getTime() - a.date.getTime());
}

@theme {
  --font-sans: 'system-ui', sans-serif;
  --font-serif: 'ui-serif', 'Georgia', serif;
}

코드 블록 팁

여는 삼중 백틱 뒤에 항상 언어 식별자를 지정하세요. 구문 하이라이팅이 활성화되어 가독성이 크게 향상됩니다. 일반적인 식별자로는 typescript, javascript, css, html, bash, json, python, markdown이 있습니다.

셸 명령에는 bash 또는 sh를 사용하세요:

# 의존성 설치
pnpm install

# 개발 서버 시작
pnpm dev

# 프로덕션 빌드
pnpm build

JSON 설정 파일:

{
  "name": "my-blog",
  "version": "1.0.0",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build"
  }
}

코드 블록은 집중적으로 유지하세요. 전체 파일을 붙여넣기보다 관련 줄만 보여주세요. 컨텍스트가 필요하면 코드가 어디에 있는지 주석을 추가하세요.

표

기능	상태	비고
다크 모드	지원	라이트 / 다크 / 시스템
RSS 피드	내장	/rss.xml
사이트맵	자동 생성	@astrojs/sitemap
SEO	내장	Open Graph + 정규 URL

오른쪽 정렬 및 가운데 정렬 열:

왼쪽	가운데	오른쪽
텍스트	텍스트	텍스트
긴 텍스트	긴 텍스트	긴 텍스트

표 가이드라인

표는 명확한 열과 행이 있는 구조화된 데이터에 적합합니다. 기능 비교, 설정 옵션, API 매개변수, 참조 데이터에 이상적입니다.

표를 단순하게 유지하세요. 5~6개 이상의 열이 있는 표는 모바일 기기에서 읽기 어렵습니다. 복잡한 표는 여러 개의 작은 표로 나누거나 대신 목록 형식을 사용하세요.

열 정렬은 구분자 행의 콜론으로 제어합니다:

• :--- 왼쪽 정렬 (기본)
• :---: 가운데 정렬
• ---: 오른쪽 정렬

숫자 데이터에는 소수점이 시각적으로 정렬되도록 오른쪽 정렬을 사용하세요.

수평선

---를 사용하여 수평선을 만듭니다:

---

수평선 이후의 콘텐츠.

수평선은 글의 주요 섹션을 구분하거나, 주제 전환을 나타내거나, 매우 긴 글을 시각적으로 나누는 데 유용합니다. 적절히 사용하세요 — 빈번한 구분이 필요하다면 제목이 더 나은 구조적 선택일 수 있습니다.

이미지

이미지는 표준 Markdown 구문으로 지원됩니다:

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

이 테마는 타이포그래피 중심이지만, 필요할 때 이미지도 잘 동작합니다.

이미지 모범 사례

• 항상 대체 텍스트를 포함하세요 — 접근성에 필수적이며 이미지 로드 실패 시에도 나타납니다
• 설명적인 파일 이름을 사용하세요 — screenshot-2.png보다 dashboard-error-state.png이 좋습니다
• 파일 크기를 최적화하세요 — 저장소에 추가하기 전에 이미지를 압축하세요; 큰 이미지는 페이지 로드를 느리게 합니다
• 읽기 흐름을 고려하세요 — 이미지를 참조하는 텍스트 근처에 배치하세요, 여러 단락 떨어진 곳이 아니라

마무리

이 가이드에 설명된 Markdown 기능은 블로그 글쓰기에 필요한 대부분을 다룹니다. 좋은 Markdown의 핵심은 올바른 목적에 올바른 요소를 사용하는 것입니다: 구조를 위한 제목, 중요도를 위한 강조, 모음을 위한 목록, 기술 콘텐츠를 위한 코드 블록, 나머지를 위한 단락.

명확하게 쓰고, 일관되게 서식을 지정하고, 타이포그래피가 일하게 하세요.