개요

MkDocs라는 도구를 사용하면 쉽게 텍스트 기반 웹 사이트를 만들 수 있습니다.

약간의 연구자 개인의 사이트나, 기술계 사이트의 작성에 추천입니다.

MkDocs의 특징

Markdown(텍스트+α 정도의 간단한 언어의 기술)로, Web 사이트에 필요한 파일 세트를 만들 수 있다. HTML을 직접 괴롭히지 않아도 된다.

기존의 좋은 것 같은 디자인을 사용할 수 있다. Material for MkDocks를 사용하여 Google이 제창하고 있는 머티리얼 디자인을 사용할 수 있다.

환경 구축

파이썬을 사용할 수있는 환경이 있으면 사용할 수 있습니다. 나는 Windows에서 python을 설치하고 VSCode에 Python for VSCode 확장을 설치하고 VSCode 터미널에서 다음 명령을 실행했습니다.

pip3 install mkdocs
pip3 install mkdocs-material

그런 다음 내 환경에서 왜 mkdocs 경로가 통과하지 않았기 때문에 다음 위치를 설정했습니다.

C:\Users\USERNAME\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.7_qbz5n2kfra8p0\LocalCache\local-packages\Python37\Scripts

웹 사이트 작성 및 편집

새 프로젝트는 다음 명령으로 만들 수 있습니다.

mkdocs new test

그대로 작성된 파일을 열어 편집해 갑니다.

code mkdocs.yml
code .\docs\index.md

머티리얼 디자인을 사용하려면 다음 줄을 yml에 추가합니다.

theme:
  name: 'material'

디자인을 약간 변경하려면 여기을 참조하여 yml을 편집합니다.

md도 자유롭게 편집해 갑니다.
다음 명령을 터미널에 입력하고 브라우저에서 http://127.0.0.1:8000를 열면 작성한 사이트를 파일 업데이트별로 확인할 수 있습니다.

mkdocs serve

변경이 완료되면 HTML, css 등의 파일 세트를 생성합니다.

mkdocs build

프로젝트 아래에 site라는 폴더가 생성되어 이것을 웹 서버에 두면 웹 사이트 작성이 완료됩니다.
또, mkdocs gh-deploy 의 커멘드로 GitHub Pages에 사이트를 구축할 수도 있는 것 같습니다.