ChanJoon

Recent notes

See 62 more →

MkDocs and mkdocs-material

Sep 27, 20235 min read

MkDocs and mkdocs-material

MkDocs를 이용해서 연세드론 ROS 튜토리얼 페이지를 만들었는데, 추후 간단히 사이트 제작에 용이한 것 같아 작성해둠.

설치

sudo python -m pip install mkdocs mkdocs-material pymdown-extensions

우선 위 명령어를 통해 필요한 패키지를 다운로드 해준다.

MkDocs에는 여러가지 테마들이 있는데 많이 사용하는 것들은 Wiki에 나와있으니 참고하면 좋다.

나는 Material for MkDocs가 제일 마음에 들어 이걸 선택하였다.

사이트 설정

대부분의 사이트 설정은 mkdocs.yml으로 간편하게 해줄 수 있다.

공식 홈페이지에서 자세하고 직관적으로 설명해주고 있어서 따라하면 된다.

theme:
  name: material
  language: ko
  font:
    text: Nanum Gothic
    code: Roboto Mono
  logo: assets/book-solid.svg
  favicon: assets/yonseidroneicon.png
  features:
    - content.code.copy
    - content.code.select
    - navigation.top
  palette:
    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default 
      primary: orange
      toggle:
        icon: material/weather-sunny
        name: Switch to dark mode
 
    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: orange
      toggle:
        icon: material/weather-night
        name: Switch to light mode
extra:
  social:
    - icon: material/storefront-edit-outline
      link: https://yonseidrone.com
    - icon: fontawesome/brands/github
      link: https://github.com/YonseiDrone
copyright: Copyright © 2023 Chanjoon Park
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

위 예시 사이트에서 사용한 mkdocs.yml파일이다.

우선 theme 부분은 Material 테마를 사용하기 위한 부분과 언어 설정, 로고와 favicon 위치 설정이 있다.

theme:
  name: material # 테마
  language: ko   # 언어
  font:
    text: Nanum Gothic # Google Font에 있는 폰트 이름만 넣으면 설정가능
    code: Roboto Mono
  logo: assets/book-solid.svg         # 이미지 경로 지정
  favicon: assets/yonseidroneicon.png
  features:
    - content.code.copy   # 코드 복사기능
    - content.code.select # 코드라인 선택 기능
    - navigation.top      # 스크롤 맨 위로 이동
  palette:
    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default 
      primary: orange
      toggle:
        icon: material/weather-sunny
        name: Switch to dark mode
 
    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: orange
      toggle:
        icon: material/weather-night
        name: Switch to light mode

각 설정 설명은 주석으로 넣어두었다.

palette 설정은 사이트 우측 상단에 light / dark 모드를 변경할 수 있도록 해준다.

나머지 부분은 Github같은 외부 링크나 Extensions 설정 그리고 수식을 사용하기 위한 설정이다.

extra:
  social:
    - icon: material/storefront-edit-outline # 사이트 아이콘
      link: https://yonseidrone.com          # 사이트 링크
    - icon: fontawesome/brands/github        # Github 아이콘
      link: https://github.com/YonseiDrone   # Github 링크
copyright: Copyright © 2023 Chanjoon Park # 저작권 표시

그러면 아래 이미지처럼 생성된다.

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 설정은 사이트 링크를 보는게 좋겠다.

수식 사용은 extra_javascript와 extra_css의 마지막 줄을 그대로 사용하고 아래 파일을 docs/javascripts/ 에 넣어주면 된다.

document$.subscribe(({ body }) => { 
  renderMathInElement(body, {
    delimiters: [
      { left: "$$",  right: "$$",  display: true },
      { left: "$",   right: "$",   display: false },
      { left: "\\(", right: "\\)", display: false },
      { left: "\\[", right: "\\]", display: true }
    ],
  })

Github Actions

mkdocs serve로 제작한 사이트를 확인해보고 나서는 mkdocs build를 통해 빌드하고 배포할 수 있다.

하지만 Github Pages를 사용해 배포하려는 경우 Actions를 통해 쉽게 배포할 수 있다.

우선 .github/workflows/ci.yml 파일을 만들고 아래 내용을 넣는다.

name: ci 
on:
  push:
    branches:
      - master 
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
      - uses: actions/cache@v3
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force

그리고 Github 본인 리포지토리 Settings > Pages에서 사이트 설정을 해준다.

그리고 git push를 해주면 자동으로 수정사항을 git에 올릴 때마다 새로 배포된다.

Recent notes

See 62 more →

Backlinks