MkDocs環境の紹介

VRM Terminalは MkDocsと Material for Mkdocs で構築しています。

このページでは，VRM Terminalの構築に使っているMkDocs環境を紹介します。

MkDocsの概要

MkDocsは，Markdownで執筆した原稿をHTMLに仕立ててくれる静的サイトジェネレータです。デザインについては，サードパーティで豊富なテーマが多数公開されており，テーマカラーのカスタマイズ程度であれば難しくありません。 Material for Mkdocsは，Googleが提唱する「マテリアルデザイン」に基づくテーマで，いろいろなサイトで使われています。 VRMNXの公式マニュアルも使っていますね。

VRM Terminalの構築環境

Component	Version
OS	Windows 10
Editor	Visual Studio Code
Python	Python 3.10.7 (venv)
MkDocs	mkdocs 1.5.3
Material for MkDocs	mkdocs-material 9.5.3

このほか，Extensionがいくつか。

VRM Terminal構築用のPython環境（バージョン）を安定させるため， VS Code + venvでPython仮想環境を構築しています。

MkDocsのビルドコマンドもVS Codeに統合されているPowershellから叩けます。

コードブロック

今のMaterial for Mkdocsのバージョンでは，コードブロックの装飾も統合されています。 Ver. 9.5.3 時点の公式リファレンスを参考に設定しています。

mkdocs.yml

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

この方法（とバージョン）だと，行番号表示がずれません。表示領域をはみ出る場合には，スクロールバーが出てきます。（勝手に改行されない。）

```python linenums="1" title="LAYOUT"
import vrmapi
import toruo

def vrmevent(obj, ev, param):
    toruo.activate(obj, ev, param)
    # コメントを書いても大丈夫
    pass
```

LAYOUT
import vrmapi
import toruo

def vrmevent(obj, ev, param):
    toruo.activate(obj, ev, param)
    # コメントを書いても大丈夫
    pass

mkdocs.yml

特別に，mkdocs.ymlの全文を公開しちゃいます。 (2024.1.7時点)

mkdocs.yml
site_name: VRM Terminal
site_url: https://akagivrm.sokushinbutsu.com/
site_author: 'AKAGI'
copyright: '&copy; 2024 AKAGI Rails.'

nav:
  - Home: index.md
  - テクニック:
    - tips/index.md
    - tips/transition_curve/solver.md
    - tips/transition_curve/theory.md
  - ダウンロード:
    - download/index.md
    - VRM自作車両:
      - download/trainmodel/EC107/index.md
      - download/trainmodel/EC731_DC201/index.md
    - VRMNX用Python拡張:
      - 撮る夫くん: https://akagi-rails.github.io/vrmnx-toruo/
      - ATENXA: https://akagi-rails.github.io/ATENXA/
    - 車両テクスチャー:
      - 211系電車: download/usertex/EC211/index.md
  - VRM Terminalについて:
      - about.md
      - history.md

theme:
  name: 'material'
  language: 'ja'
  custom_dir: custom_theme/
  features:
    - navigation.footer
    - navigation.tabs
    - navigation.sections
    - navigation.path
    # - toc.integrate

  palette:
      primary: 'black'
      accent: 'pink'
  font:
      #text: 'Noto Sans JP'
      text: 'Roboto'
      code: 'Roboto Mono'
  logo: img/express185.svg
  favicon: img/express185.svg

extra:
  social:
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/AKAGIvrm
    - icon: fontawesome/brands/youtube
      link: https://www.youtube.com/@AkagiRails
  analytics:
    provider: google
    property: G-XXXXXXXXXX  # ここだけ内緒

markdown_extensions:
  - attr_list
  - admonition
  # [^1] を使って注釈を使う（Markdownのサンプルを参照）
  - footnotes
  - def_list
  # コードハイライトを使う
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - md_in_html
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - js/mathjax.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js