[2021.02] MKDocs (1) - 소개 및 설정방법

2023.03.22 수정사항

 - MKDocs와 MZDocs를 혼용사용해서 헷갈리게 한 점 수정, 본글은 MKDocs에 대한 글입니다. 

 - MZDocs도 존재함. 

 

자료가 많아서 작성하지 않으려다가 시리즈 형태로 만들어볼까해서 만들어본다.

 

목차

[2021.02] MKDocs (1) - 소개 및 설정방법

 

[2021.02] MKdocs (2) - Docker로 Build하기

 

[2021.02] MKDocs (3) - Docker로 실행하기

 

윈도우 환경

필자는 윈도우에 파이썬 최신버전(3.9.8)을 설치하니 알아서 pip도 같이 깔아줬다. 

다만, 공식홈페이지도 설치했는데 예전에 윈도우 앱스토어에 있는 것을 설치했던 적이 있었는지 경로(PATH)가 꼬이면서 정상적으로 

실행되지 않았다. 그때는 우선 모두 제거하자.

그래도 에러가 난다면 .....  https://my-repo.tistory.com/19 - 이 링크로 필자는 해결했다.

 

리눅스에서 Python 및 Pip확인 (CentOS)

CentOS8은 망했고, CentOS7에서 보면 Python 2.7.5가 설치되어 있고, Pip은 설치되지 않은 상태다. 

> python -V
Python 2.7.5
> sudo yum install epel-release
> sudo yum install python-pip
> pip -V
pip 8.1.2 from /usr/lib/python2.7/site-packages (python 2.7)

그런데 mkdocs가 설치가 되지 않ㄴ는다. 

 

우여곡절 속에 정상적으로 "pip --version"이 실행된다면 이제 설치해보자.

필자는 윈도우 커맨드(또는 파워쉘)보다는 리눅스가 편해서 Git Bash를 즐겨 쓴다. 아래에 나올 리눅스 명령은 감안해서 봐주길 바란다.

 

1) mkdocs설치

pip install mkdocs

 

 2) 테마설치다. mkdocs-rtd-dropdown이라는 테마인데, readtodocs (비슷한 툴)과 똑같아진다. 

 이 테마의 단점은 마크다운에서 코드하이라이트(``` ~ ```) 태그가 제대로 먹지 않는다. 그래도 이쁘니까 설치하자.

pip install mkdocs-rtd-dropdown 

 

3) 메인 테마설치. 단점은 존재하지 않고 화사하다.

pip install mkdocs-material

 

4) 이모티콘 또는 탭, 하이라이트 등 마크다운 태그를 한층 업그레이드하는 플러그인 설치

자세한 사용방법: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/

pip install pymdown-extensions

 

설치완료!!

이제 프로젝트를 만들어보자.  

 

mkdocs new enjoyDocs

이 명령을 실행하면 현재 폴더에 enjoyDocs 폴더가 만들어지며, mkdocs.yml 파일과 docs라는 폴더에 index.md 파일이 생성된다.

 

주로 환경파일은 mkdocs.yml 파일에서 이뤄지며 docs는 컨텐츠를 만들 폴더가 된다. 

자세한 사용방법: https://www.mkdocs.org/user-guide/configuration/

우선 환경파일이다. 필자가 사용하는 파일은 다음과 같다. 

site_name: 엔조이데브
nav:
  - 소개 : index.md
  - 본문 : 
    - 엔조이데브 : enjoydev/index.md
  
theme:
  name: 'material'
extra_css: [ css/pymdownx.css]
markdown_extensions:
  - admonition
  - attr_list
  - pymdownx.details
  - pymdownx.emoji
  - pymdownx.pathconverter
  - pymdownx.progressbar
  - pymdownx.smartsymbols
  - pymdownx.tabbed
  - pymdownx.highlight

 

nav

 : 이것을 사용하지 않으면 폴더와 markdown파일을 기반으로 네비게이션을 생성한다. 이렇게 만들면 제목을 한글로 하기 위해 폴더명을 한글로 만들어야 하는 단점(?)이 있다. 이 태그를 이용하면 환경파일 내에서 직관적으로 네비게이션을 만들 수 있다.

 

markdown_extensions:

 : Markdown 태그 외에 더 사용할 수 있는 태그를 추가해준다. 이를 테면

이런 것을 컨텐츠에 추가할 수 있다. 

 

기동하기

mkdocs serve

또는

mkdocs serve -a 0.0.0.0:8000

그리고 브라우저에서 

http://localhost:8000 

또는

http://[자기아이피]:8000

으로 열어보자.

 

아래는 예시화면이다.