素敵なサムシングを独断と偏見で一方的に紹介するブログ(´・ω・`)

IT

【グッバイエクセル/パワポ/スプレットシート 】ドキュメントをマークダウンでかけるMkDocsが最強過ぎた【Github管理可能】

投稿日: 2020年6月30日
最終更新日:

スポンサーリンク

336×280




ドキュメントをマークダウンで書ける時代がやってきた

オフィスソフトでのドキュメント管理はもう嫌だ!

システム開発やサイト制作をしている際、必ず仕様書設計書を作成し場合によっては納品する必要がありますよね。

昨今では、基本的にExcelPowerPointGoogleスプレットシートGooleスライドで作成や保守をする事が多いと思いますが、
これがまた悪い文化
何ですよねorz

何が悪いって、シート毎にレイアウトがバラバラになるので統一感が持てない点修正差分が分かりにくい点に不満を感じます。

もちろん、ある程度の履歴機能やテンプレートはありますが、それでもまだ使いにくい感は否めません。。。orz

Markdownで書けるドキュメントツールを発見

そんな最中、マークダウンでドキュメントを書けるという神ツールを見つけました!


Overview
MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introduction below, then check the User Guide for more info.MkDocs

このツールを使えば、Markdownベースでドキュメントを記述出来るため、git管理対象として保守する事が可能になります。

またHTML形式PDF形式にも出力する事が可能なようなので、納品対応にも対応出来るため期待が出来るツールとなっています!

そして何より、デザインやレイアウトのカスタマイズ性が高いのもMkDocsの魅力とも言えるでしょう。

今回は早速インストールをして基本的な部分の使い方を試してみようと思います♪

細かい機能やレイアウト調整については以下の記事にてご紹介しているので、興味のある方はそちらも読んでいただければなと思います♪

使い方

前提

MkDocsPythonを利用して動かすツールとなっています。

今回は以下の環境にて動作を確認しています。

Point

  • Python 3.6.3
  • Anyenv 1.1.1

インストール

以下のコマンドでMkDocsをインストールしてください。

確認

以下のコマンドで確認してみましょう。

無事にインストールされていますね♪

プロジェクトの作成

まずはプロジェクトを作成しましょう。

mkdocs new {プロジェクト名}で作成する事が可能です。

すると以下の形でディレクリが生成されます。

以降の作業は生成されたディレクトリに移動した上で行う事になります。

ローカルでの開発サーバ起動(Serve)

では、一旦初期の状態でMarkdownから生成されるHTMLを確認してみましょう。

デフォルトではindex.mdには以下の記述がされています。

以下のコマンドでローカルに開発サーバを起動出来ます。

これでhttp://localhost:8000/ にサーバが起動されHTMLが確認出来ます。

ホットリロード標準完備が便利過ぎる!

そしてこの開発サーバはホットリロードに対応しているので、サーバ起動後にMarkdownを変更すると自動で再リロードがかかります。

毎回再起動する必要なく、作業者はMarkdownの修正だけ気にすれば良いのはとても楽ですね!

ページを追加

ドキュメントのページを追加する際には、docs配下にmdファイルを追加するだけで自動で反映されます。

ページ名を制御

ページ名を変えたい場合や順番を変えたい場合は以下のようにmkdocs.ymlに記述する事で制御する事が可能です。

ちなみに、docs/index.mdトップページに該当するので用意しておく必要があります。

HTMLの生成(ビルド)

では、実際にHTML出力をしてみましょう。

すると、siteディレクトリが生成され、HTMLファイル一式が出力されています。

確認

ブラウザでindex.htmlを確認すると、正常に表示されていますね♪

とても簡単です!

本日のオススメ商品

終わりに

今回はインストールからシンプルなHTML出力までの確認をしました。

MkDocsの本領発揮はカスタマイズ性の高さなので、次回はその辺を試してみようと思います♪

皆さんも脱Office/GoogleDocsを目指してみてはいかがでしょうか♪

336×280




336×280




CATEGORIES & TAGS

IT, , , , , , , , , , , , ,

blogenist

Author: blogenist