MkDocsを使ってサイトを作る

Neovim上での単語補完

私の勤めているところでは、Markdown形式のメモがそこまで浸透していないので、Markdownファイルをそのまま渡すのも何となく気が引けます。また、画像を挿入したりしている場合はその画像も一緒に渡す必要があり、単一ファイルで完結しないにも面倒です。

かといって、書いたメモをPDFに変換するにも、MarkdownからPDF変換時に改ページを挿入しなおしたり、体裁を整える。必要があります。これも面倒です。

というか、そもそもMarkdownはHTMLに変換することを目的としたマークアップ言語なので、共有するなら、HTMLにすればええやん。と思いました。

MarkdownをHTMLに変換しよう。

前述したとおり、Markdownは、HTMLに変換することを目的としたマークアップ言語です。

今回はMkDocsというツールを使います。

どうしてMkDocsを使うのかというと MinervaのMkDocsでObsidianと互換性の高いドキュメントベースを実現するの記事を拝読したからです。

なのでほぼ100記事の内容を使用しています。

(faviconの設定や簡単な設定は変更しています。)

なので、使用する環境は記事が提供しているものとおなじものとします。

強いていえば、記事内で提供されていた。一発で環境構築するシェルをPowerShellで実行できるように書き換えたくらいです。

前提

Git
Python

上記がインストールされていること。

環境構築

細かい設定を羅列してもMkDocsでObsidianと互換性の高いドキュメントベースを実現するの二の舞になるので、詳細はこちらを参考してください。

以下を.ps1で保存しPowerShellから実行をすればWindowsでも、環境構築ができます。

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

New-Item -ItemType Directory -Path "Mkdocs-Sample" -Force | Out-Null
Set-Location "Mkdocs-Sample"

New-Item -ItemType Directory -Path "docs" -Force | Out-Null

@"
site_name: Mkdocs-Sample
strict: true
use_directory_urls: false
# TODO: site_url: これを設定しないと静的デプロイしたサイトでは有効にならない
theme:
  name: material
  icon:e
    logo: material/file
    repo: material/github
  features:
    - navigation.instant
    - navigation.instant.progress
    - content.code.copy
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: dark-blue  # ライトテーマ時の色
      toggle:
        icon: material/weather-night
        name: ダークモードに切り替え
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: dark blue       # ダークテーマ時の色
      toggle:
        icon: material/weather-sunny
        name: ライトモードに切り替え

plugins:
  - obsidian-bridge
  - awesome-nav
  - glightbox
  - search:
      lang: ja
  - backlinks_section:
      title: "🖇️ Backlinks"
      description: ""
      add_to_toc: false
      hide_if_empty: true
  - git-revision-date-localized:
      strict: false
      enable_creation_date: true
      locale: ja
      timezone: Asia/Tokyo

markdown_extensions:
  - footnotes
  - md_in_html
  - obsidian_callouts
  - pymdownx.magiclink
  - pymdownx.snippets:
      check_paths: true
      base_path: docs
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tabbed:
      alternate_style: true
"@ | Set-Content -Encoding UTF8 "mkdocs.yml"

@"
mkdocs
mkdocs-material
# WARNINGが出なくなったらこちらを使う
# mkdocs-obsidian-bridge
git+https://github.com/tadashi-aikawa/mkdocs-obsidian-bridge
mkdocs-awesome-nav
mkdocs-backlinks-section-plugin
mkdocs-git-revision-date-localized-plugin
mkdocs-git-authors-plugin
mkdocs-glightbox
"@ | Set-Content -Encoding UTF8 "requirements.txt"

@"
nav:
  - index.md
"@ | Set-Content -Encoding UTF8 "docs/.nav.yml"

@"
Hello Mks & Obsidian !!

- [[サンプル]]
"@ | Set-Content -Encoding UTF8 "docs/index.md"

@"
## Callout

> [!info]
> INFOのCallout
"@ | Set-Content -Encoding UTF8 "docs/サンプル.md"

git init && git add . && git commit -m "Initial commit"
python -m venv .venv
. .\.venv\Scripts\Activate.ps1
python.exe -m pip install --upgrade pip
pip install -r requirements.txt

作成したMarkdownをMkDocsでHTMLに変換する

先ほどのスクリプトを実行すると、docsフォルダが作成されます。そこにMarkdownファイルを配置していきます。

ファイルを配置したら、以下のコマンドを実行します。

Note

pyrhonの仮想環境を有効にしてから実行してください。

mkdocs build

このコマンドを実行すると、siteフォルダが作成され、その中にHTMLファイルが生成されます。

サーバーにアップロードする。

生成されたsiteフォルダをXServerなどのサーバーにアップロードします。現状は以下の手順で更新をしています。

サーバー管理画面からFTPアカウントの設定をする
WinScpを利用してsiteフォルダをpublic_htmlフォルダにアップロードする。

もっと効率的な方法があればそっちに移行したい。

さいごに

MkDocsを使うことで、Markdownで書いたメモを簡単にHTMLに変換して、サーバーにアップロードすることができました。

KuretaNone.netはこのようにして作成をしています。