コンテンツにスキップ

Top

MkDocs

MkDocs(https://www.mkdocs.org/)は静的サイトジェネレーター。
Markdown記法で書いたのをHTMLにしてくれる。

いろいろある静的サイトジェネレータのなかで一番シンプル。
設定ファイルは mkdocs.yml ひとつだけ。

ただ、そのままだと見た目があれなので、
Material for MkDocs(https://squidfunk.github.io/mkdocs-material/)を使う。

1. インストール

1
2
3
4
$ pip install mkdocs
$ pip install mkdocs-material
$ pip install fontawesome_markdown
$ pip install python-markdown-math

2. プロジェクト作成

1
$ mkdocs new [プロジェクト名]

3. ローカルサーバによる確認

アクセス先URLは127.0.0.1:8000

1
$ mkdocs serve

起動時オプションでURLは変更出来る

1
$ mkdocs serve -a 127.0.0.1:8080

4. ページの追加

[プロジェクト名]/docsディレクトリ配下に任意の.mdファイルを作成。
そのパスをmkdocs.ymlのnav:に設定すると、自動的にメニューやhtml等が生成される。
(pagesはもう古いので使ってはダメ) 

1
2
3
4
5
nav:
    - Home: index.md
    - User Guide:
        - Writing your docs: user-guide/writing-your-docs.md
        - Styling your docs: user-guide/styling-your-docs.md

5. Google Analytics

mkdocs.ymlの下の方に、以下を追加すると全ページに対して勝手に対応してくれる。 

1
2
3
google_analytics:
  - !!python/object/apply:os.getenv ["GOOGLE_ANALYTICS_KEY"]
  - auto

6. Disqus

静的サイトジェネレーターはコメントとか出来ない。でもコメント欲しい！
というのを実現してくれる機能。
disqusのアカウントを作って、mkdocs.ymlに以下の記述を追加すると全ページ勝手に対応してくれる。 なお、disqusを使う場合、site_urlの指定をしておかないとエラーになるみたい。

1
2
3
4
5
6
site_url: 'your-site-url'

〜

extra:
  disqus: 'your-shortname'

7. アイコン

アイコンつけると見た目良くなる。
Font Awesomeから無料のものを選んで使う。
https://fontawesome.com/icons?d=gallery&m=free

設定

1
2
3
4
5
markdown_extensions:
    - fontawesome_markdown

extra_css:
    - 'https://use.fontawesome.com/releases/v5.7.2/css/all.css'

使用方法

MkDocs固有の記述方法

1
:fa-arrow-circle-right:

:fa-arrow-circle-right:

URLによる記述方法

1
<i class="fa fa-arrow-circle-right"></i>