MkDocs

MkDocs는 마크다운(Markdown) 파일을 HTML로 변환하여 정적 웹사이트를 쉽게 만들 수 있게 도와주는 Python 기반의 정적 사이트 생성기이다. MkDocs의 설치와 사용법을 단계별로 설명해드리겠다.

1. MkDocs 설치

MkDocs는 Python을 기반으로 하기 때문에 Python이 먼저 설치되어 있어야 한다. 설치가 완료된 후, pip로 MkDocs를 설치할 수 있다.

설치 명령어

pip install mkdocs

설치가 완료되면 mkdocs 명령어를 사용할 수 있게 된다.

2. 새 프로젝트 생성

MkDocs 프로젝트를 새로 생성하려면 아래 명령어를 사용하여 프로젝트 폴더를 만든다.

mkdocs new my-project
cd my-project

이 명령어는 my-project라는 폴더를 생성하고, 그 안에 기본적인 MkDocs 파일 구조를 생성한다.

3. 프로젝트 폴더 구조

my-project 폴더의 기본 구조는 다음과 같다:

my-project/
    mkdocs.yml    # MkDocs 설정 파일
    docs/
        index.md  # 기본 문서 파일

mkdocs.yml: 사이트 설정을 관리하는 파일이다.
docs/: 마크다운 파일들이 저장되는 폴더이다. 여기에 여러 마크다운 파일을 추가하여 문서를 작성할 수 있다.
index.md: 사이트의 기본 페이지가 되는 마크다운 파일이다.

4. 로컬 서버 실행

MkDocs는 작성 중인 사이트를 로컬에서 미리 확인할 수 있는 서버 기능을 제공한다. 아래 명령어로 로컬 서버를 실행할 수 있다.

mkdocs serve

이 명령어를 실행한 후, 브라우저에서 http://127.0.0.1:8000/로 접속하면 문서 사이트를 실시간으로 미리보기할 수 있다.

5. 문서 작성

docs/ 폴더 안에 새로운 마크다운 파일을 만들어 추가할 수 있다. 예를 들어 introduction.md라는 파일을 만들었다고 가정해보겠다.


This is the introduction to my project.

그리고 mkdocs.yml 파일에 새로 추가한 문서를 메뉴에 추가할 수 있다.

site_name: My Project

nav:
    - Home: index.md
    - Introduction: introduction.md

이렇게 설정하면 메뉴에 "Introduction" 항목이 나타나고, 클릭하면 introduction.md 파일로 이동하게 된다.

6. 테마 설정

MkDocs는 다양한 테마를 지원하며, 이를 통해 사이트의 디자인을 쉽게 변경할 수 있다. 기본 테마는 mkdocs 테마이지만, 다른 테마를 사용할 수도 있다.

기본 테마 변경

mkdocs.yml 파일에서 테마 설정을 할 수 있다. 예를 들어, readthedocs 테마로 변경하고 싶다면 아래와 같이 설정할 수 있다.

theme:
  name: readthedocs

다양한 테마를 확인하려면 MkDocs 테마 페이지를 참조할 수 있다.

7. 정적 사이트 생성

문서를 모두 작성하고 나면, build 명령어를 사용하여 실제로 배포할 수 있는 정적 사이트를 생성할 수 있다.

mkdocs build

이 명령어를 실행하면 site/ 폴더가 생성되며, 여기에 HTML 파일들이 저장된다. 이 폴더를 웹 서버에 업로드하면 웹사이트로 배포할 수 있다.

8. GitHub Pages에 배포

MkDocs는 GitHub Pages에 쉽게 배포할 수 있는 기능을 제공한다. 아래 명령어를 사용하면 자동으로 GitHub Pages에 사이트가 배포된다.

mkdocs gh-deploy

이 명령어는 GitHub Pages에 사이트를 업로드하고, 배포가 완료되면 https://username.github.io/repository/에서 사이트를 확인할 수 있다.

9. 플러그인 및 확장 기능

MkDocs는 다양한 플러그인을 지원하며, 이들을 통해 추가적인 기능을 사용할 수 있다. 예를 들어, 검색 기능을 추가하거나 코드 하이라이트를 적용하는 등 여러 기능을 쉽게 확장할 수 있다.

폴더 구조

MkDocs에서 하위 폴더를 사용하여 문서를 구조화하고, 이를 통해 다단계 목차를 만들 수 있다. mkdocs.yml 파일에서 nav 섹션을 사용하여 원하는 대로 문서 구조를 정의할 수 있으며, 하위 폴더를 사용하여 문서의 섹션과 하위 섹션을 구성할 수 있다.

1. 하위 폴더 구조

예를 들어, 다음과 같은 디렉토리 구조를 만들었다고 가정해보겠다.

docs/
    index.md
    section1/
        intro.md
        details.md
    section2/
        overview.md
        deepdive.md

여기서 section1과 section2는 각각의 하위 폴더로, 그 안에 여러 마크다운 파일이 있다.

2. mkdocs.yml에서 목차 구성

하위 폴더를 포함한 목차를 설정하려면 mkdocs.yml 파일에서 다음과 같이 nav 섹션을 설정할 수 있다.

site_name: My Project

nav:
  - Home: index.md
  - Section 1:
      - Introduction: section1/intro.md
      - Details: section1/details.md
  - Section 2:
      - Overview: section2/overview.md
      - Deep Dive: section2/deepdive.md

이렇게 설정하면 MkDocs는 각 폴더의 파일을 계층적으로 표시한다. Section 1과 Section 2는 각 폴더에 해당하고, 그 안에 있는 문서들이 하위 항목으로 나타난다.

3. 하위 섹션 추가

필요하면 더 많은 하위 섹션을 추가할 수도 있다. 예를 들어, section1 폴더 내에 또 다른 하위 폴더를 만들고 그 폴더 내에 문서를 넣을 수 있다.

docs/
    section1/
        intro.md
        details/
            part1.md
            part2.md

그리고 mkdocs.yml 파일에서 이를 다음과 같이 구성할 수 있다.

nav:
  - Section 1:
      - Introduction: section1/intro.md
      - Details:
          - Part 1: section1/details/part1.md
          - Part 2: section1/details/part2.md

이 설정은 Section 1 아래에 Details라는 하위 섹션을 만들고, 그 아래에 다시 Part 1과 Part 2를 표시한다.

4. 결과

이런 방식으로 설정하면, MkDocs는 마크다운 파일을 계층적으로 해석하여 네비게이션 바에 표시한다. 폴더 구조와 mkdocs.yml 파일 내 nav 설정을 통해 원하는 대로 다단계 목차를 만들 수 있다.

플러그인

MkDocs에서 Mermaid 다이어그램과 LaTeX 수식을 렌더링하려면 각각 플러그인이나 확장 기능을 사용해야 한다. 여기에서는 Mermaid와 LaTeX 렌더링을 위한 설정 방법을 단계별로 설명하겠다.

1. Mermaid 다이어그램 렌더링

Mermaid는 다이어그램을 마크다운 문서 내에서 작성할 수 있게 해주는 도구이다. MkDocs에서는 Mermaid 다이어그램을 렌더링하기 위해 mkdocs-mermaid2-plugin을 사용한다.

Mermaid 설치 및 설정

플러그인 설치: mkdocs-mermaid2-plugin을 설치한다.
```
pip install mkdocs-mermaid2-plugin
```
플러그인 활성화: mkdocs.yml 파일에서 Mermaid 플러그인을 활성화한다.
```
site_name: My Project

plugins:
  - search
  - mermaid2
```

Mermaid 사용: 마크다운 파일에서 Mermaid 다이어그램을 다음과 같이 작성할 수 있다.

```mermaid
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;


이제 MkDocs 서버를 실행하거나 빌드하면 Mermaid 다이어그램이 렌더링된다.

2. LaTeX 수식 렌더링

MkDocs에서 LaTeX 수식을 렌더링하려면 mkdocs-mathjax-plugin 플러그인을 사용할 수 있다. MathJax는 LaTeX 문법을 HTML로 변환해주는 JavaScript 라이브러리이다.

LaTeX 설치 및 설정

MathJax 플러그인 설치:
```
pip install mkdocs-mathjax-plugin
```
플러그인 활성화: mkdocs.yml 파일에서 MathJax 플러그인을 활성화한다.
```
site_name: My Project

plugins:
  - search
  - mathjax
```
LaTeX 수식 사용: 마크다운 파일에서 LaTeX 수식을 사용할 수 있다.
- 인라인 수식: $...$
- 블록 수식: $$...$$
예시:
```
인라인 수식: $E = mc^2$

블록 수식:

$$
E = mc^2
$$
```
MathJax 구성 (선택 사항): 기본 MathJax 설정 외에 추가로 설정을 하고 싶다면, mkdocs.yml에서 config 섹션을 사용하여 설정할 수 있다.
```
plugins:
  - mathjax:
      config:
        tex2jax:
          inlineMath: [['$', '$'], ['\$ ', '\ $']]
```

3. MkDocs 로컬 서버 실행

Mermaid와 LaTeX 플러그인을 설정한 후, 로컬 서버에서 결과를 확인하려면 다음 명령어를 사용한다.

mkdocs serve

브라우저에서 http://127.0.0.1:8000/로 접속하면 Mermaid 다이어그램과 LaTeX 수식이 제대로 렌더링되는지 확인할 수 있다.

테마 구성

MkDocs에서는 다양한 테마를 지원하며, 이를 통해 사이트의 디자인을 쉽게 변경할 수 있다. 기본적으로 제공되는 테마 외에도 추가적인 서드파티 테마를 사용할 수 있다. 여기서는 MkDocs에서 테마를 변경하는 방법과 커스터마이징하는 방법을 설명하겠다.

1. 기본 테마 변경

MkDocs에서 기본적으로 제공되는 테마 중 하나로 변경하려면 mkdocs.yml 파일에서 theme 항목을 설정하면 된다. 기본 제공 테마로는 mkdocs, readthedocs 등이 있다.

테마 변경 예시

site_name: My Project

theme:
  name: readthedocs

이렇게 설정하면 readthedocs 테마로 사이트의 디자인이 변경된다.

2. 서드파티 테마 설치 및 사용

MkDocs는 다양한 서드파티 테마를 지원한다. 이러한 테마를 사용하려면 먼저 설치한 후, mkdocs.yml 파일에서 해당 테마를 설정할 수 있다.

서드파티 테마 예시: Material for MkDocs

Material for MkDocs 설치
Material 테마는 MkDocs에서 가장 인기 있는 서드파티 테마 중 하나이다. 설치하려면 다음 명령어를 사용하라.
```
pip install mkdocs-material
```
테마 활성화
설치가 완료되면 mkdocs.yml 파일에서 Material 테마를 설정할 수 있다.
```
site_name: My Project

theme:
  name: material
```
테마 커스터마이징
Material 테마는 매우 다양한 옵션을 제공한다. 예를 들어, 색상이나 글꼴을 변경하려면 다음과 같이 설정할 수 있다.
```
theme:
  name: material
  palette:
    primary: 'indigo'
    accent: 'pink'
  font:
    text: 'Roboto'
    code: 'Roboto Mono'
```

3. 커스텀 CSS 사용

만약 기본 제공 테마나 서드파티 테마를 사용하면서도 추가적으로 디자인을 수정하고 싶다면, extra_css 항목을 사용하여 커스텀 CSS 파일을 추가할 수 있다.

CSS 파일 추가
먼저 docs/ 폴더 안에 custom.css 파일을 생성한 후, 원하는 CSS 스타일을 정의한다.
```
/* custom.css */
body {
    background-color: #f0f0f0;
}
```
mkdocs.yml 파일에 CSS 파일 추가
다음으로, mkdocs.yml 파일에 CSS 파일을 등록한다.
```
extra_css:
  - css/custom.css
```

이렇게 하면 custom.css에서 정의한 스타일이 사이트에 반영된다.

4. 커스텀 템플릿 사용

만약 더 큰 수준의 커스터마이징이 필요하다면, MkDocs에서 HTML 템플릿을 직접 수정할 수도 있다. mkdocs.yml 파일에서 extra_templates를 사용하여 HTML 템플릿 파일을 지정할 수 있다.

theme:
  name: material
  custom_dir: custom_theme

이렇게 하면 custom_theme 폴더에서 테마 템플릿을 수정하여 원하는 대로 커스터마이징할 수 있다.

기본 테마 변경: mkdocs.yml에서 theme: name을 설정하여 기본 제공 테마를 변경할 수 있다.
서드파티 테마 설치: pip install 명령어로 서드파티 테마를 설치하고 mkdocs.yml에서 활성화한다.
커스텀 CSS 사용: extra_css 항목을 사용하여 추가적인 스타일을 적용할 수 있다.
커스텀 템플릿 사용: HTML 템플릿을 직접 수정하여 사이트 디자인을 더 깊이 커스터마이징할 수 있다.

Nextdocs

Last updated 1 year ago

hashtag1. MkDocs 설치

hashtag2. 새 프로젝트 생성

hashtag3. 프로젝트 폴더 구조

hashtag4. 로컬 서버 실행

hashtag5. 문서 작성

hashtag6. 테마 설정

hashtag7. 정적 사이트 생성

hashtag8. GitHub Pages에 배포

hashtag9. 플러그인 및 확장 기능

hashtag폴더 구조

hashtag1. 하위 폴더 구조

hashtag2. mkdocs.yml에서 목차 구성

hashtag3. 하위 섹션 추가

hashtag4. 결과

hashtag플러그인

hashtag1. Mermaid 다이어그램 렌더링

hashtag2. LaTeX 수식 렌더링

hashtag3. MkDocs 로컬 서버 실행

hashtag테마 구성

hashtag1. 기본 테마 변경

hashtag2. 서드파티 테마 설치 및 사용

hashtag3. 커스텀 CSS 사용

hashtag4. 커스텀 템플릿 사용