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

여기에서 Markdown에서의 코드 블록 옵션에 대해 검토하고 있습니다. 프로그래밍 언어를 지정하는 방법, diff 형식화 및 코드 블록 파일 이름을 지정하는 방법을 설명합니다.

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

Markdown 코드 블록 개요

Markdown 코드 블록은 Markdown 문서 내에서 코드 또는 미리 형식화된 텍스트를 표시하며, 형식을 유지하고 선택적으로 구문 강조를 활성화할 수 있습니다. Markdown에는 두 가지 주요 유형의 코드 형식화가 있습니다: 인라인 코드 및 코드 블록입니다.

Markdown 코드 블록 유형

주요 차이점

• 인라인 코드는 단일 백틱(`)을 사용하며, 문장 내부의 짧은 코드에 적합합니다.
• 들여쓰기 코드 블록은 각 줄의 시작에 4개 공백 또는 탭을 사용합니다. 구문 강조를 지원하지 않으며 현대 Markdown에서는 드뭅니다.
• 경계 코드 블록은 삼중 백틱(```) 또는 티일드(~~~)을 코드 앞뒤에 사용합니다. 이는 특히 GitHub과 같은 플랫폼에서 선호되는 방법이며, 다음과 같은 이유로:
  • 읽기와 작성하기가 더 쉽습니다.
  • 코드 블록 시작 직후에 프로그래밍 언어를 지정하여 구문 강조를 활성화할 수 있습니다.
  • 형식을 유지하고 다중 줄 코드를 지원합니다.

구문 강조가 있는 경계 코드 블록 예시:

다음과 같은 Markdown 형식의 텍스트가 있을 때:

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

렌더링된 결과는 다음과 같습니다:

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

Markdown 코드 블록을 위한 최선의 실천 방식

• 경계 코드 블록(삼중 백틱)을 사용하여 다중 줄 코드를 표시하여 플랫폼 간의 명확성과 호환성을 보장하세요.
• 구문 강조를 위해 개방 백틱 바로 뒤에 프로그래밍 언어를 지정하세요 (예: ```python).
• 인라인 코드를 사용하여 텍스트 내부의 짧은 스니펫 또는 명령어에 사용하세요.
• 들여쓰기 블록은 호환성 때문에 필요할 때만 사용하세요. 구문 강조를 지원하지 않으며 가독성이 낮을 수 있습니다.
• 경계 코드 블록 앞뒤에 빈 줄을 추가하여 원본 Markdown에서 가독성을 높이세요.

특별 기능

• 일부 플랫폼은 diff와 같은 추가 언어 식별자를 지원하여 코드 변경을 표시할 수 있습니다. 이는 코드 리뷰에서 추가 또는 삭제된 줄을 강조합니다.
• 코드 블록 내부에 백틱을 표시하려면 더 많은 백틱으로 블록을 감싸세요 (예: 네 개의 백틱으로 세 개의 백틱을 표시).

빠른 참조 요약

구문 강조가 있는 경계 코드 블록을 사용하여 최대의 가독성과 구문 강조를 얻으세요. 인라인 코드는 짧은 스니펫에, 들여쓰기 블록은 호환성 때문에 필요한 경우에만 사용하세요.

코드 블록은 Markdown에서의 테이블와 자연스럽게 결합되어 잘 구성된 기술 문서를 작성할 수 있습니다.

Diff 구문 강조

Diff 구문 강조는 코드 변경을 명확하게 표시할 수 있게 해주며, 문서화, 코드 리뷰, 기술 블로그에 유용합니다.

• 삼중 백틱(```)을 사용하여 코드 블록을 시작하고 끝내세요.
• 개방 백틱 바로 뒤에 diff를 언어 식별자로 지정하세요.

예시:

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

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

최선의 실천 방식:

• 원본 Markdown에서 가독성을 높이기 위해 코드 블록 앞뒤에 빈 줄을 추가하세요.
• Diff 강조는 줄의 시작 문자에 따라 전체 줄만 색칠하며, 줄 내부의 인라인 변경은 강조하지 않습니다.

팁: Diff 강조는 GitHub, GitLab, 대부분의 Markdown 렌더러에서 널리 지원되며, 코드 변경을 전달하는 신뢰할 수 있는 선택입니다.

구문 강조에 지원되는 언어

지원되는 언어의 정확한 집합은 사용하는 렌더러 또는 플랫폼에 따라 달라집니다. Markdown은 언어 식별자를 렌더링 엔진에 전달하고, 적절한 구문 강조를 적용합니다. 이는 Python에서 HTML을 Markdown으로 변환할 때 중요합니다. <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에서 다이어그램 및 데이터 시각화를 위해)
• 기타: 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 모드 및 Pygments 레็ก서를 참조합니다.

Markdown 코드 블록에서 파일 이름 지정

코드 블록과 함께 파일 이름을 표시하면 독자가 스니펫이 어떤 파일에 속하는지 쉽게 식별할 수 있습니다. 지원되는 정도는 플랫폼에 따라 다릅니다.

1. 코드 블록 라벨 내의 파일 이름 (메타 구문)

일부 Markdown 엔진(특정 스태틱 사이트 생성기 및 문서화 플랫폼)은 메타 구문을 지원합니다. 이 구문에서는 언어 뒤에 콜론으로 분리된 파일 이름을 추가합니다:

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

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

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

참고: GitHub 스타일의 Markdown에서는 지원되지 않습니다.

2. 수동 파일 이름 헤딩 또는 인라인 코드

GitHub, Stack Overflow, 대부분의 Markdown 렌더러와의 전반적인 호환성을 위해, 코드 블록 위에 볼드 인라인 코드로 파일 이름을 표시하세요:

**`app.js`**

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

또는 헤딩을 사용하세요:

#### `app.js`

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

이 방법은 모든 곳에서 작동하며, 파일 이름을 코드 블록과 시각적으로 연결합니다.

3. 코드 내부의 주석으로 파일 이름 지정

코드 블록 자체 내부에 파일 이름을 주석으로 포함하세요:

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

코드를 복사할 때 파일 이름이 보여야 할 경우 특히 유용합니다.

호환성 요약

코드 블록 위에 볼드 인라인 코드를 사용하여 최대 호환성을 확보하세요. 플랫폼 간 공유 시 코드 내부의 주석을 사용하여 명확성을 높이세요.

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

코드 블록 내부에 백틱 경계를 표시하려면 — 예를 들어 Markdown 자체에 대한 문서를 작성할 때 — 더 많은 수의 백틱으로 블록을 중첩하세요:

````markdown
```python
# 이 삼중 백틱 경계는 네 백틱 경계 내부에 있습니다
print("hello")
```
````

외부 경계에 네 개의 백틱을 사용하면 삼중 백틱 예제를 내부에 표시할 수 있으며, Markdown 튜토리얼 및 체크리스트에 매우 유용합니다.

Hugo 전용: Highlight Shortcode

Hugo를 사용하는 경우, 내장 highlight shortcode는 일반 경계 블록보다 더 많은 제어 기능을 제공하며, 줄 번호 및 강조된 줄을 포함합니다:

{{< 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 체크리스트에서, Hugo 명령어 및 템플릿에 대한 보다 광범위한 참고는 Hugo 체크리스트에서 확인하세요.

유용한 링크

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