마크다운 코드 블록: 구문, 언어 및 예제를 포함한 완전 가이드

여기서는 마크다운의 코드블록 옵션을 검토해 보겠습니다. 프로그래밍 언어 지정 방법, diff 서식화 및 코드블록 파일명을 설정하는 방법을 다룹니다.

이 가이드는 2026년 문서화 도구: 마크다운, LaTeX, PDF 및 인쇄 워크플로우 허브의 일부입니다.

마크다운 코드블록 개요

마크다운 코드블록은 마크다운 문서 내에서 코드 또는 사전 서식된 텍스트를 표시하며, 서식을 유지하고 선택적으로 구문 강조를 활성화합니다. 마크다운에는 두 가지 주요 코드 서식 유형이 있습니다: 인라인 코드와 코드블록.

마크다운 코드블록의 유형

주요 차이점

• 인라인 코드는 단일 백틱( ``)을 사용하며 문장 내 짧은 코드를 위해 사용됩니다.
• 들여쓰기 코드블록은 각 줄의 시작에 공백 4칸 또는 탭을 사용합니다. 이들은 구문 강조를 지원하지 않으며 현대 마크다운에서는 드물게 사용됩니다.
• 펜스 코드블록은 코드 앞뒤에 삼중 백틱(```) 또는 틸드(~~~)를 사용합니다. 이는 특히 GitHub와 같은 플랫폼에서 선호되는 방법이며, 그 이유는 다음과 같습니다:
  • 읽고 쓰기 쉽습니다.
  • 구문 강조를 위해 여는 백틱 바로 뒤에 프로그래밍 언어를 지정할 수 있습니다.
  • 서식을 보존하고 다중 라인 코드를 지원합니다.

구문 강조가 있는 펜스 코드블록 예시:

다음과 같이 마크다운 형식화된 텍스트가 있는 경우:

```python
def hello():
    print("Hello, world!")
```

렌더링된 출력은 다음과 같습니다:

def hello():
    print("Hello, world!")

마크다운 코드블록 모범 사례

• 다중 라인 코드의 경우 명확성과 플랫폼 간 호환성을 보장하기 위해 펜스 코드블록(삼중 백틱)을 사용하십시오.
• 구문 강조를 위해 여는 백틱 뒤에 언어를 지정하십시오(예: ```python).
• 텍스트 내 짧은 스니펫 또는 명령어의 경우 인라인 코드를 사용하십시오.
• 구문 강조를 지원하지 않고 읽기 어려울 수 있으므로 레거시 호환성이 필요한 경우가 아니라면 들여쓰기 코드블록 사용을 피하십시오.
• 원시 마크다운에서 가독성을 높이기 위해 펜스 코드블록 앞뒤에 빈 줄을 배치하십시오.

특수 기능

• 일부 플랫폼은 코드 변경 사항을 보여주는 diff와 같은 추가 언어 식별자를 지원하며, 이는 코드 리뷰에서 추가되거나 제거된 라인을 강조 표시합니다.
• 코드블록 내부에 백틱을 표시하려면 더 많은 수의 백틱으로 블록을 감싸십시오(예: 내부의 삼중 백틱을 표시하기 위해 사중 백틱 사용).

빠른 참조 요약

최상의 가독성과 구문 강조를 위해 언어 식별자와 함께 펜스 코드블록을 사용하십시오. 인라인 코드는 짧은 스니펫용으로 예약하고, 호환성이 필요한 경우가 아니라면 들여쓰기 블록을 피하십시오.

코드블록은 잘 구조화된 기술 문서를 구축하기 위해 마크다운의 테이블과 자연스럽게 결합됩니다.

Diff 구문 강조

Diff 구문 강조는 코드 변경 사항을 명확하게 보여줄 수 있게 해줍니다 — 문서화, 코드 리뷰 및 기술 블로그에 유용합니다.

• 블록의 시작과 끝을 위해 삼중 백틱(```)과 함께 펜스 코드블록을 사용하십시오.
• 여는 백틱 바로 뒤에 diff를 언어 식별자로 지정하십시오.

예시:

- old line that will be removed
+ new line that will be added
  unchanged line

• -로 시작하는 라인은 삭제(보통 빨간색)로 강조 표시됩니다.
• +로 시작하는 라인은 추가(보통 초록색)로 강조 표시됩니다.
• 접두사가 없는 라인은 특별히 강조 표시되지 않습니다.

모범 사례:

• 원시 마크다운에서 더 나은 가독성을 위해 코드블록 앞뒤에 빈 줄을 배치하십시오.
• diff 강조는 선행 문자에 기반하여 전체 라인만 색칠한다는 점을 유의하십시오; 라인 내 인라인 변경 사항을 강조하지 않습니다.

팁: Diff 강조는 GitHub, GitLab 및 대부분의 마크다운 렌더러에서 널리 지원되므로 코드 변경 사항을 전달하는 데 신뢰할 수 있는 선택입니다.

구문 강조를 위한 지원 언어

지원되는 언어의 정확한 세트는 사용하는 렌더러 또는 플랫폼에 따라 다릅니다. 마크다운은 언어 식별자를 렌더링 엔진에 전달하며, 엔진은 적절한 구문 강조를 적용합니다. 이는 Python으로 HTML을 마크다운으로 변환할 때 중요하며, <code> 태그에 언어 클래스 속성(예: class="language-python")이 포함되어 있으면 펜스 블록의 이러한 식별자로 직접 매핑됩니다.

주요 플랫폼(GitHub, VS Code, Bitbucket, Docusaurus, ReadMe)에서 일반적으로 지원되는 언어:

• 웹 & 스크립팅: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• 프로그래밍: python (py), java, c, cpp (c++), csharp (c#), php, ruby, go, rust, scala, swift, kotlin, objective-c
• 데이터 & 쿼리: sql, r, matlab
• 마크업 & 설정: markdown, ini, toml, dockerfile, makefile
• 특수: diff, mermaid, geojson, topojson, stl (GitHub의 다이어그램 및 데이터 시각화를 위한 것) — 특히 mermaid 식별자는 지원되는 플랫폼에서 전체 다이어그램 렌더링을 활성화합니다; 완전한 구문 참조 및 Hugo 설정 가이드는 Mermaid 다이어그램 빠른 시작 및 치트시트를 참조하십시오.
• 기타: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme 등 다수

언어 지정 방법:

```python
def hello():
    print("Hello, world!")
```

대부분의 렌더러에서 지원하는 언어 식별자:

참고: 대부분의 렌더러는 언어 이름에 대해 대소문자를 구분하지 않습니다. 지원되지 않는 식별자를 사용하면 코드블록이 일반 텍스트로 렌더링됩니다.

지원되는 언어 전체 목록 찾기:

• GitHub: Linguist를 사용하여 수백 가지 언어를 지원합니다.
• VS Code 및 많은 웹 렌더러: highlight.js 또는 Pygments를 사용합니다 — 포괄적인 목록은 해당 문서를 참조하십시오.
• Bitbucket: CodeMirror modes 및 Pygments lexers를 참조합니다.

마크다운 코드블록에서 파일명 지정

코드블록 옆에 파일명을 표시하면 독자가 스니펫이 어느 파일에 속하는지 식별하는 데 도움이 됩니다. 지원 여부는 플랫폼에 따라 다릅니다.

1. 코드블록 레이블에서 파일명 (메타 구문)

일부 마크다운 엔진(특정 정적 사이트 생성기 및 문서화 플랫폼)은 언어 뒤에 콜론으로 구분하여 파일명을 추가하는 메타 구문을 지원합니다:

```js:app.js
console.log("Hello, world!");
```

이렇게 하면 파일명이 코드블록 위 또는 옆에 표시됩니다. 이 사이트의 Hugo 렌더러는 이를 지원하지 않습니다:

console.log("Hello, world!");

참고: 이는 GitHub flavored Markdown에서 지원되지 않습니다.

2. 수동 파일명 제목 또는 인라인 코드

범용 호환성(GitHub, Stack Overflow 및 대부분의 마크다운 렌더러 포함)을 위해 굵은 인라인 코드를 사용하여 코드블록 위에 파일명을 배치하십시오:

**`app.js`**

```js
console.log("Hello, world!");
```

또는 제목과 함께:

#### `app.js`

```js
console.log("Hello, world!");
```

이 방법은 어디서나 작동하며 시각적으로 파일명을 코드블록과 연관시킵니다.

3. 코드 내부의 주석으로 파일명

코드블록 자체 내에서 주석으로 파일명을 포함하십시오:

```js
// app.js
console.log("Hello, world!");
```

이는 코드를 복사할 때 파일명이 보이기를 원할 때 특히 유용합니다.

호환성 요약

최대한의 호환성을 위해 코드블록 위에 굵은 인라인 코드를 사용하고, 플랫폼 간 공유 시 명확성을 위해 코드 내부 주석을 고려하십시오.

코드블록 내부 백틱 이스케이프

코드블록 내부에 백틱 펜스를 표시하려면 — 예를 들어 마크다운 자체에 대한 문서를 작성할 때 — 블록을 더 많은 수의 백틱으로 중첩하십시오:

````markdown
```python
# This triple-backtick fence is inside a four-backtick fence
print("hello")
```
````

외부 펜스로 사중 백틱을 사용하면 내부에 삼중 백틱 예시를 보여줄 수 있어 마크다운 튜토리얼 및 치트시트에 유용합니다.

Hugo 전용: Highlight Shortcode

Hugo를 사용하는 경우, 내장된 highlight 쇼트코드는 일반 펜스 블록보다 더 많은 제어를 제공하며, 라인 번호 및 강조 표시된 라인을 포함합니다:

{{< highlight python "linenos=true,hl_lines=2 4" >}}
def greet(name):
    print(f"Hello, {name}!")

greet("world")
{{< /highlight >}}

옵션:

• linenos=true — 라인 번호 표시
• hl_lines=2 4 — 2번 및 4번 라인 강조
• linenostart=10 — 10에서 라인 번호 시작

이는 특정 라인에 주목을 끌고 싶은 튜토리얼 또는 문서화에 특히 유용합니다. 더 많은 서식 기능은 Markdown Cheatsheet를, Hugo 명령 및 템플릿에 대한 광범위한 참조는 Hugo Cheat Sheet을 참조하십시오.

유용한 링크

• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks