[Github Pages] Github 무료 호스팅으로 MkDocs 사용하기

MkDocs Material 테마

Notion을 이용하여 마크다운 형식의 페이지를 작성하고, Docker를 이용하여 생성될 페이지 미리보기를 확인 후, Git을 이용하여 홈페이지를 업데이트 하는 방법을 설명합니다.

 

Notion 사용

페이지 작성

내용은 노션의 편집 기능을 통해 자유롭게 작성하시면 됩니다. 하지만 한가지 주의하셔야 할 것은 나중에 생성될 Mkdocs 카테고리를 생각하셔서 /page나 /페이지 기능을 사용하여 구조적으로 만들어야 합니다.

Notion 페이지 구조

Mkdocs 카테고리 구조

페이지 내보내기

노션에는 작성한 페이지와 이미지들을 마크다운 확장자인 .md 형식으로 내보내는 기능이 있습니다. 노션에서 사용할 수 있는 여러 형식의 기능들은 기본 마크다운 형식으로 변환되어 내보내니 확인하시기 바랍니다.

최상위 페이지에서 내보내기 선택

하위 페이지 포함 버튼 활성화 후 내보내기

내보내기 압축파일 저장

마크다운 파일 내보내기 파일 압축해제 내용

 

Docker 사용

Mkdocs를 사용하는 방법에는 python, docker, git과 같은 방법이 있지만, 이 글에서는 기존에 설치하여 사용하던 docker를 사용합니다.

Docker 설치

2020/09/01 - [Cloud/Docker] - [Docker] 윈도우10 도커 데스크탑 설치(WSL2)

[Docker] 윈도우10 도커 데스크탑 설치(WSL2)

Mkdocs 이미지 가져오기

도커 데스크탑 실행 후 cmd 창에서 진행합니다.

docker pull squidfunk/mkdocs-material

Mkdocs 디렉토리 및 설정파일 생성

저의 경우 D:\Blog\test에 폴더를 생성하였습니다.

cd D:\Blog\test
docker run --rm -it -v D:\Blog\test:/docs squidfunk/mkdocs-material new .

디렉토리 및 설정파일 생성 확인

Notion에서 내보내기 후 압축 해제한 파일들을 사용합니다. 페이지가 될 .md 파일들과 이미지가 담겨있는 폴더들을 방금 생성된 docs 디렉토리에 복사합니다. 저의 경우 D:\Blog\test\docs 경로입니다.

붙여넣기 결과

>Notion에서 내보내기 한 파일 중 단순히 페이지를 표시하기 위한 파일과 기존에 있던 index.md 파일을 삭제합니다.

불필요한 파일 삭제

최초 접속시 노출되는 페이지인 홈 ~~~.md 파일의 이름을 index.md로 변경해줍니다.

홈(메인) 페이지 이름 변경

 

삭제 및 이름 변경 결과

 

Mkdocs 설정 및 미리보기

최소 설정 추가 저장 후 미리보기를 실행합니다.

편집 툴은 메모장 등을 사용하셔도 관계없으나 저의 경우 VS Code를 사용합니다.

yaml형식 설정파일의 들여쓰기는 space 2칸씩을 사용하시면 됩니다.

mkdocs.yml

저의 경로는 D:\Blog\test 이지만 각자 경로에 맞게 작성하여 cmd창에서 실행합니다.

docker run --rm -it -p 8000:8000 -v D:\Blog\test:/docs squidfunk/mkdocs-material

추가할 수 있는 .md 파일들의 경로 확인

Notion에서 내보내기한 파일의 이름이 복잡하여 경로가 어렵기 때문에 위 커맨드창에서 경로를 복사하여 아래 설정파일의 nav(카테고리) 작성을 완료하고 저장합니다.

nav 설정 추가

site_name: My Docs
theme:
  name: material
  language: kr
nav:
  - 홈: index.md
  - 개발:
    - 개발1: 개발 3f011ae567b44408bf721ebb9c8ae0b3/개발1 a50601d3a32340589fdc553db1f706d6.md
    - 개발2: 개발 3f011ae567b44408bf721ebb9c8ae0b3/개발2 eeb0cd3f3e014dc19191df92c4028f4b.md
  - 배포:
    - 배포1: 배포 f6ea6fc0a86d4083b8fa809efaede3fa/배포1 e05d05f7059b407eb3b89eed2a383d04.md
    - 배포2: 배포 f6ea6fc0a86d4083b8fa809efaede3fa/배포2 6bbdc0fb3812434d8329d4f99c5fac45.md
  - 서비스:
    - 서비스1: 서비스 c64126f722af4f07af3119ec994245e7/서비스1 d618e64e4fa043e08022ae92aa116050.md
    - 서비스2: 서비스 c64126f722af4f07af3119ec994245e7/서비스2 54a552fdf62b4caa83b1880f37527053.md

웹 브라우저에 주소 localhost:8000 으로 접속하여 디렉토리 및 페이지 적용을 확인합니다.

localhost:8000

 

 

docker run --rm -it -p 8000:8000 -v D:\Blog\test:/docs squidfunk/mkdocs-material 명령어 실행중에는 변경사항이 즉각 적용됩니다.

미리보기를 중지하려면 실행중인 cmd창에서 Ctrl+c를 입력합니다.

 

Git 사용

Github에 게시

저의 경우 VS Code를 사용하여 Github에 파일 및 폴더를 업로드(푸시)합니다. Git 툴은 편한 것을 사용하시면 됩니다.

test 폴더 열기

github에 게시

public으로 게시

확인

Github Action 작성

Github에 게시된 test Repository에서 시작합니다.

Actions 링크 클릭

set up a workflow yourself 링크 클릭

ci.yml Action 파일 생성

name: ci
on:
  push:
    branches:
      - master
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

ci.yml 생성 후 Action이 실행되며, master, gh-pages branch에 변경사항이 업데이트 됩니다.

Action 확인

Github Pages 설정

Setting > Options > GitHub Pages 설정

호스팅 주소 확인

페이지 접속 확인

 

마무리

이후 페이지 업데이트는 지금까지 해온 작업을 반복하시면 됩니다.

Notion을 사용하여 작성하고, Docker를 사용하여 미리보기 확인 후, Git을 사용하여 Push 하면 자동으로 업데이트 됩니다.

VS Code를 사용한 변경점 적용

변경 후 저장 > 변경사항 Commit > 변경사항 Push 의 과정으로 이루어지며, 변경된 내용은 자동으로 업데이트 됩니다.

변경사항 저장 후 확인

변경사항 입력 후 Ctrl+Enter 사용하여 Commit

Github으로 Push

Material for MkDocs

추가적인 커스터마이징이나 설정은 Mkdocs Meterial 테마의 공식 문서를 확인하시면 됩니다.

Material for MkDocs