mkdocs からの移行

mkdocs からの移行

bxSites migrate --from=mkdocs は、mkdocs プロジェクト（mkdocs.yml と その docs/ フォルダ）を、一つのコマンドで完全な bx-sites プロジェクトに 変換します:

bxSites migrate --source=/path/to/mkdocs-project --from=mkdocs

• --source（必須）- mkdocs プロジェクトのルートディレクトリ （mkdocs.yml を含んでいる必要があります）

GitBook からの移行とは違い、これは主に コンテンツの変換ではなく設定の変換です。mkdocs 自身の docs/ フォルダは すでに bx-sites とまったく同じ規約を使っています - フォルダのネストがナビ 構造であること、index.md がフォルダ自身のホームページであること、 ページ間の相対 .md リンクがそのまま機能することです。さらに重要なのは、 mkdocs-material 自身の拡張 Markdown 構文が、bx-sites がすでに話しているのと まったく同じテキスト構文だということです。そもそも bx-sites は mkdocs-material をモデルにして作られているからです（ Markdown 拡張機能 を参照）。そのため、ページ本文はバイト単位で そのままコピーされます - !!! note の Admonition も、=== "Tab" の コンテンツタブも、$x^2$ の数式も、ここでは書き換える必要は一切ありません。 すでに有効な bx-sites 構文だからです。

自動的に変換される内容

mkdocs.yml → bxsites.yaml:

markdown_extensions のそれ以外のエントリは、mkdocs-material 自身の構文が すでにネイティブにカバーしています - admonition、pymdownx.tabbed、 pymdownx.details、pymdownx.superfences、pymdownx.highlight、toc、 attr_list など - これらは bxsites.yaml の変更を一切必要としません。 bx-sites はすでに標準でその通りに振る舞います。

nav: → docs/nav.json:

# mkdocs.yml
nav:
  - Home: index.md
  - Guide:
      - Setup: guide/setup.md
      - Advanced: guide/advanced.md
  - About: about.md

は次のようになります:

[
  { "title": "Home", "path": "index.md", "children": [] },
  { "title": "Guide", "path": "", "children": [
    { "title": "Setup", "path": "guide/setup.md", "children": [] },
    { "title": "Advanced", "path": "guide/advanced.md", "children": [] }
  ] },
  { "title": "About", "path": "about.md", "children": [] }
]

• 裸のパスエントリ（明示的なタイトルのない - about.md）も変換されます - そのタイトルは移行済みページ自身のフロントマター/最初の見出しから 取得されます。title が設定されていない bx-sites の docs/nav.json エントリと同じ挙動です
• 完全な形式については設定: nav を参照してください

ページとアセット:

• すべての .md ファイルは、docs/ の下の同じパスに無変更でコピーされます
• それ以外のすべてのファイル（画像、PDF など）は docs/assets/mkdocs/<同じ相対パス> に再配置されます - bx-sites 自身の アセットパイプラインは docs/assets/** しか公開しないため、また mkdocs には GitBook の .gitbook/assets/ のような単一のアセットフォルダ規約がないため （画像は使用するページの隣に散らばっているのが一般的です）
• 再配置されたアセットへの参照 - 例えば ![diagram](img/diagram.png) - はすべて、リンク元のページ自身がどれだけ深い階層にあるかを考慮した上で、 新しい場所に正しく到達する相対パスに書き換えられます（どの bx-sites プロジェクトもすでに使っている「著者が正しい数の ../ を書く」という 規約と同じですが、ここでは find-and-replace に頼らず自動的に計算されます）

手動での確認が必要な内容

コマンド自身の出力に警告として報告されます。何も黙って捨てられることは ありません:

• bx-sites に対応するものがない mkdocs の markdown_extensions/plugins エントリ（mkdocs-material 自身の絵文字ショートコード、awesome-pages や git-revision-date のようなサードパーティプラグインなど）- 同じ挙動が 必要な場合はプラグイン を参照してください
• mkdocs.yml 自身の色/フォントカスタマイズ （theme.palette/theme.font）には直接の対応物がありません - 移行が 終わったら 色のカスタマイズ を参照してください
• material 以外の theme.name（bootstrap にデフォルトします）

実例

bxSites new --projectRoot=my-docs
bxSites migrate --projectRoot=my-docs --source=../my-mkdocs-project --from=mkdocs
cd my-docs
bxSites serve

migrate は bxsites.yaml と docs/ 自体を書き込みます - 上記の new ステップは、それらを受け取る準備として docs/ を持つプロジェクトルートを 用意するためだけのものです。migrate 自体も docs/ を自分で作成するため、 厳密には必須ではありません。コマンド自身の警告を確認したうえで、コミットする 前に serve で結果を見てください。