Docusaurus

개요

Docusaurus는 인기 있는 마크다운 문서화 시스템입니다. Docusaurus 웹사이트의 페이지는 보통 순수 마크다운으로 작성되므로, 계산 결과를 자동으로 재현 가능하게 포함하는 간단한 방법이 없습니다.

Quarto docusaurus-md 형식을 사용하면 계산 결과(예: 플롯을 생성하는 R/Python 코드)를 Docusaurus 웹사이트에 포함할 수 있습니다. 이 문서에서 그 방법을 설명합니다.

Docusaurus와 함께 Quarto를 사용할 때는 테마, 페이지 레이아웃, 내비게이션과 관련된 많은 Quarto 기능이 적용되지 않는다는 점을 기억하세요. Docusaurus에는 자체 테마 시스템, 구문 강조, 목차, 페이지 레이아웃, 내비게이션 메뉴, 전체 텍스트 검색이 있습니다. Quarto의 자체 프레임워크가 아니라 Docusaurus의 HTML 배포 프레임워크 내에서 렌더링되는 마크다운을 생성하기 위해 Quarto를 사용하게 됩니다.

워크플로

Docusaurus와 함께 Quarto를 사용하는 기본 개념은 계산 마크다운 문서(.qmd)나 Jupyter 노트북(.ipynb)을 사용해 Docusaurus가 HTML로 렌더링하는 일반 마크다운 파일(.md)을 생성하는 것입니다.

index.qmd   quarto =>   index.md   docusaurus =>   index.html

quarto render와 quarto preview 명령은 .qmd 또는 .ipynb 파일을 Docusaurus 호환 마크다운(.md)으로 변환하는 데 사용됩니다. 계산 파일은 일반 마크다운 파일을 두는 위치(예: blog 디렉터리)에 함께 위치합니다.

렌더링 후에는 계산 문서 옆에 일반 .md 파일이 생성됩니다. 이 마크다운 파일은 Docusaurus에서 처리됩니다.

실시간 미리보기

quarto preview 명령은 Docusaurus 웹사이트가 있는 디렉터리에서 실행될 때 이를 자동으로 인식합니다:

Terminal
cd my-docusaurus-website
quarto preview

이는 로컬 미리보기 서버를 띄우기 위해 docusaurus start를 자동으로 실행합니다. 또한 파일 시스템에서 .qmd 및 .ipynb 입력 변경을 감시하고 변경 시 Docusaurus 호환 .md 파일로 자동 렌더링합니다.

이 기능은 VS Code 또는 Positron의 Quarto VS Code 확장에 포함된 통합 Preview 명령에서도 동작합니다.

렌더링

미리보기를 사용하지 않고 사이트의 모든 Quarto 문서(.qmd)와 노트북(.ipynb)을 렌더링하려면 사이트 루트 디렉터리에서 quarto render를 실행하세요:

Terminal
cd my-docusaurus-website
quarto render

보통 배포용 사이트를 빌드하기 전에 사이트 수준에서 quarto render를 실행하는 것이 좋습니다:

Terminal
quarto render && npm run build

개별 문서나 노트북만 렌더링할 수도 있습니다:

Terminal
quarto render blog/2022-07-26/hello-quarto/index.qmd

계산 비용이 큰 문서가 있다면 문서 소스 코드가 변경될 때만 코드가 재실행되도록 Quarto의 freeze 기능을 사용하는 것을 고려하세요.

프로젝트 수준에서 렌더링하지 않고 Quarto로 개별 파일만 렌더링하려면 다음과 같이 docusaurus-md 형식을 지정해야 합니다:

---
title: "My Blog Post"
format: docusaurus-md
---

구성

Quarto는 _quarto.yml 프로젝트 설정 파일이 없는 Docusaurus 사이트에서도 잘 동작하지만, 기본 동작을 사용자 지정하거나 참고문헌을 추가하려면 _quarto.yml 파일을 추가할 수 있습니다. 예를 들어 간단히 사용자 지정한 _quarto.yml 파일은 다음과 같습니다:

_quarto.yml
project:
  type: docusaurus
      
format: 
  docusaurus-md:
    code-fold: true
  
execute: 
  warning: false

bibliography: references.bib

명시적 _quarto.yml 파일을 제공하는 경우, 위와 같이 프로젝트 유형(type: docusaurus)을 반드시 명시해야 합니다.

외부 디렉터리

Quarto 문서/노트북을 Docusaurus 웹사이트와 분리된 별도 디렉터리에 두고 싶을 수도 있습니다. 이 구성에서는 Quarto 디렉터리에 사이트의 디렉터리 구조를 그대로 반영한 뒤, 프로젝트 파일의 output-dir을 Docusaurus 디렉터리를 가리키도록 설정합니다. 예:

_quarto.yml
project:
  type: docusaurus
  output-dir: ../docusaurus-site

코드 블록

Docusaurus의 코드 블록은 Quarto와 매우 비슷합니다. 중요한 점은 구문 강조 테마가 Quarto가 아니라 Docusaurus에서 온다는 것입니다. 자세한 내용은 theming 문서를 참고하세요.

Quarto에서 filename 속성을 사용하면 Docusaurus에서 코드 블록 title로 자동 변환됩니다:

```{.python filename="hello.py"}
1 + 1
```

코드 접기도 자동으로 적용됩니다. 예를 들어 다음 실행 코드 블록은:

```{python}
#| code-fold: true
1 + 1
```

Docusaurus에서 접을 수 있는 블록으로 렌더링됩니다:

Callouts 및 Tabsets

Quarto와 마찬가지로 Docusaurus는 Callouts와 Tabsets를 지원합니다. 문서에 이 구성 요소를 포함할 때 Quarto 표준 마크다운 문법을 사용하면 적절한 Docusaurus 구성으로 자동 변환됩니다.

예를 들어 Quarto callout은 다음과 같습니다:

::: {.callout-important}
여기서는 Quarto callout 문법을 사용합니다.
:::

Docusaurus에서는 다음과 같이 렌더링됩니다:

Quarto tabset 예시는 다음과 같습니다:

::: {.panel-tabset group="fruits"}

## 사과
이것은 사과입니다 🍎

## 오렌지
이것은 오렌지입니다 🍊

## 바나나
이것은 바나나입니다 🍌

:::

Docusaurus에서는 다음과 같이 렌더링됩니다:

HTML 및 MDX

Docusaurus 웹사이트는 Pandoc(Quarto의 기본 마크다운 렌더러)과 큰 차이가 있는 마크다운 변종인 MDX를 사용합니다. 가장 큰 차이점은 Quarto가 HTML 삽입을 허용하는 반면 MDX는 허용하지 않는다는 것입니다. 대신 MDX는 JavaScript 코드와 React JSX 컴포넌트를 직접 삽입할 수 있습니다(HTML처럼 보이지만 동작에 중요한 차이가 있습니다).

Quarto의 Docusaurus 지원은 이러한 차이를 고려하여 필요할 때 raw HTML을 삽입하고 MDX 컴포넌트와 JavaScript를 사용할 수 있게 합니다.

HTML 블록

Docusaurus 웹사이트는 임의의 HTML 콘텐츠를 허용하지 않습니다. 대신 JSX를 사용해 HTML 태그를 출력합니다. JSX 태그는 대부분의 경우 HTML 태그처럼 보이고 동작하지만, 중요한 주의점이 있습니다. 특히 class 속성은 className으로 작성해야 하며, style 속성은 CSS 문자열이 아니라 JavaScript 객체로 지정해야 합니다.

JSX에 맞지 않는 raw HTML을 포함해야 한다면 raw ```{=html} 코드 블록을 사용하세요. 예:

```{=html}
<p style="color: green;">Paragraph</p>
```

HTML 코드(예: 배지, 비디오, 트윗)를 삽입해야 한다면 JSX가 파싱할 수 없는 태그를 만나 오류가 발생하지 않도록 위와 같은 raw HTML 블록을 사용하는 것이 확실합니다.

계산 결과로 생성된 HTML(예: 노트북에 표시된 Pandas 데이터프레임)은 class 및/또는 style 태그를 포함한 raw HTML을 사용하는 경우가 많습니다. 이러한 계산 출력은 Docusaurus에서 올바르게 렌더링되도록 raw ```{=html} 코드 블록에 자동으로 포함됩니다.

MDX 블록

Docusaurus를 대상으로 하는 Quarto 문서에서도 MDX 컴포넌트와 JavaScript를 사용할 수 있습니다. 이를 위해 ```{=mdx} raw 코드 블록으로 감싸세요. 예:

```{=mdx}
export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '2px',
      color: '#fff',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);

<Highlight color="#25c2a0">Docusaurus GREEN</Highlight> and <Highlight color="#1877F2">Rams blue</Highlight> are my favorite colors.

I can write **Markdown** alongside my _JSX_!
```

이는 다음과 같이 렌더링됩니다:

일반 마크다운 콘텐츠도 JavaScript와 React 컴포넌트와 함께 mdx 블록에 포함할 수 있습니다.

LaTeX 수식

기본적으로 Quarto는 Docusaurus 프로젝트에서 WebTeX를 사용해 LaTeX 수식을 렌더링합니다. WebTeX는 TeX 표현식을 입력으로 받아 웹 배포를 위한 PNG 이미지를 생성하는 서비스입니다.

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

$x + 1$

다음으로 변환됩니다:

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

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

다크 모드

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

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

KaTeX

수식 렌더링에 KaTeX를 사용하도록 Docusaurus를 구성할 수도 있습니다. 이 옵션에 대한 자세한 내용은 KaTeX 사용 문서를 참고하세요.

사이트에서 KaTeX가 수식을 올바르게 렌더링하는 것을 확인한 후, _quarto.yml 파일에서 수식 렌더링에 webtex 대신 katex를 사용하도록 지정해야 합니다:

_quarto.yml
format:
  docusaurus-md:
    html-math-method: katex