MkDocs 를 이용하여 문서 사이트 만들기

본 게시물은 파이썬의 mkdocs 패키지를 이용하여 문서 사이트를 만드는 방법에 대해 소개하고 있습니다.

하단의 방법을 이용하여 mkdocs로 문서를 만들고자 할 경우, 개발 환경 내에 python 이 먼저 설치되어있어야하며, github 계정이 필요합니다 (github.io 를 이용하여 간단히 배포하기 위한 목적입니다).

 

mkdocs 를 이용하여 문서를 만들면 다음과 같은 형태의 사이트를 만들 수 있습니다. (아래는 readthedocs라는 테마가 적용된 버전입니다)

 

MkDocs 를 이용하여 만들어진 사이트의 예시

 

---

Mkdocs 를 이용하여 문서 사이트 만들기

 

1. mkdocs 선택 이유

 

블로그는 글이 시간순으로 정렬되기 때문에, 책처럼 목차가 보이는 형태의 사이트를 찾던 중 Sphinx나 MkDocs를 찾게 되었습니다. 둘 중 MkDocs 사용법이 더 간단해보여서, 이걸로 선택하였습니다.

 

Sphinx 시작하기)

tech.songyunseop.com/post/2017/11/setting-til-page-with-sphinx/

MkDocs 시작하기)

demun.github.io/mkdocs-tuts/

 

cf) 정말 쉬운 버전으로 작업을 하길 원한다면 위의 선택지 대신 WikiDocs를 추천합니다.

 

2. mkdocs 설치 및 프로젝트 생성

 

1.에서 말씀드린 MkDocs 참고문서를 보고, 다음과 같이 mkdocs 패키지를 설치하였습니다.

(파이썬이 먼저 설치되어있어야합니다.)

 

명령 프롬프트 창에서 "pip install mkdocs" 를 입력하여 설치합니다.

pip install mkdocs

mkdocs 가 정상적으로 설치되었다면, 다음과 같이 mkdocs 프로젝트를 생성하라고 안내되어있습니다.

mkdocs new 원하는프로젝트명

그러나 이 단계에서 다음과 같이 오류메세지가 나는 경우가 있습니다!!

 

명령 프롬프트 에러)

C:\Users\BY\Documents\Github\Linux CPU and Power Management>mkdocs new linux-power
'mkdocs'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는
배치 파일이 아닙니다.

MINGW 에러)

BY@DESKTOP-BS9Q3LI MINGW64 ~/Documents/Github/Linux CPU and Power Management
$ mkdocs new linux-power
bash: mkdocs: command not found

위의 에러메세지를 구글에 검색해본 결과, mkdocs 가 있는 경로가 환경변수에 포함되어있지 않아서 발생한 것이었습니다. (질문/답변 참고) github.com/mkdocs/mkdocs/issues/2184

 

따라서 다음과 같이 mkdocs.exe가 존재하는 폴더를 환경변수에 추가해줍니다.

제어판>시스템>고급 시스템 설정>고급>환경 변수>사용자 변수 중 "Path" 선택하고 "편집" 눌러서 다음의 경로를 추가합니다. 

C:\Users\BY\AppData\Roaming\Python\Python36\Scripts\ 

환경 변수 추가 화면 예시

환경변수에 추가한 이후에는 보통 재부팅을 해야하지만, 재부팅을 하지 않고도 환경변수를 적용할 수 있는 방법이 있습니다!! 바로 명령프롬프트 창에 set을 입력하는 것입니다.

set

(혹시 mkdocs 명령어가 여전히 오류가 발생한다면, 명령 프롬프트를 껐다가 다시 켜고 set을 다시 입력해주세요)

 

set 명령어 사용법) blog.naver.com/PostView.nhn?blogId=carrotcarrot&logNo=40204680485

 

이제 환경변수 관련 에러가 해결되어 다음과 같이 mkdocs 프로젝트가 정상적으로 생성이 되었습니다.

C:\Users\BY\Documents\Github\Linux CPU and Power Management>mkdocs new linux-power
INFO    -  Creating project directory: linux-power
INFO    -  Writing config file: linux-power\mkdocs.yml
INFO    -  Writing initial docs: linux-power\docs\index.md

(참고) developer.gaeasoft.co.kr/development-guide/workflow/gitlab-style-guide/

git repository 명에 - 를 쓰는 것인지 _ 를 쓰는 것인지 규칙이 헷갈렸는데, - 가 일반적인 규칙인 듯합니다.

 

3. 로컬에서 사이트 실행

 

mkdocs new 명령어로 새 폴더가 생성되었는데, 해당 폴더로 이동합니다. 그리고 "mkdocs serve" 를 입력하여 serving을 합니다.

C:\Users\BY\Documents\Github\Linux CPU and Power Management>cd linux-power

C:\Users\BY\Documents\Github\Linux CPU and Power Management\linux-power>mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.55 seconds
[I 210321 17:28:48 server:335] Serving on http://127.0.0.1:8000
INFO    -  Serving on http://127.0.0.1:8000
[I 210321 17:28:48 handlers:62] Start watching changes
INFO    -  Start watching changes
[I 210321 17:28:48 handlers:64] Start detecting changes
INFO    -  Start detecting changes
[I 210321 17:29:18 handlers:135] Browser Connected: http://127.0.0.1:8000/
INFO    -  Browser Connected: http://127.0.0.1:8000/

그러면 이제 로컬에서 http://127.0.0.1:8000/ 로 접속이 가능해집니다.

mkdocs 새 프로젝트가 정상적으로 실행된 모습

 

 

4. 사이트명 및 카테고리 (폴더 구조) 수정하기

 

mkdocs 프로젝트를 빌드합니다. (# mkdocs build)

mkdocs build

그리고 mkdocs.yml 파일을 열어서 site_name 을 변경해줍니다. 이걸 변경하면 실제 브라우저에서 보이는 사이트 명 및 화면 상단에 보이는 이름이 모두 변경됩니다.

site_name: Linux CPU and Power

위의 수정사항을 반영하여 저장한 후 다시 mkdocs serve를 입력하여 사이트가 변화한 것을 확인합니다.

mkdocs serve

yml 파일의 site_name을 수정한 결과

폴더 구조를 변경하기 위해서는 동일한 yml 파일에 다음과 같이 원하는 폴더 구조를 입력합니다. (필요한 Markdown 문서들은 docs 폴더 밑에 생성해줍니다)

 

mkdocs.yml 

site_name: Linux CPU and Power

pages:
  - 홈: index.md
  - CPU:
    - 'CPU 목차' : '01_CPU/01_01_cpu_index.md'

 

(yml 문법 관련 에러 참고)

yml 문법 에러가 자꾸 발생해서 확인해보니 space 2칸이 기준이라고 합니다. pages 밑에는 space 2칸, 하위 폴더의 경우 space 4칸으로 작성하여서 에러가 해결되었습니다.

stackoverflow.com/questions/21144013/expected-block-end-yaml-error

 

(pages 관련 에러)

참고한 튜토리얼 문서대로 pages 로 입력하였으나, MkDocs에서 pages 라는 configuration은 추후에 더이상 지원하지 않는다는 에러 메세지가 나왔습니다. 이 부분은 nav 로 변경이 필요할 것으로 보입니다.

WARNING -  Config value: 'pages'. Warning: The 'pages' configuration option has been deprecated and will be removed in a future release of MkDocs. Use 'nav' instead. 

 

폴더구조가 반영되어 상단에 새로운 메뉴가 더 생성된 것을 확인할 수 있습니다.

pages 폴더 구조의 수정 사항 반영 결과

 

5. github 이용한 배포

 

배포를 하기 전에 먼저 github의 git repository 와 연동이 되어있어야합니다.

작업하던 로컬 폴더에서는 git init / git add . / git commit -m "Initial commit" 을 입력하고, github에서는 새 repo를 생성합니다.

 

사전 연동을 하지 않을 경우 다음과 같은 에러메세지가 나옵니다.

C:\Users\BY\Documents\Github\Linux CPU and Power Management\linux-power>mkdocs gh-deploy
WARNING -  Config value: 'pages'. Warning: The 'pages' configuration option has been deprecated and will be removed in a future release of MkDocs. Use 'nav' instead.
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: C:\Users\BY\Documents\Github\Linux CPU and Power Management\linux-power\site
INFO    -  Documentation built in 0.16 seconds
WARNING -  Version check skipped: No version specified in previous deployment.
INFO    -  Copying 'C:\Users\BY\Documents\Github\Linux CPU and Power Management\linux-power\site' to 'gh-pages' branch and pushing to GitHub.
ERROR   -  Failed to deploy to GitHub with error:
fatal: 'origin' does not appear to be a git repository
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

github에서 새로운 repository를 만들고, 해당 페이지에서 안내하는 대로 명령어를 입력하였습니다.

(두번째 ...or push an existing repository from the command line 을 따라쳤습니다.)

 

배포를 하기 위해서는 명령 프롬프트에 다음의 명령어를 입력합니다.

mkdocs gh-deploy

그러면 정상적으로 동작할 경우에는 다음과 같은 메세지를 확인할 수 있습니다.

C:\Users\BY\Documents\Github\Linux CPU and Power Management\linux-power>mkdocs gh-deploy
WARNING -  Config value: 'pages'. Warning: The 'pages' configuration option has been deprecated and will be removed in a future release of MkDocs. Use 'nav' instead.
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: C:\Users\BY\Documents\Github\Linux CPU and Power Management\linux-power\site
INFO    -  Documentation built in 0.16 seconds
INFO    -  Copying 'C:\Users\BY\Documents\Github\Linux CPU and Power Management\linux-power\site' to 'gh-pages' branch and pushing to GitHub.
INFO    -  Your documentation should shortly be available at: https://BY1994.github.io/linux-power/

github repository 의 settings 를 누르고, 왼쪽의 메뉴 중 Pages 를 선택합니다. 그리고 branch 를 gh-deploy 로 선택합니다. (save 버튼도 눌러줘야합니다.)

github repository settings 화면

여기까지 진행하면 "Github아이디.github.io/생성한repository명"으로 접속이 가능해집니다.

참고한 튜토리얼 문서에서는 gh-deploy를 친 후에 생긴 변경사항까지 github에 업로드해주도록 안내하고 있으므로, 나머지 파일들도 모두 업로드 합니다.

 

(1) git status로 변경된 파일 확인

C:\Users\BY\Documents\Github\Linux CPU and Power Management\linux-power>git status

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   site/404.html
        modified:   site/index.html
        modified:   site/search/search_index.json
        modified:   site/sitemap.xml
        modified:   site/sitemap.xml.gz

Untracked files:
  (use "git add <file>..." to include in what will be committed)

        site/01_CPU/

no changes added to commit (use "git add" and/or "git commit -a")

(2) git add . 으로 변경된 모든 파일 git에 반영

C:\Users\BY\Documents\Github\Linux CPU and Power Management\linux-power>git add . 

warning: LF will be replaced by CRLF in site/404.html.
The file will have its original line endings in your working directory 
warning: LF will be replaced by CRLF in site/index.html.
The file will have its original line endings in your working directory
warning: LF will be replaced by CRLF in site/sitemap.xml. 
The file will have its original line endings in your working directory
warning: LF will be replaced by CRLF in site/01_CPU/01_01_cpu_index/index.html. 
The file will have its original line endings in your working directory 

(3) git commit -m 혹은 git commit을 입력하여 나온 창으로 commit 메세지 입력

 C:\Users\BY\Documents\Github\Linux CPU and Power Management\linux-power>git commit -s                                   [main 4874528] [feat] start gh-deploy for gihub io
 6 files changed, 232 insertions(+), 6 deletions(-)
 create mode 100644 site/01_CPU/01_01_cpu_index/index.html

(4) git push origin으로 github repository에 업로드

C:\Users\BY\Documents\Github\Linux CPU and Power Management\linux-power>git push origin
Enumerating objects: 20, done.
Counting objects: 100% (20/20), done.
Delta compression using up to 8 threads
Compressing objects: 100% (10/10), done.
Writing objects: 100% (12/12), 4.00 KiB | 1022.00 KiB/s, done.
Total 12 (delta 6), reused 0 (delta 0)
remote: Resolving deltas: 100% (6/6), completed with 5 local objects.
To https://github.com/BY1994/linux-power.git
   d1bad28..4874528  main -> main

 

여기까지 작업하면 모두 완성입니다!

 

Q. 한번 만든 후에 계속 업데이트하는 경우?

mkdocs.yml 에 목차를 업데이트해주고, 'mkdocs gh-deploy' 를 입력합니다.

그 후 생성된 파일들을 모두 위의 git 명령어들을 이용하여 github 에 반영해주면 됩니다.

 

 

+ 추가 업데이트 (2023.11.28)

mkdocs gh-deploy 명령어 입력시 pages 대신 nav 를 사용하라는 error 가 발생합니다.

$ mkdocs gh-deploy
ERROR    -  Config value 'pages': The configuration option 'pages' was removed
            from MkDocs. Use 'nav' instead.
Aborted with 1 Configuration Errors!

mkdocs.yml 을 열어서 pages 를 nav 로 변경합니다.

site_name: Linux CPU and Power

nav:
  - 홈: index.md

그리고 다시 mkdocs gh-deploy 를 입력하고, commit 을 push 하면 완료입니다.