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

IT

【ドキュメントをMarkdownでGitHub管理】MkDocsで生成されるHTMLのレイアウトをカスタマイズする方法まとめ【グッバイExcel・PowerPoint】

投稿日: 2020年7月5日
最終更新日:

スポンサーリンク

336×280




MkDockのカスタマイズしよう

カスタマイズ方法

mkdocs.ymlを変更

MkDocsのテーマを変えるには、mkdocs.ymlを編集することになります。

デフォルトは以下のようになっていると思います。

テーマ変更

MkDosにはテーマ機能があります。

デフォルトで様々なテーマが用意されており

試しに、alabasterというテーマを適用してみましょう。

以下のように、theme: alabasterと追記してください。

すると、以下のようなレイアウトに変わると思います。

デフォルトと比べるとこんな感じです。

海外ライブラリのドキュメントページでよく見るデザインですね!

MkDocsを使っていたのか・・・!

他にも様々なライブラリがありますが、物によってはインストールをしないと使えないものもあるので色々試してみてください♪

This page contains a list of some external MkDocs themes. All these and more can be installed via pip. You can find additional themes on WheelodexMkDocs Themes · mkdocs/mkdocs Wiki · GitHub

今回はmkdocs-materialを使ってみようと思います。

以下のコマンドでインストールをします。

良い感じのマテリアルデザインに変わりました♪

CSSのカスタマイズ

テーマを使用していて、部分的に変えたい場合があると思います。

MkDocsであれば、簡単に独自CSSを用いて変更することが可能です!

docsディレクトリにcssディレクトリを作成し、以下のcssファイルを配置してみましょう。

そして、mkdocs.ymlに以下を追記してCSSを追加読み込みさせましょう。

これでCSSが読み込まれデザインが上書きされるようになりました。

あとは独自でレイアウトをCSSで調整出来ます。

Webの技術でドキュメントのレイアウトを調整出来るのはとても便利ですね♪

GoogleFontsなどの外部CSSを利用したい場合

CDNなどの外部CSSを利用したい場合にも対応可能です。

以下のようにURLを指定することで読み込まれるようになります。

正しく読み込まれていますね♪

注釈・警告文

admonitionという拡張機能を使うことで、ドキュメント内にヒントやメモ、警告などを表す事が出来ます。

とても綺麗に表示されていますね!

注釈文

ドキュメントには必要不可欠な注釈文ですが、もちろんMkDocsでも表現する事が可能です!

footnotesという拡張機能を利用する事で可能になります。

こちらもしっかりと注釈が表現されていますね♪

さらに文章中の注釈をクリックすると、対応する注釈にフォーカスされるので注釈が多い場合にもとても見やすいです♪

また、以下のように注釈のキー名が一致していれば数字じゃなくても良さそうなので、分かりやすい注釈キーを指定するのが良いかもしれませんね♪

画像の挿入

もちろん画像も埋め込むことが出来ます。

以下のディレクトリ構造の場合、

以下のようにパスを指定することで読み込むことが可能です!

画像も同じリポジトリで管理出来るので便利ですね♪

FontAwesomeの利用

ドキュメント内にFontAwesomeのアイコンを利用する事も出来ます。

fontawesome_markdownのインストール

まずはfontawesome_markdownというライブラリをインストールします。

mkdocs.ymlに追記

次にmkdocs.ymlに以下を追記します。

利用方法

ドキュメント内でFontAwesomeのアイコンを使うには:{FontAwesomeコード}:のように指定します。

試しにgithubのアイコンを利用してみましょう。

正常に表示されていますね♪

指定するコードは公式サイトにあるのでそちらで調べてみてください♪

コードハイライト

codehiliteという拡張機能を利用する事で、コードハイライトを表現する事が可能になります。

fontawesome_markdownの有効化

次にmkdocs.ymlに以下を追記します。

利用方法

ドキュメント内で利用するには、~で囲む事で表現可能です。

また、その際に{言語}~とする事で言語ごとのシンタックスハイライトを適用する事が出来ます。

綺麗にコードハイライトが表示されていますね♪

行番号を出したい場合

コードハイライトに行番号を出したい場合は以下のようにします。

テーブル

よく使うであろうテーブルについてもMarkdownでの表現が可能になっています。

利用方法

以下のように記述する事で任意のセル数のテーブルを表現する事が可能です。

テキストの寄せ方についても自由に実現出来るので良いですね♪

マーカー

テキストにマーカーを表現する事も可能です。

pymdownx.markの有効化

mkdocs.ymlに以下を追記します。

使い方

=~=のように囲む事で表現が可能です。

リンク

外部リンクも簡単に表現する事が可能です。

使い方

=~=のように囲む事で表現が可能です。

新しいタブで開きたい場合

このままだとページ遷移になってしまうので、別タブで開くようにするには、mkdocs.ymlattr_listを追加し、

以下のように記述する事で実現出来ます。

本日のオススメ商品

終わりに

以上のように色々とドキュメントをカスタマイズする事が出来ました。

他にも色々な拡張機能があるようなので、改めて紹介しようと思います♪

336×280




336×280




CATEGORIES & TAGS

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

blogenist

Author: blogenist