MkDocs and mkdocs-material
MkDocs를 이용해서 연세드론 ROS 튜토리얼 페이지를 만들었는데, 추후 간단히 사이트 제작에 용이한 것 같아 작성해둠.
설치
sudo python -m pip install mkdocs mkdocs-material pymdown-extensions
우선 위 명령어를 통해 필요한 패키지를 다운로드 해준다.
MkDocs에는 여러가지 테마들이 있는데 많이 사용하는 것들은 Wiki에 나와있으니 참고하면 좋다.
나는 Material for MkDocs가 제일 마음에 들어 이걸 선택하였다.
사이트 설정
대부분의 사이트 설정은 mkdocs.yml
으로 간편하게 해줄 수 있다.
공식 홈페이지에서 자세하고 직관적으로 설명해주고 있어서 따라하면 된다.
위 예시 사이트에서 사용한 mkdocs.yml
파일이다.
우선 theme
부분은 Material 테마를 사용하기 위한 부분과 언어 설정, 로고와 favicon 위치 설정이 있다.
각 설정 설명은 주석으로 넣어두었다.
palette
설정은 사이트 우측 상단에 light / dark 모드를 변경할 수 있도록 해준다.
나머지 부분은 Github같은 외부 링크나 Extensions 설정 그리고 LATEX 수식을 사용하기 위한 설정이다.
그러면 아래 이미지처럼 생성된다.
markdown_extensions:
- attr_list
- md_in_html
- toc:
permalink: "#"
toc_depth: 0
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
- admonition
- pymdownx.details
- admonition
extra_javascript:
- javascripts/katex.js
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js
extra_css:
- stylesheets/extra.css
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css
Extension 설정은 사이트 링크를 보는게 좋겠다.
LATEX 수식 사용은 extra_javascript
와 extra_css
의 마지막 줄을 그대로 사용하고 아래 파일을 docs/javascripts/
에 넣어주면 된다.
Github Actions
mkdocs serve
로 제작한 사이트를 확인해보고 나서는 mkdocs build
를 통해 빌드하고 배포할 수 있다.
하지만 Github Pages를 사용해 배포하려는 경우 Actions를 통해 쉽게 배포할 수 있다.
우선 .github/workflows/ci.yml
파일을 만들고 아래 내용을 넣는다.
그리고 Github 본인 리포지토리 Settings > Pages에서 사이트 설정을 해준다.
그리고 git push
를 해주면 자동으로 수정사항을 git에 올릴 때마다 새로 배포된다.