目次
MarkdownをBook化する
Book化する色々な方法
② 更新履歴
③ 画面イメージ画像
④ 画面定義書
⑤ イベント
⑥ 処理詳細
⑦ などなど..
これではクライアントに、こう言うしかありません。 『この画面仕様書は、このフォルダにある20ファイルをブラウザにポンポン投げて確認してね』
『あ、それからブラウザにプラグインも入れてね』と. うーん。
『エクセルにしてよぉ～』 って駄々をこねられそうですね。 マークダウンフィル自体にはエクセルの様なシート機能は本当にありませんが、サードパーティ製の便利なモジュールがありますので以下にまとめてみました。
| 製品名 | 開発環境 | 参照環境 |
|---|---|---|
| MkDocs | Python3.8以上必要 | なし |
| Docsify | サーバ(XAMPP可)必要 | サーバ(XAMPP可)必要 |
| 自作 | MarkdownViewerEnhanced必要 | MarkdownViewerEnhanced必要 |
MkDocsの環境構築と動作確認
C:\～\dir> python --version
Python 3.6.3 :: Anaconda, Inc.
C:\～\dir>
必要なのは『Python3.8』以上でした。
『MkDocs』に興味がある場合は、以下URLからpythonをダウンロードして環境を整えてくださいね。
https://www.python.org/downloads/windows/ Pythonの準備が整った方は、以下を叩いて「MkDocs」とレイアウト等を整えてくれる「Material」をインストールしましょう。
任意のディレクトリにターミナルを移動し、今回は「mybook」という名前で作成します。
C:\～\dir> cd 任意のディレクトリ
C:\～\dir> mkdocs new mybook
INFO - Creating project directory: mybook
INFO - Writing config file: mybook\mkdocs.yml
INFO - Writing initial docs: mybook\docs\index.md
C:\～\dir>
[mybook/]
+----- [mkdocs.yml]
+----- [docs/]
+----- [index.md]
同階層にある『docs/』の中にご自身のマークダウンファイルを自由に格納します。
当然ディレクトリを新たに作成し、ネスト状態も可能です。 それではサーバの起動確認をしてみましょう。
今いる場所から『mybook』へ移動し、ターミナルからコマンドを叩きます。
左側にナビゲーションメニュー、右側がドキュメントとなます。
表示がおかしな場合や表示しない場合は、サーバの起動忘れやエラーになってないか確認してください。
ナビゲーション編集
『MkDocs』の役割はそのMDファイル達をどうナビゲートするかです。
基本的に全て『mkdocs.yml』ファイルを編集します。
では早速デフォルトで存在する「index.md」をナビしてみましょう。
以下の様にymlファイルを編集して下さい。
エラーになってサーバが起動しない場合や表示内容が反映されない場合は以下を確認して下さい。
例えば「:」の後ろは半角スペースを空けます。
また「-」は親要素に対し【必ず半角２個】以上のスペースが必要です。
例）
nav:
- ホーム: index.md
ナビを階層化する
ディレクトリ構造を以下の様にしてみましょう。
[mybook/]
+----- [mkdocs.yml]
+----- [docs/]
+----- [index.md]
+----- [gamens/]
+----- [gamen.md]
site_name: My Docs
theme:
name: material
nav:
- ホーム: index.md
- 画面仕様書:
- gamens/gamen.md
mermaid（マーメイド）
そんな図を綺麗に見せてくれるのが、ミセスマーメイド（古い）です
※ 1992年J-POPグループ「チェッカーズ」の名曲です（Mrs.Mermaid）
設定はいたって簡単。以下を[yml]ファイル追加するだけです。
site_name: My Docs
theme:
name: material
extra_css:
- styles/custom.css
markdown_extensions:
- pymdownx.superfences
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
nav:
- ホーム: index.md
- 画面仕様書:
gamen/gamen.md
上記設定で動作しない場合は、以下の設定も追記してみてください。
- https://unpkg.com/[email protected]/dist/mermaid.min.js
ビルド
そこで最後の仕上げに、ブラウザさえあれば誰でも見れちゃう状態にします。
一旦サーバを落とし、コマンドプロンプトから以下を叩きます。
mkdocs build すると『site』フォルダが作成されます。
このフォルダをそのままクライアントに納品しましょう。 おや、まだ表示が変ですね。
そうです。これローカルだと上手く動きません。
「http」経由にする必要があります。 ではクライアントに『サーバ立ててください』と言えるか？
相手によりますが、通常は『は？おかしくね？』と言われそうです。
ではどうするか？
そう。サーバごと納品しちゃいましょう。 まずはサーバを以下からダウンロードします。
Hhttps://caddyserver.com/download 「Platform: Windows amd64」を選択して「DownLoad」を押下します。
落ちてきた「addy_windows_amd64.exe」をを[site/]へ設置する。
[site/]へ設置する場合、ダウンロード経由の実行ファイルの場合はブロックされます。
以下の操作で実行を許可しましょう。
右クリック > プロパティ > ブロックを解除（一番下）
「site/run.bat」を作成し、以下の様に編集します。
@echo off
start "" http://localhost:8000
caddy_windows_amd64.exe file-server --root . --listen :8000
これで本当に『site』フォルダをクライアントに渡しちゃいましょう。
先方は「site/run.bat」を叩くだけです。 ターミナルが立ち上がると同時にブラウザにドキュメントが表示されてるハズです。
「mermaid」もちゃんと表示されてますね。
終了する場合は、ターミナルを[Ctrl]+[c]となります。 いかがでしたか？
これがAI時代のドキュメント納品の形ではないでしょうか。
site_name: My Docs
theme:
name: material
nav:
- ホーム: index.md