개요

Static 정적 사이트를 만들때 Gatsby, Jeklly, Docsify, Hexo 등을 사용 해봤는데 ... 빠르게 배포 및 관리 할 수 있는 메뉴얼을 위한 사이트를 목적으로 한다면 뭔가 부족했다.

경량 느낌 - docsify
다양한 확장 - Jeklly, Hexo
나만의 사이트 - Gatsby

사실, redocly 같은 걸 원했는데 막상 이건 또 유료기도 해서 좀 더 찾아봤다.

내가 원하는 것

필요 목적을 수립하고 이에 부합하는 것을 찾아 봤다

• Markdown 지원
• Docker 지원
• 정적사이트 빌드 및 배포 지원

그러다 MkDocs 를 찾아 봤는데 좋은거 같아 소개 해본다.

설치

공식 도커이미지에 추가적으로 플러그인을 추가하여 사용 해봤다.

1. Dockerfile 만들기

FROM squidfunk/mkdocs-material
RUN pip install mkdocs-macros-plugin
RUN pip install mkdocs-glightbox

2. Dockerfile 빌드

docker build -t squidfunk/mkdocs-material .

3. 컨텐츠 설정 및 작성

최상위 경로에 mkdocs.yml 파일을 만들어 준다

site_name: My Docs
nav:
  - Home: index.md

폴더 및 파일 구성

4. MkDocs 실행

Windows 의 경우 아래 커맨드를 cmd 가 아닌 powershell 에서 실행해야 한다.
cmd 또는 gitbash 등으로 실행하면 Error: Config file 'mkdocs.yml' does not exist. 와 문구를 볼수 있는데, powershell 에서 실행하면 정상적으로 실행된다.

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

5. MkDocs 실행 ( docker compose )

docker-compose.yml 파일 작성 후 docker up 커맨드를 통해 실행할 수 있다.

version: '3'

services:
  mkdocs:
    container_name: mkdocs
    image: squidfunk/mkdocs-material
    restart: always
    ports:
      - '8000:8000'
    volumes:
      - '${PWD}:/docs'

6. MkDocs 배포

docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build

맺음말

정말 첫 화면을 보기까지 10분도 되지 않은 것 같다.

이런 손쉽고 빠른 설치 및 markdown 을 통한 손쉬운 컨텐츠 배포가 중요한 것 같다 : )