# MkDocs
MkDocs는 마크다운(Markdown) 파일을 HTML로 변환하여 정적 웹사이트를 쉽게 만들 수 있게 도와주는 Python 기반의 정적 사이트 생성기이다. MkDocs의 설치와 사용법을 단계별로 설명해드리겠다.
#### 1. **MkDocs 설치**
MkDocs는 Python을 기반으로 하기 때문에 Python이 먼저 설치되어 있어야 한다. 설치가 완료된 후, pip로 MkDocs를 설치할 수 있다.
**설치 명령어**
```bash
pip install mkdocs
```
설치가 완료되면 `mkdocs` 명령어를 사용할 수 있게 된다.
#### 2. **새 프로젝트 생성**
MkDocs 프로젝트를 새로 생성하려면 아래 명령어를 사용하여 프로젝트 폴더를 만든다.
```bash
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는 작성 중인 사이트를 로컬에서 미리 확인할 수 있는 서버 기능을 제공한다. 아래 명령어로 로컬 서버를 실행할 수 있다.
```bash
mkdocs serve
```
이 명령어를 실행한 후, 브라우저에서 `http://127.0.0.1:8000/`로 접속하면 문서 사이트를 실시간으로 미리보기할 수 있다.
#### 5. **문서 작성**
`docs/` 폴더 안에 새로운 마크다운 파일을 만들어 추가할 수 있다. 예를 들어 `introduction.md`라는 파일을 만들었다고 가정해보겠다.
```markdown
This is the introduction to my project.
```
그리고 `mkdocs.yml` 파일에 새로 추가한 문서를 메뉴에 추가할 수 있다.
```yaml
site_name: My Project
nav:
- Home: index.md
- Introduction: introduction.md
```
이렇게 설정하면 메뉴에 "Introduction" 항목이 나타나고, 클릭하면 `introduction.md` 파일로 이동하게 된다.
#### 6. **테마 설정**
MkDocs는 다양한 테마를 지원하며, 이를 통해 사이트의 디자인을 쉽게 변경할 수 있다. 기본 테마는 `mkdocs` 테마이지만, 다른 테마를 사용할 수도 있다.
**기본 테마 변경**
`mkdocs.yml` 파일에서 테마 설정을 할 수 있다. 예를 들어, `readthedocs` 테마로 변경하고 싶다면 아래와 같이 설정할 수 있다.
```yaml
theme:
name: readthedocs
```
다양한 테마를 확인하려면 [MkDocs 테마 페이지](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)를 참조할 수 있다.
#### 7. **정적 사이트 생성**
문서를 모두 작성하고 나면, `build` 명령어를 사용하여 실제로 배포할 수 있는 정적 사이트를 생성할 수 있다.
```bash
mkdocs build
```
이 명령어를 실행하면 `site/` 폴더가 생성되며, 여기에 HTML 파일들이 저장된다. 이 폴더를 웹 서버에 업로드하면 웹사이트로 배포할 수 있다.
#### 8. **GitHub Pages에 배포**
MkDocs는 GitHub Pages에 쉽게 배포할 수 있는 기능을 제공한다. 아래 명령어를 사용하면 자동으로 GitHub Pages에 사이트가 배포된다.
```bash
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` 섹션을 설정할 수 있다.
```yaml
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` 파일에서 이를 다음과 같이 구성할 수 있다.
```yaml
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 설치 및 설정**
1. **플러그인 설치**: `mkdocs-mermaid2-plugin`을 설치한다.
```bash
pip install mkdocs-mermaid2-plugin
```
2. **플러그인 활성화**: `mkdocs.yml` 파일에서 Mermaid 플러그인을 활성화한다.
```yaml
site_name: My Project
plugins:
- search
- mermaid2
```
3. **Mermaid 사용**: 마크다운 파일에서 Mermaid 다이어그램을 다음과 같이 작성할 수 있다.
````markdown
```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 설치 및 설정**
1. **MathJax 플러그인 설치**:
```bash
pip install mkdocs-mathjax-plugin
```
2. **플러그인 활성화**: `mkdocs.yml` 파일에서 MathJax 플러그인을 활성화한다.
```yaml
site_name: My Project
plugins:
- search
- mathjax
```
3. **LaTeX 수식 사용**: 마크다운 파일에서 LaTeX 수식을 사용할 수 있다.
* 인라인 수식: `$...$`
* 블록 수식: `$$...$$`
예시:
```markdown
인라인 수식: $E = mc^2$
블록 수식:
$$
E = mc^2
$$
```
4. **MathJax 구성 (선택 사항)**: 기본 MathJax 설정 외에 추가로 설정을 하고 싶다면, `mkdocs.yml`에서 `config` 섹션을 사용하여 설정할 수 있다.
```yaml
plugins:
- mathjax:
config:
tex2jax:
inlineMath: [['$', '$'], ['\$ ', '\ $']]
```
#### 3. **MkDocs 로컬 서버 실행**
Mermaid와 LaTeX 플러그인을 설정한 후, 로컬 서버에서 결과를 확인하려면 다음 명령어를 사용한다.
```bash
mkdocs serve
```
브라우저에서 `http://127.0.0.1:8000/`로 접속하면 Mermaid 다이어그램과 LaTeX 수식이 제대로 렌더링되는지 확인할 수 있다.
### 테마 구성
MkDocs에서는 다양한 테마를 지원하며, 이를 통해 사이트의 디자인을 쉽게 변경할 수 있다. 기본적으로 제공되는 테마 외에도 추가적인 서드파티 테마를 사용할 수 있다. 여기서는 MkDocs에서 테마를 변경하는 방법과 커스터마이징하는 방법을 설명하겠다.
#### 1. **기본 테마 변경**
MkDocs에서 기본적으로 제공되는 테마 중 하나로 변경하려면 `mkdocs.yml` 파일에서 `theme` 항목을 설정하면 된다. 기본 제공 테마로는 `mkdocs`, `readthedocs` 등이 있다.
**테마 변경 예시**
```yaml
site_name: My Project
theme:
name: readthedocs
```
이렇게 설정하면 `readthedocs` 테마로 사이트의 디자인이 변경된다.
#### 2. **서드파티 테마 설치 및 사용**
MkDocs는 다양한 서드파티 테마를 지원한다. 이러한 테마를 사용하려면 먼저 설치한 후, `mkdocs.yml` 파일에서 해당 테마를 설정할 수 있다.
**서드파티 테마 예시: Material for MkDocs**
1. **Material for MkDocs 설치**
Material 테마는 MkDocs에서 가장 인기 있는 서드파티 테마 중 하나이다. 설치하려면 다음 명령어를 사용하라.
```bash
pip install mkdocs-material
```
2. **테마 활성화**
설치가 완료되면 `mkdocs.yml` 파일에서 Material 테마를 설정할 수 있다.
```yaml
site_name: My Project
theme:
name: material
```
3. **테마 커스터마이징**
Material 테마는 매우 다양한 옵션을 제공한다. 예를 들어, 색상이나 글꼴을 변경하려면 다음과 같이 설정할 수 있다.
```yaml
theme:
name: material
palette:
primary: 'indigo'
accent: 'pink'
font:
text: 'Roboto'
code: 'Roboto Mono'
```
#### 3. **커스텀 CSS 사용**
만약 기본 제공 테마나 서드파티 테마를 사용하면서도 추가적으로 디자인을 수정하고 싶다면, `extra_css` 항목을 사용하여 커스텀 CSS 파일을 추가할 수 있다.
1. **CSS 파일 추가**
먼저 `docs/` 폴더 안에 `custom.css` 파일을 생성한 후, 원하는 CSS 스타일을 정의한다.
```css
/* custom.css */
body {
background-color: #f0f0f0;
}
```
2. **`mkdocs.yml` 파일에 CSS 파일 추가**
다음으로, `mkdocs.yml` 파일에 CSS 파일을 등록한다.
```yaml
extra_css:
- css/custom.css
```
이렇게 하면 `custom.css`에서 정의한 스타일이 사이트에 반영된다.
#### 4. **커스텀 템플릿 사용**
만약 더 큰 수준의 커스터마이징이 필요하다면, MkDocs에서 HTML 템플릿을 직접 수정할 수도 있다. `mkdocs.yml` 파일에서 `extra_templates`를 사용하여 HTML 템플릿 파일을 지정할 수 있다.
```yaml
theme:
name: material
custom_dir: custom_theme
```
이렇게 하면 `custom_theme` 폴더에서 테마 템플릿을 수정하여 원하는 대로 커스터마이징할 수 있다.
***
1. **기본 테마 변경**: `mkdocs.yml`에서 `theme: name`을 설정하여 기본 제공 테마를 변경할 수 있다.
2. **서드파티 테마 설치**: `pip install` 명령어로 서드파티 테마를 설치하고 `mkdocs.yml`에서 활성화한다.
3. **커스텀 CSS 사용**: `extra_css` 항목을 사용하여 추가적인 스타일을 적용할 수 있다.
4. **커스텀 템플릿 사용**: HTML 템플릿을 직접 수정하여 사이트 디자인을 더 깊이 커스터마이징할 수 있다.