마크다운 (Markdown)

서론

이 장에서는 수많은 코딩 관련 애플리케이션과 재현 가능한 분석에서 매우 인기 있는 가벼운 마크업 언어인 마크다운(Markdown)을 만나보겠습니다. 마크다운의 다양한 용도 중 한 가지 예로, 이 장 자체가 마크다운으로 작성되었습니다!

사전 준비

어떤 일반 텍스트 에디터로도 마크다운을 작성할 수 있지만, 이 책은 마크다운 에디터로 Visual Studio Code를 추천합니다. VS Code는 열려 있는 마크다운 파일을 렌더링하여 최종 출력 결과물이 어떻게 보일지 보여줄 수 있습니다. 이를 위해 Markdown All in One 및 Markdown Preview Enhanced 익스텐션을 설치해야 하며, 마크다운 파일(확장자 .md) 내에서 우클릭한 후 Markdown Preview Enhanced: Open Preview to the Side를 선택하면 됩니다.

Visual Studio Code를 사용하지 않는다면, JupyterLab의 텍스트 셀이나 Google Colab 노트북의 텍스트 셀에서 마크다운을 실험해 볼 수 있으며, 온라인 라이브 코딩 마크다운 환경인 Dillinger를 이용할 수도 있습니다.

마크다운 소개

마크다운은 마이크로소프트 워드와 같은 위지윅(What-You-See-Is-What-You-Get) 문서 작성 소프트웨어와 다릅니다. 입력(일종의 일반 텍스트)이 렌더링 된 출력과 다르게 보이기 때문입니다. 워드에서는 버튼을 클릭하여 서식을 적용합니다. 반면 마크다운을 작성할 때는 문서의 서식 요소를 코드와 유사한 지침으로 지정합니다. 원시 HTML과 렌더링 된 HTML이 어떻게 보이는지 안다면 비슷한 아이디어라고 생각하면 됩니다(HTML 자체가 마크업 언어입니다). 다만 순수 마크다운은 워드 문서에 코드를 적어둘 수 있는 것처럼 코드 스니펫을 포함할 수는 있지만 파이썬 코드를 실행할 수는 없다는 점에 유의하세요.

마크다운은 작성할 때도 최대한 읽기 쉽도록 만들어졌습니다. 또한 명령어가 몇 개 되지 않아 매우 단순합니다. 사용자가 서식보다는 텍스트 작성에 집중해야 한다는 것이 핵심 아이디어입니다.

마크다운만 포함된 파일의 표준 확장자는 .md이지만, 실행 가능한 코드 청크를 포함한 마크다운의 문맥에서는 .qmd를 볼 수도 있습니다. 또한 주피터 노트북의 셀(파일 확장자 .ipynb)에서도 마크다운을 찾을 수 있습니다.

마크다운이 소통에 사용되는 상황은 매우 많습니다:

  • 코더와 데이터 과학자들은 패키지 문서화와 같은 문서를 작성할 때 자주 마크다운을 사용합니다.
  • 웹사이트, 리포트, 슬라이드, 연구 논문을 만들기 위해 사용됩니다.
  • 주피터 노트북의 텍스트 셀에서 사용됩니다.
  • pandoc이나 Quarto와 같은 도구들이 다른 문서 유형으로 변환할 수 있는 기본 포맷으로 사용됩니다.
  • 데이터 과학에 관한 책을 쓰기 위해 사용됩니다!

마크다운의 장점 중 일부는 다음과 같습니다:

  • 마크다운 파일은 어떤 일반 텍스트 에디터로도 열 수 있습니다.
  • 마크다운은 운영 체제에 독립적입니다.
  • 마크다운은 렌더링 되지 않은 상태에서도 가독성이 매우 높습니다.
  • 깃허브(Github-flavored markdown이라고 함)와 레딧(Reddit)을 포함한 많은 웹사이트가 마크다운 구문을 지원합니다.

이 장의 나머지 부분에서는 대부분의 마크다운 구문을 다룹니다.

마크다운 구문 (The Markdown Syntax)

제목 (Headings)

마크다운의 기초를 살펴보겠습니다. 예를 들어, 해시 기호 하나(#)는 다음과 같이 문서의 제목을 나타냅니다:

# 제목

다음 단계의 부제목은 다음과 같이 두 개의 해시 기호로 지정할 수 있습니다:

## 부제목

해시 기호가 늘어날수록 제목의 크기는 점차 작아집니다. 예를 들어:


### 문 (Phylum)

#### 강 (Class)

##### 목 (Order)

###### 과 (Family)

의 결과물은 다음과 같습니다:

문 (Phylum)

강 (Class)

목 (Order)
과 (Family)

Visual Studio Code를 사용 중이고 탐색기 패널에 있다면, ‘outline’ 드롭다운 메뉴 아래에서 마크다운 문서의 개요(제목과 부제목 구조)를 볼 수 있습니다.

인라인 구문 (In-Line Syntax)

자주 사용하게 될 다른 일반적인 구문 기능들은 다음과 같습니다:

  • 기울임꼴(italic) 텍스트를 만들려면, *텍스트 양쪽에 별표 하나*를 씁니다.
  • 굵은(bold) 텍스트는 **별표 두 개**로 만듭니다.
  • 굵은 기울임꼴은 ***별표 세 개***입니다.
  • 링크는 텍스트를 대괄호로, 하이퍼링크를 소괄호로 묶어 만듭니다. 예: [텍스트](링크)
  • 인라인 코드는 백틱을 사용하여 `코드`와 같이 표시합니다.
  • ~~취소선~~은 취소선과 같이 보입니다.
  • ^(윗첨자)는 ^(윗첨자)를 만듭니다.
  • 수학 공식은 달러 기호로 감싸서 인라인으로 지원됩니다. 예: ${\displaystyle ds^{2}=\left(1-{\frac {r_{\mathrm {s} }}{r}}\right)^{-1}\,dr^{2}+r^{2}\,d\varphi ^{2}}$는 \({\displaystyle ds^{2}=\left(1-{\frac {r_{\mathrm {s} }}{r}}\right)^{-1}\,dr^{2}+r^{2}\,d\varphi ^{2}}\)와 같이 렌더링 됩니다.
  • 유니코드가 지원되므로 ∰와 같은 기호를 쓸 수 있으며, 이모지도 지원됩니다. :tada:와 같은 구문은 :tada:를 만듭니다.

텍스트 블록 구문 (Text Block Syntax)

인용구는 매 줄마다 꺽쇠 기호 >를 추가하여 만들 수 있습니다:

여기에 인용구가 들어갑니다!

순서 없는 목록은 각 줄에 - 또는 *를 사용하여 만들 수 있습니다. 즉,

- 첫 번째 항목
- 두 번째 항목
- 세 번째 항목

은 다음과 같이 됩니다:

  • 첫 번째 항목
  • 두 번째 항목
  • 세 번째 항목

순서 있는 목록은 단순히 각 줄에 연속된 숫자를 써서 만들 수 있습니다:

1. 첫 번째 항목
2. 두 번째 항목
3. 세 번째 항목

결과는 다음과 같습니다:

  1. 첫 번째 항목
  2. 두 번째 항목
  3. 세 번째 항목

두 유형의 목록 모두 하위 항목을 가질 수 있습니다:

- 첫 번째 항목
  - 하위 항목
    - 하위의 하위 항목
- 두 번째 항목

결과는 다음과 같습니다:

  • 첫 번째 항목
    • 하위 항목
      • 하위의 하위 항목
  • 두 번째 항목

표를 만드는 기본 구문은 다음과 같습니다:

| 치즈 | 국가 | kg당 가격 |
|---------------------|-----------------|-------------|
| Appleby's Cheshire  | 영국 | £30 |
| Edam | 네덜란드 | £8 |
| Pélardon | 프랑스 | £37 |

결과는 다음과 같습니다:

치즈 국가 kg당 가격
Appleby’s Cheshire 영국 £30
Edam 네덜란드 £8
Pélardon 프랑스 £37

하지만 표를 직접 작성하고 싶지는 않을 것입니다! 실무에서는 pandas 데이터 프레임에서 df.to_markdown()을 사용하여 마크다운 파일로 내보내거나, 유용한 웹사이트인 markdown table generator를 사용하는 것이 가장 쉽습니다.

인라인 코드는 백틱으로 렌더링 되었지만, 코드 블록은 세 개의 백틱과 언어 이름을 사용하여 다음과 같이 렌더링 할 수 있습니다:

코드 보기 
import pandas as pd
df = pd.DataFrame([[1, 2, 3], [4, 5, 6], [7, 8, 9]],
                  columns=['a', 'b', 'c'])

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

코드 보기 
import pandas as pd
df = pd.DataFrame([[1, 2, 3], [4, 5, 6], [7, 8, 9]],
                  columns=['a', 'b', 'c'])

데이터 타입과 예약어들에 구문 강조(syntax highlighting)가 적용된 것을 확인하세요. 구문 강조는 광범위한 언어를 지원합니다. 또한 이 구문은 자동화된 리포트 출판을 위해 마크다운을 사용할 때 Quarto에 의해 실행될 코드 블록에 사용되는 구문과 매우 유사합니다(이에 대해서는 아래에서 자세히 다룹니다).

수학 공식 표시는 다음과 같이 두 개의 달러 기호로 렌더링 됩니다:

$$
{\displaystyle ds^{2}=\left(1-{\frac {r_{\mathrm {s} }}{r}}\right)^{-1}\,dr^{2}+r^{2}\,d\varphi ^{2}}
$$

결과는 다음과 같습니다:

\[ {\displaystyle ds^{2}=\left(1-{\frac {r_{\mathrm {s} }}{r}}\right)^{-1}\,dr^{2}+r^{2}\,d\varphi ^{2}\,,} \]

이미지를 삽입하려면 ![대체-텍스트](url 또는 파일경로) 구조를 사용합니다. 예를 들어

![Python4DS 로고](https://github.com/aeturrell/python4DS/blob/main/logo.png?raw=true)

는 다음 결과를 냅니다:

Python4DS 로고

작업 목록(task lists)을 만들 수도 있습니다. 예를 들어:

- [x] 1장 완료
- [ ] 2장 편집
- [ ] 책 출간 :rocket:

의 결과는 다음과 같습니다:

각주(Footnotes)는 [^1], [^2]와 같이 번호를 붙이거나 [^note]와 같이 내용과 관련된 이름을 붙여 만들 수 있습니다. 여기 세 가지 사용 예시가 있습니다: 첫 번째 예시1, 그리고 또 다른 예시2, 세 번째는 여기에 있으며 이름으로 된 레이블을 가지고 있습니다3 (렌더링 시에는 텍스트가 아닌 번호로 보입니다). 각주와 연관된 정보를 보려면 페이지 맨 아래로 스크롤해야 하지만, 정보를 채워 넣는 구문은 다음과 같습니다:

[^1]: 첫 번째 각주.
[^2]: 각주의 모든 새 줄은 앞에 공백 2개가 있어야 합니다.  
  이를 통해 여러 줄로 된 각주를 가질 수 있습니다.
[^note]: 이름이 지정된 각주도 텍스트가 아닌 번호로 렌더링 되지만, 식별과 연결을 더 쉽게 해줍니다.

마지막으로 가로 구분선을 삽입하려면 다음을 사용하세요:

***

다음과 같은 구분선이 생깁니다:

다른 마크다운 리소스

훌륭한 마크다운 리소스들이 시중에 많이 있습니다:

  1. 첫 번째 각주.↩︎

  2. 각주의 모든 새 줄은 앞에 공백 2개가 있어야 합니다.
    이를 통해 여러 줄로 된 각주를 가질 수 있습니다.↩︎

  3. 이름이 지정된 각주도 텍스트가 아닌 번호로 렌더링 되지만, 식별과 연결을 더 쉽게 해줍니다.↩︎