MkDocs
MkDocs(https://www.mkdocs.org/)は静的サイトジェネレーター。
Markdown記法で書いたのをHTMLにしてくれる。
いろいろある静的サイトジェネレータのなかで一番シンプル。
設定ファイルは mkdocs.yml ひとつだけ。
ただ、そのままだと見た目があれなので、
Material for MkDocs(https://squidfunk.github.io/mkdocs-material/)を使う。
1. インストール
$ pip install mkdocs
$ pip install mkdocs-material
$ pip install fontawesome_markdown
$ pip install python-markdown-math
2. プロジェクト作成
$ mkdocs new [プロジェクト名]
3. ローカルサーバによる確認
アクセス先URLは127.0.0.1:8000
$ mkdocs serve
起動時オプションでURLは変更出来る
$ mkdocs serve -a 127.0.0.1:8080
4. ページの追加
[プロジェクト名]/docsディレクトリ配下に任意の.mdファイルを作成。
そのパスをmkdocs.ymlのnav:に設定すると、自動的にメニューやhtml等が生成される。
(pagesはもう古いので使ってはダメ)
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の下の方に、以下を追加すると全ページに対して勝手に対応してくれる。
google_analytics:
- !!python/object/apply:os.getenv ["GOOGLE_ANALYTICS_KEY"]
- auto
6. Disqus
静的サイトジェネレーターはコメントとか出来ない。でもコメント欲しい！
というのを実現してくれる機能。
disqusのアカウントを作って、mkdocs.ymlに以下の記述を追加すると全ページ勝手に対応してくれる。
なお、disqusを使う場合、site_urlの指定をしておかないとエラーになるみたい。
site_url: 'your-site-url'
〜
extra:
disqus: 'your-shortname'
7. アイコン
アイコンつけると見た目良くなる。
Font Awesomeから無料のものを選んで使う。
https://fontawesome.com/icons?d=gallery&m=free
設定
markdown_extensions:
- fontawesome_markdown
extra_css:
- 'https://use.fontawesome.com/releases/v5.7.2/css/all.css'
使用方法
MkDocs固有の記述方法
:fa-arrow-circle-right:
URLによる記述方法
<i class="fa fa-arrow-circle-right"></i>