[Mkdocs] Mkdocs 설치 및 사용 방법

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]$ 

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

 

 

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-material

MkDocs  플러그인 설치 

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

• 사용법

![Alt text](<path to 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