마크다운 코드 블록 - 빠른 참고서 및 사용 예시

여기에서 저는 Markdown의 코드 블록 옵션에 대해 검토하고 있습니다.

Markdown 코드 블록

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

Markdown 코드 블록의 유형

주요 차이점

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

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

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

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

렌더링된 텍스트는 다음과 같이 보입니다:

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

Markdown 코드 블록 사용 시 최선의 실천 방법

• 경계 코드 블록(삼중 백틱)을 사용하여 다중 줄 코드를 표시하여 플랫폼 간의 명확성과 호환성을 보장하세요.
• 개방 백틱 뒤에 언어를 지정하여 구문 강조를 활성화하세요(예: ``````python).
• 인라인 코드를 사용하여 텍스트 내부의 짧은 스니펫이나 명령어에 사용하세요.
• 들여쓰기 코드 블록은 호환성 때문에 필요한 경우를 제외하고는 피하세요. 구문 강조를 지원하지 않으며, 가독성이 낮을 수 있습니다.
• 경계 코드 블록 앞뒤에 공백 줄을 추가하여 원본 Markdown에서 가독성을 높이세요.

특별 기능

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

요약

구문 강조를 위한 경계 코드 블록을 사용하여 최상의 가독성을 보장하세요. 인라인 코드는 짧은 스니펫에 사용하고, 호환성 때문에 필요한 경우를 제외하고는 들여쓰기 블록을 피하세요.

Diff 구문 강조

Markdown 코드 블록에서 diff 구문 강조를 효과적으로 사용하려면 다음 단계를 따르세요:

• 삼중 백틱(```)으로 시작하고 끝나는 경계 코드 블록을 사용하세요.
• 개방 백틱 뒤에 diff를 언어 식별자로 지정하세요. 이는 Git 커밋 메시지나 Pull Request에서처럼 차이를 강조하는 구문 강조를 활성화합니다.

예시:

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

• -로 시작하는 줄은 일반적으로 빨간색으로 삭제된 줄로 강조됩니다.
• +로 시작하는 줄은 일반적으로 녹색으로 추가된 줄로 강조됩니다.
• 접두사가 없는 줄은 특별히 강조되지 않습니다.

최선의 실천 방법:

• 문서, 코드 리뷰, 기술 블로그에서 코드 변경, 수정, 제안을 명확하게 전달하기 위해 이 형식을 사용하세요.
• 원본 Markdown에서 가독성을 높이기 위해 코드 블록 앞뒤에 공백 줄을 추가하세요.
• diff 강조는 줄의 시작 문자에 따라 전체 줄만 색상으로 표시하며, 줄 내부의 인라인 변경 사항은 강조하지 않습니다.

팁:
이 방법은 GitHub, GitLab 및 많은 Markdown 렌더러에서 널리 지원되며, 시각적으로 코드 변경 사항을 공유하는 데 신뢰할 수 있는 선택입니다.

지원되는 언어

Markdown 코드 블록은 구문 강조를 위해 다양한 언어를 지원하지만, 지원되는 언어의 정확한 목록은 사용하는 렌더러나 플랫폼에 따라 다릅니다. Markdown 자체는 지원되는 언어를 정의하지 않으며, 단지 언어 식별자를 렌더링 엔진에 전달하고, 해당 엔진이 적절한 구문 강조를 적용합니다. Markdown 코드 경계 자체는 공식적으로 지원되는 프로그래밍 언어의 고정된 목록을 정의하지 않습니다. 대신, 지원되는 언어 목록은 사용하는 Markdown 렌더러 또는 플랫폼(예: GitHub, GitLab, VS Code, Typora, Quarto 등)에 따라 달라집니다.

주요 플랫폼(예: 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, c++, 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!")
```

다음 언어는 대부분의 Markdown 렌더러에서 널리 지원됩니다:

참고: 실제 식별자는 js와 javascript와 같이 다를 수 있습니다. 대부분의 렌더러는 언어 이름에 대해 대소문자를 구분하지 않습니다.

지원되는 언어의 전체 목록을 찾는 방법:

• GitHub: Linguist를 사용하여 수백 가지 언어를 지원합니다.
• VS Code 및 많은 웹 렌더러: highlight.js 또는 Pygments를 사용합니다. 자세한 목록은 문서를 참조하세요.
• Bitbucket: CodeMirror 모드 및 Pygments 레็ก서를 참조합니다.

핵심 포인트:

• 대부분의 플랫폼은 주요 프로그래밍, 스크립팅 및 마크업 언어를 모두 지원합니다.
• 일부 플랫폼은 다이어그램 및 데이터 형식(예: mermaid, geojson)도 지원합니다.
• 언어 식별자는 일반적으로 대소문자를 구분하지 않지만, 호환성을 위해 소문자로 지정하는 것이 좋습니다.
• 지원되지 않는 언어 식별자를 사용하면 코드 블록이 일반 텍스트로 렌더링됩니다.

Markdown 코드 블록에서 파일명 지정

Markdown 코드 블록에서 파일명을 지정하려면 여러 가지 방법이 있지만, 사용하는 플랫폼과 렌더러에 따라 방법이 달라집니다:

1. 코드 블록 라벨 내부에 파일명 지정 (메타 구문)

일부 Markdown 엔진(예: 특정 정적 사이트 생성기, 문서 도구, 블로그 플랫폼)은 언어 뒤에 콜론으로 구분된 파일명을 추가하는 메타 구문을 지원합니다:

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

이 방법은 렌더러에 따라 코드 블록 위나 옆에 파일명(예: app.js)을 표시합니다.
그러나 이 웹사이트의 Hugo 렌더러는 이 기능을 지원하지 않습니다:

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

참고: 이 방법은 모든 플랫폼에서 지원되지 않습니다(예: GitHub 플레이버 Markdown은 현재 이 기능을 지원하지 않습니다).

2. 코드 블록 위에 파일명 헤딩 또는 인라인 코드 사용

GitHub, Stack Overflow 및 대부분의 Markdown 렌더러와의 호환성을 위해, 코드 블록 위에 헤딩 또는 굵은 인라인 코드로 파일명을 추가하세요:

**`app.js`**

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

또는:

#### `app.js`

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

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

3. 코드 내부에 파일명 주석으로 지정

대안적으로, 코드 블록 내부에 파일명을 주석으로 포함할 수 있습니다:

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

이 방법은 코드를 복사할 때 파일명이 보이는 것이 특히 유용합니다.

요약 및 최선의 실천 방법

코드 블록 위에 헤딩 또는 굵은 인라인 코드를 사용하여 최대 호환성을 보장하세요. 다양한 플랫폼에서 공유할 때는 코드 내부에 주석으로 파일명을 추가하여 명확성을 높이는 것도 고려하세요.

유용한 링크

• Markdown 간단한 가이드 - 가장 유용한 구조 및 명령어
• Hugo 간단한 가이드
• Bash 간단한 가이드 - 가장 유용한 Bash 명령어
• LaTeX 간단한 가이드
• Hugo에서 가장 인기 있는 테마
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks