MkDocsの導入メモ

MkDocsってなんぞ、何が良いの

markdownで記載されたテキストを、見た目の良いHTMLに変換してくれるソフトです。

以下良い点があります。(markdownの良い点でもあるが)

• シンプルにテキストで記載できる
• ただのテキストのためgit等のバージョン管理ソフトと相性が良い
• 内容と見た目が分離されており、見た目やすいビジュアルを色々と試せる
• 全文検索機能がある
• テーブルレイアウトも意外と綺麗に文章中に書ける
• MkDocks上で編集もできる

導入方法

基本のインストール

pip3 install  mkdocs

この後紹介の各種拡張もインストール

pip3 install  mkdocs-material # マテリアルデザイン＆各種機能の欲張り詰め合わせセット
pip3 install mkdocs-git-revision-date-plugin  # gitの情報を取り込んで表示
pip3 install mkdocs-live-edit-plugin # ライブエディターmkdocsだけでも編集できるように

以下カスタマイズしていきます、mkdocs-materialが機能豊富すぎて、
素のmkdocsの機能かmkdocs-materialの機能分からなくなることがあります。。。。

拡張関係も「features」「markdown_extensions」「extra」「plugins」どこに設定するのか混乱したり。。。
まあ、一度設定して動いた後に変に修正しなきゃ良いのですが。

私のファイル構成

.
├── markdown
│   ├── 記事1
│   │   ├── 記事2
│   │   ├── 記事3-1
│   │   ├── 記事3-2
│   │   └── 記事3-3
│   ├── 記事4
│   └── 記事5
├── overrides
│   ├── css
│   │   └── custom.css
│   ├── javascript
│   │   └── custom.js
│   └── partials
│       ├── footer.html
│       └── header.html
├── markdown.yaml
└── start_up.sh

カスタマイズ：mkdocs-material

マテリアルデザイン＆各種機能の欲張り詰め合わせセットです。検索機能等はこれで有効にします。

pip3 install  mkdocs-material

定番のダークモード/ライトモード切り替えスッチ追加

  palette:
    - scheme: default
      primary: 'teal'
      accent: 'pink'
      toggle:
        icon:  material/toggle-switch-off-outline
        name: ダークモードに切り替えます。
    - scheme: slate
      primary: 'teal'
      accent: 'orange'
      toggle:
        icon: material/toggle-switch
        name: ライトモードに切り替えます。

検索機能有効時設定部分

古いmkdocsは特別な対応が必要だったそうですが、今の最新バージョンは特に特別なことをしなくても、日本語の全文検索ができるようです。

  features:
    - search.suggest         ## 検索の候補リスト表示を表示する
    - search.highlight       ## 検索で一致した結果をハイライトする

各種ナビゲーション周り

コメントで無効にしている物も参考で入れています。

  features:
    ## - navigation.instant     ## mkdocs for MaterialのSPA対応 # SPAだとlive-editが効かないので無効化
    - navigation.tabs        ## トップレベル項目を画面上部メニューにタブ表示
    ##- navigation.sections  ## 項目のセクション表示 
    ##- navigation.expand    ## 初期表示で全てのページ展開を有効化
    - navigation.top         ## ページTOP遷移ボタンを有効化
    - navigation.path        ## パンくずリスト　動かない？
    ## - toc.integrate       ## 画面左右のメニューを統合
    - header.autohide        ## スクロールしたときヘッダーを自動的に非表示にする
    - search.suggest         ## 検索の候補リスト表示を表示する
    - search.highlight       ## 検索で一致した結果をハイライトする
    - content.code.copy      ## コードコピー機能

アラート装飾

アラート装飾も情報をまとめて見易い書き方を考える時便利。

markdown_extensions:
  - admonition     # アラート修飾の設定

カスタマイズ：mkdocs-git-revision-date-plugin編

mkdocsをgitで管理している場合に便利な拡張です。

対象記事について、gitの情報を元に更新日を出してくれます。
意外に便利です。git管理していない婆は無用の長物です。

pip3 install mkdocs-git-revision-date-plugin  # gitの情報を取り込んで表示

カスタマイズ：mkdocs-live-edit-plugin

基本はVS codeで書いているので、本機能を使うことは滅多にないのですが、ちょっとしたときに出来ないとイラっとするので、心の平穏のために入れています。思いの外出番はないけど。

pip3 install mkdocs-live-edit-plugin # ライブエディターmkdocsだけでも編集できるように

少し離れた話から始めますが、mkdocsは不特定多数にアクセスさせるような設定(0.0.0.0で起動)すると警告が表示されます。
live-editは、その機能性から外部ネットワークからイタズラされないようネットワーク制限がかけられています。(別ネットワークからアクセス時は機能しないよう)そのためローカル環境のDockerの場合でも、別ネットワークからのアクセスとして上記制限にあたり動きません。

ので、安全なローカル環境使用を前提に上記制限を直接書き換えて解除します。書き換えるべきファイルの場所を探します。

pip3 show mkdocs_live_edit_plugin # インストール位置確認

色々出てきた中に「Location:」という項目があります。こちらがインストール位置です。あまりpyhonパッケージに詳しくないのですが、このインストール先に

• mkdocs_live_edit_plugin〜バージョン
• live

ってフォルダがあります。変えるべきは「live」側のファイルになります。（なんでなんだろう。。。。。）

• /live/plugin.py

変更前

    async def event_loop(self):
        """The event loop of the websocket server."""
        async with serve(
            self.websocket_receiver,
            "127.0.0.1",
            self.config['websockets_port']
        ):
            self.log.info(
                'live-edit websocket server listening on port %s',
                self.config["websockets_port"]

変更後

    async def event_loop(self):
        """The event loop of the websocket server."""
        async with serve(
            self.websocket_receiver,
            "0.0.0.0",
            self.config['websockets_port']
        ):
            self.log.info(
                'live-edit websocket server listening on port %s',
                self.config["websockets_port"]

これでネットワークが違っても機能するようになります。ただし、これをインターネットから自由にアクセスできる場所に置いたりするのはやめましょう。

あとこの拡張のmkdocs.yamlの設定は以下です。

plugins:
  - live-edit:
      websockets_port: 9091 # Dockerで使う場合は、ソースを直接一部変えないといけない

カスタマイズ：CSS編

古い人間のため、マテリアルデザインのスッキリしすぎなデザインだと、どこがタイトルかわからなくなります。ので、ベースはマテリアルデザインのまま、目立つようにH1,H2,H3,H4あたりの見た目を変えます。

mkdocs.yamlの設定は以下です。

theme:
  name: 'material'
  custom_dir: overrides
  language: ja # サイトの言語設定

〜途中省略〜〜
extra_css:
    - '../css/custom.css'

markdownのファイル群と、カスタマイズ用のファイルが混ざるのが嫌なので、カスタマイズ用のフォルダ：overridesを用意して、そこに入れています。

custom.css

.md-typeset h1 {
  border: solid 3px;
  padding: 0.5em;/*文字周りの余白*/
  border-radius: 0.5em;/*角丸*/
}

.md-typeset h2 {
  border-bottom: solid 3px;
}
.md-typeset h3 {
  border-bottom: solid 1px;
}
.md-typeset h4 {
  border-bottom: dashed 3px;
}
.md-typeset h5 {
  border-bottom: dashed 1px;
}

編集時の便利ツール：VS codeの画像貼り付け設定

画像の挿入は追加拡張を入れなくてもできるようです。自分が使い易いように設定をします。使われる画像がどこに保存されるのが良いかは、それぞれの趣味の範囲かと思います。

• 画像は記事の側に保存したい派
• 画像は記事の側に保存したいが、混ざるのは嫌派
• 画像は記事と全然別の場所にまとめて保存したい派

私は画像は記事の側に保存したいが、記事と画像が混ざるのは嫌だったので、記事と同じフォルダ内にimagesというフォルダを作成し、そこに保存するようにしました。参考までにそのあ場合の設定は以下。

setting.json

     "markdown.copyFiles.destination": { // 画像をドラック＆ドロップ時の動作指定
      "*": "./images/"
    },
 }

編集時の便利ツール：VS codeのMarkdown Table拡張

markdoでテーブルを作るのは意外にめんどくさいです。この拡張はmarkdownでテーブルを作成するときの補助をしてくれます。
なんとなく作ったの日本人では？と感じるような、きっちとした動作をします。全然作者さんのことを知らないですが。。。。
すでにコレ無しではテーブル形式で書く気がなくなるレベルで便利です。

果物<tab>値段<tab>備考
りんご<tab>100<tab>
なし<tab>130<tab>
ぶどう<tab>130<tab>

| 果物   | 値段 | 備考 |
| :----- | :--- | :--- |
| りんご | 100  |      |
| なし   | 130  |      |
| ぶどう | 130  |      |

編集時の便利ツール：VS codeのAscii Tree Generator

テーブルと同様にめんどくさいのが、ファイルのツリー情報とかです。
こちらも拡張機能で対応します。

以下のように書くと

# public
# dist
## index.d.ts
## index.js
# src
## index.ts

以下のように変換

.
├── public
├── dist
│   ├── index.d.ts
│   └── index.js
└── src
    └── index.ts

またVScode上から実際のパスを指定しての作成機能もあります。

編集時の便利ツール：vscode-textlint

textlintをvs-codeから使う拡張で各種日本語のチェックをしてくれます。
npmでtextlint本体のインストールが必要です。

最後私の設定例

# metadata
site_name: "Knowledgeページ"
site_author: "xxx"
copyright: Copyright © 2024 xxx
site_url: "http://localhost:9090"
docs_dir: "./markdown"
site_dir: "../../tmp/DevKnowledge"

theme:
  name: "material"
  custom_dir: overrides
  language: ja # サイトの言語設定
  icon:
    logo: material/school #サイト左上のアイコン
  palette:
    - scheme: default
      primary: "teal"
      accent: "pink"
      toggle:
        icon: material/toggle-switch-off-outline
        name: ダークモードに切り替えます。
    - scheme: slate
      primary: "teal"
      accent: "orange"
      toggle:
        icon: material/toggle-switch
        name: ライトモードに切り替えます。
  features:
    #---- 各種機能カスタマイズ(ナビゲーション関連)
    ## - navigation.instant     ## mkdocs for MaterialのSPA対応 # SPAだとlive-editが効かないので無効化
    - navigation.tabs ## トップレベル項目を画面上部メニューにタブ表示
    ##- navigation.sections  ## 項目のセクション表示
    ##- navigation.expand    ## 初期表示で全てのページ展開を有効化
    - navigation.top ## ページTOP遷移ボタンを有効化
    - navigation.path ## パンくずリスト　動かない？
    ## - toc.integrate       ## 画面左右のメニューを統合
    - header.autohide ## スクロールしたときヘッダーを自動的に非表示にする
    - search.suggest ## 検索の候補リスト表示を表示する
    - search.highlight ## 検索で一致した結果をハイライトする
    - content.code.copy ## コードコピー機能

    #---- 各種機能カスタマイズ(ヘッダー関連)
  font:
    text: Noto Sans JP
    code: Inconsolata
extra:
  homepage: http://192.168.0.117:5680/hobbit/workshop
  annotate: true // ページの右上にアノテーションボタンを表示
markdown_extensions:
  - admonition # アラート修飾の設定
  # - pymdownx.details # コンテンツの折りたたみ設定
  - pymdownx.superfences # スーパーフェンス機能の設定
  - codehilite: # コードハイライトの設定
      noclasses: true
      pygments_style: colorful
      linenums: true
  - pymdownx.tabbed:
      alternate_style: true # タブ機能　すべてで使えるわけでは無いが、プレビューとソース的使い方
  - pymdownx.tasklist:
      custom_checkbox: true # チェックリスト機能
  - pymdownx.magiclink # URLっぽいものは自動リンク機能
  - footnotes # 注釈機能
  - pymdownx.inlinehilite # インラインコードハイライト機能
extra_javascript:
  # テーブル並べ替え設定
  - https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
  - ../javascripts/tables.js
extra_css:
  - "../css/custom.css"
plugins:
  - git-revision-date # ファイル更新日を表示 git使わない場合はコメントアウト
  - tags:
      tags_file: tags.md
  - live-edit:
      websockets_port: 9091 # Dockerで使う場合は、ソースを直接一部変えないといけない
  - search:
      separator: '[\s\-\.]' # インデックス対象の条件
  - drawio-exporter:
      cache_dir: "drawio-exporter"
      drawio_executable: null
      drawio_args: ["--no-sandbox"]
      format: svg
      embed_format: "{img_open}{img_src}{img_close}"
      sources: "*.drawio"
      
# python3 -m mkdocs build --strict --verbose
# python3 -m mkdocs serve --dev-addr=0.0.0.0:9090 #ポート指定: 本体 9090 ,live-edit 9091