GitHub (GFM)

개요

마크다운은 Quarto의 입력 형식이지만, 경우에 따라 출력 형식이 될 수도 있습니다(예: 마크다운을 입력으로 받는 웹사이트나 CMS가 있고 Python이나 R의 계산 결과를 포함하고 싶을 때).

이 문서는 Quarto로 GitHub Flavored Markdown (GFM)을 생성하는 방법을 다룹니다. 다음과 같은 이유로 필요할 수 있습니다:

  • Jupyter 노트북에서 GitHub README.md 생성

  • 계산 결과(예: 플롯 출력)를 포함하는 GitHub 위키 페이지 생성.

GFM 형식

Quarto에서 GitHub Flavored Markdown을 만들려면 gfm 형식을 사용하세요. 예:

---
title: "My Project"
format: gfm
---

GFM 출력에 사용할 수 있는 전체 옵션 목록은 GFM 형식 참조를 참고하세요.

Quarto로 README.md를 만들려면 파일 이름 줄기가 README인 노트북(.ipynb) 또는 계산 마크다운 파일(.qmd)로 시작하세요. 예:

README.qmd
---
title: "My Project"
format: gfm
jupyter: python3
---

이것은 Python에서 동적으로 생성된 콘텐츠가 포함된 GitHub README입니다:
    
```{python}
1 + 1
```

다음으로 README를 렌더링합니다:

Terminal
quarto render README.qmd

그러면 입력 파일과 함께 README.md가 생성됩니다.

미리보기 모드

GitHub Flavored Markdown 문서를 quarto preview하면 기본적으로 GitHub에서 렌더링된 마크다운과 유사한 HTML 미리보기가 표시됩니다. 생성된 원본 마크다운을 보고 싶다면 preview-mode: raw 옵션을 사용하세요. 예:

---
title: "My Project"
format: 
  gfm:
    preview-mode: raw
---

WebTeX 수식

gfm 형식은 표준 달러 구분 인라인($...$)과 디스플레이($$...$$) 문법으로 LaTeX 수식을 렌더링합니다. 그러나 배포 대상 웹 환경에서 달러 구분 수식을 지원하지 않는다면 WebTeX를 사용해 수식을 표시할 수 있습니다. 이는 Pandoc의 html-math-method를 webtex로 설정하면 됩니다. 예:

format:
  gfm:
    html-math-method: webtex

WebTeX는 이미지를 표시할 수 있는 모든 웹 페이지에서 동작하며, 특별한 JavaScript나 CSS가 필요하지 않습니다. 문서에 포함된 모든 인라인 또는 디스플레이 수식은 렌더링된 수식을 요청하는 이미지 URL로 변환됩니다. 예를 들어 다음 마크다운은:

$x + 1$

다음으로 변환됩니다:

![](https://latex.codecogs.com/svg.latex?x%20%2B%201)

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

다크 모드

SVG는 전체적인 외관이 가장 좋기 때문에 기본 렌더링 방식으로 사용됩니다. 하지만 gfm 문서를 어두운 배경에 렌더링한다면, 어두운 배경을 지정한 PNG로 전환하는 것이 좋습니다. 다음과 같이 설정할 수 있습니다:

format:
   gfm:
     html-math-method: 
       method: webtex
       url: https://latex.codecogs.com/png.image?%5Cbg_black&space;

GitHub 위키

Quarto를 사용해 GitHub 위키에 계산 결과를 포함하려면 먼저 로컬 편집을 위해 위키를 클론하세요.

그 다음 위키의 각 페이지마다 계산 마크다운 파일(.ipynb, .qmd)을 만들면 됩니다. Quarto 프로젝트를 사용하면 이 파일들을 한 번에 해당 .md 파일로 렌더링할 수 있습니다. 예:

Terminal
quarto render

프로젝트 파일이 없어도 quarto render는 기본적으로 디렉터리의 모든 입력 파일을 렌더링하므로 꼭 Quarto 프로젝트 파일이 필요한 것은 아닙니다.