728x90
반응형
MkDocs 설치 방법
- MkDocs를 활용해 Markdown(.md) 형식으로 작성된 가이드 문서를 효율적으로 관리 하는 방법에 대해 알아본다.
python 가상환경 생성
- MkDocs 는 python 을 통개 개발된 문서 관리 유틸이다.
- python 에서 제공 하는 가상환경(venv)을 만들어서MkDocs 를 설치 한다.
#mkdocs 가상환경 생성
python3 -m venv venv_mkdocs
#가상환경 활성화
source venv_mkdocs/bin/activate[guide_doc@my-rocky9.4:/home/guide_doc]$ python3 -m venv venv_mkdocs
[guide_doc@my-rocky9.4:/home/guide_doc]$ ll
합계 0
drwxr-xr-x. 5 guide_doc guide_doc 74 1월 13 14:39 venv_mkdocs
[guide_doc@my-rocky9.4:/home/guide_doc]$ source venv_mkdocs/bin/activate
(venv_mkdocs) [guide_doc@my-rocky9.4:/home/guide_doc]$
[guide_doc@my-rocky9.4:/home/guide_doc]$ ll
합계 0
drwxr-xr-x. 5 guide_doc guide_doc 74 1월 13 14:39 venv_mkdocs
[guide_doc@my-rocky9.4:/home/guide_doc]$ source venv_mkdocs/bin/activate
(venv_mkdocs) [guide_doc@my-rocky9.4:/home/guide_doc]$
MkDocs 설치
- pip 를 이용한 mkdocs 를 설치 한다.
- 설치후 mkdocs --version 를 이요해 버전을 확인 합니다.
- 삭제는 pip uninstall mkdocs 명령을 통해 삭제 할수 있습니다.
pip3 install mkdocs
pip install --upgrade pip
# mkdocs 버전확인
mkdocs --version
mkdocs, version 1.6.1 from /home/guide_doc/venv_mkdocs/lib/python3.8/site-packages/mkdocs (Python 3.8)
MkDocs 프로젝트 생성
- mkdocs new 명령을 통해 문서를 관리할 프로젝트를 생성한다.
mkdocs new md_guide
(venv_mkdocs) [guide_doc@my-rocky9.4:/home/guide_doc]$ mkdocs new md_guide
INFO - Creating project directory: md_guide
INFO - Writing config file: md_guide/mkdocs.yml
INFO - Writing initial docs: md_guide/docs/index.md
(venv_mkdocs) [guide_doc@my-rocky9.4:/home/guide_doc]$ ll
합계 0
drwxr-xr-x. 3 guide_doc guide_doc 36 1월 13 14:51 md_guide
drwxr-xr-x. 5 guide_doc guide_doc 74 1월 13 14:39 venv_mkdocs
(venv_mkdocs) [guide_doc@my-rocky9.4:/home/guide_doc]$ tree -a md_guide/
md_guide/
├── docs
│ └── index.md
└── mkdocs.yml
INFO - Creating project directory: md_guide
INFO - Writing config file: md_guide/mkdocs.yml
INFO - Writing initial docs: md_guide/docs/index.md
(venv_mkdocs) [guide_doc@my-rocky9.4:/home/guide_doc]$ ll
합계 0
drwxr-xr-x. 3 guide_doc guide_doc 36 1월 13 14:51 md_guide
drwxr-xr-x. 5 guide_doc guide_doc 74 1월 13 14:39 venv_mkdocs
(venv_mkdocs) [guide_doc@my-rocky9.4:/home/guide_doc]$ tree -a md_guide/
md_guide/
├── docs
│ └── index.md
└── mkdocs.yml
MkDocs 서버 실행
- mkdocs serve 명령을 실행하면 브라우저에서 실시간으로 작성된 문서를 확인 할수 있다.
- 기본 수행시 로컬에서만 접속이 가능 하다.
- http://127.0.0.1:8000
## 로컬에서만 접속 가능
mkdocs serve
##외부 접속을 허용하려면 -a 0.0.0.0:8000 옵션을 사용 한다.
mkdocs serve -a 0.0.0.0:8000
#백그라운드 실행
nohup mkdocs serve -a 0.0.0.0:8000 > mkdocs.log 2>&1 &- 브라우저에 접속을 하면 아래 URL 을 통해 문서를 확인할수 있다.
MkDocs 테마 적용
- MkDocs 는 다양한 테마를 지원합니다.
- https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes 에서 원하는 테마를 적용해서 사용 합니다.
- 아래 테마는 dracula 를 설정한 화면 입니다.
pip install mkdocs-dracula-theme- vi mkdocs.yml
site_name: My Docs
theme:
name: dracula
theme:
name: dracula
- 가장 많이 사용하는것으로 보이는 material 테마는 아래 링크에서 자세한 기능 및 설명 확인이 가능 하다.
- https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/
pip install mkdocs-materialMkDocs 플러그인 설치
mkdocs-awesome-pages-plugin
- 사이드바와 네비게이션을 자동 정렬 하는 플러그인
pip install mkdocs-awesome-pages-plugin- vi mkdocs.yml
plugins:
- search
- awesome-pages
markdown_extensions
- markdown 기능을 확장해서 사용 할수 있는 기능
pip install markdown_extensions
pip install pymdown-extensions
- vi mkdocs.yml
markdown_extensions:
# Python Markdown
- abbr
- admonition
- attr_list
- def_list
- footnotes
- md_in_html
- toc:
permalink: true
# Python Markdown Extensions
- pymdownx.arithmatex:
generic: true
- pymdownx.betterem:
smart_enable: all
- pymdownx.caret
- pymdownx.details
- pymdownx.highlight
- pymdownx.inlinehilite
- pymdownx.keys
- pymdownx.mark
- pymdownx.smartsymbols
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.tilde확장 이름기능 설명설치 필요 여부
| toc | 문서 내 목차 생성 | 기본 제공 |
| admonition | 강조 블록 (노트, 경고, 팁 등) 생성 | 기본 제공 |
| tables | Markdown 표 지원 | 기본 제공 |
| pymdownx.superfences | 코드 블록 기능 확장 | 설치 필요 |
| pymdownx.highlight | 코드 강조 기능 향상 | 설치 필요 |
| pymdownx.tabbed | 탭으로 콘텐츠 구분 | 설치 필요 |
| pymdownx.tasklist | 체크박스 스타일 지원 | 설치 필요 |
| pymdownx.details | 접을 수 있는 세부정보 블록 생성 | 설치 필요 |
| pymdownx.progressbar | 진행 바 생성 | 설치 필요 |
| abbr | 약어 지원 | 기본 제공 |
| meta | 문서의 메타데이터를 추가 | 기본 제공 |
mkdocs-mermaid2-plugin
- Mermaid 를 이용한 다이어그램을 표시해주는 기능
pip install mkdocs-mermaid2-plugin- vi mkdocs.yml
markdown_extensions:
- pymdownx.superfences:
# make exceptions to highlighting of code:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:mermaid2.fence_mermaid_custom
plugins:
- mermaid2:
version: 10.0.2
theme: "dark" # Mermaid 다이어그램 테마 (default, dark 등)
# securityLevel: "loose" # 보안 수준 (loose로 설정하면 외부 자원 로드 가능)MkDocs PDF
- pdf 파일을 브라우져에서 출력해주는 기능입니다.
pip install mkdocs-pdf- vi mkdocs.yml
# mkdocs.yml
markdown_extensions:
- attr_list
plugins:
- mkdocs-pdf- 사용법
{ type=application/pdf style="min-height:25vh;width:100%" }MkDocs navigator 설정
- material 테마 기준으로 nav 항목에서 좌측 side bar 와 top bar 매뉴 설정이 가능 하다.
- vi mkdocs.yml
nav:
- Home: index.md
- About: about.md
- Guides:
- Getting Started: guides/getting-started.md
- Advanced Topics: guides/advanced.md- index.md
# Welcome to MkDocs
For full documentation visit [mkdocs.org](https://www.mkdocs.org).
## Commands
* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.
## Project layout
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.
- mkdocs 디렉토리 구조
$ tree -L 4
.
├── docs
│ ├── about.md
│ ├── doctech
│ │ ├── README.md
│ │ └── guides
│ │ ├── advanced.md
│ │ └── getting-started.md
│ └── index.md
├── mkdocs.yml
└── overrides
.
├── docs
│ ├── about.md
│ ├── doctech
│ │ ├── README.md
│ │ └── guides
│ │ ├── advanced.md
│ │ └── getting-started.md
│ └── index.md
├── mkdocs.yml
└── overrides
728x90
반응형
'IT지식' 카테고리의 다른 글
| 쉘스크립트 (0) | 2024.11.08 |
|---|---|
| [IT지식] REST FUL 이란? (0) | 2022.06.04 |
| [IT 지식]스케일 아웃 vs 스케일 업 (0) | 2022.04.18 |
