コンテンツにスキップ

mkdocsのコマンドパターン

For full documentation visit mkdocs.org.

Commands

  • mkdocs new [dir-name] - Create a new project.
  • mkdocs serve - Start the live-reloading docs server.
  • mkdocs build - Build the documentation site.
  • mkdocs -h - Print help message and exit.

Project layout

1
2
3
4
mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.

参照サイト

以下を見てこのmkdocsの説明をカスタマイズしている

実行方法

コマンドはWindowsでは、以下に置き換え

1
python -m mkdocs serve

以下でビルドするとsiteディレクトリが生成された

1
python -m mkdocs build

警告の記述

概要

拡張機能 Admonition を使うと、文書内にメモ、ヒント、警告などが目立つようなスタイルで表示してくれます。Admonition も含め、これから紹介する機能は material テーマをインストールすると一緒にインストールされます。

使う場合は mkdocs.yml で使うように指定します。

1
2
markdown_extensions:
  - admonition

例

Note

これはノートです。

Tip

ヒントです。

Warning

これは警告です

Danger

これは危険です。

Success

これは成功です。

Failure

これは失敗です。

Bug

これはバグです。

Summary

これは概要です。

折り畳みブロック

警告文拡張機能に似ていますが、こちらは折り畳みブロックです。詳細ブロックでは !!! の代わりに ??? を使います。

1
2
markdown_extensions:
  - pymdownx.details
Note

これはノートです。

Tip

ヒントです。

定義リスト

定義リストは定義語のリストを作成する拡張機能です。この拡張機能を使用するには def_list を追加する必要があります。

1
2
markdown_extensions:
  - def_list

使い方は以下のようになります。

例

定義語
ここに説明を書きます
継承
継承の説明をここに書きます。 複数行になったらどのようになるか。改行は無視されるようです。

注釈

拡張機能 footnotes を使います。使用する場合、footnotes を有効にします。

markdown_extensions: - footnotes

注釈をつけるには、つけたい言葉の後ろに 1 のように記述します。

Mkdocs とは静的サイトジェネレータです。 コンテンツは基本的に markdown1 形式で記述したソースファイルになります。

例

上記の場合、次のように表示されます。

コードハイライト

コードハイライトを有効にするには次のようにします。

1
2
3
4
5
6
markdown_extensions:
  - pymdownx.highlight:
      use_pygments: true
      noclasses: true
      pygments_style: monokai
      linenums: true

pygmentsを使ってハイライトをしないのであれば、use_pygments, noclasses, pygments_style は不要です。

コードは fenced code blocks ( `) バッククォートを書いて囲みます。

1
2
3
4
#include <iostream>
void main() {
    std::cout << "Hello world!" << std::endl;
}

mkdocs-codehilite

行番号を表示する場合は linenums を設定します。コードの表示では前後のスペース（マージン）をなくして表示しているものをよく見るようになりました。そこでスタイルシートを使って対応してみます。次のような内容をスタイルシートに追加します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
.md-typeset pre {
  color: #f8f8f2;
}
.md-typeset .highlighttable {
  margin-left:-20px;
  margin-right: -20px;
  border-radius: 0;
}
.md-typeset .highlighttable > * {
  --md-code-bg-color: #222 !important;
  --md-code-fg-color: #fefefe !important;
}
.md-typeset .highlighttable .linenos .linenodiv pre span {
  background-color: #222 !important;
  color: #fefefe !important;
}
.md-typeset .highlighttable .md-clipboard:before,
.md-typeset .highlighttable .md-clipboard:after {
  color: rgba(240,240,240,.8);
}
.md-typeset .highlighttable .md-clipboard:hover:before,
.md-typeset .highlighttable .md-clipboard:hover:after {
  color: rgba(102,217,224,1);
}

行番号をコードコードブロックごとに区別

行番号を3からはじめる

コードブロックに c++ linenums="3" のように記述する

3
4
5
6
#include <iostream>
void main() {
std::cout << "Hello world!" << std::endl;
}

行番号を表示しないようにする

コードブロックに c++ linenums="0" のように記述する

#include <iostream>
void main() {
std::cout << "Hello world!" << std::endl;
}

タブブロック

ドキュメント内でタブがついたブロックを作ることができます。

1
2
3
markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true

例

次のように使います。

  • Sed sagittis eleifend rutrum
  • Donec vitae suscipit est
  • Nulla tempor lobortis orci
  1. Sed sagittis eleifend rutrum
  2. Donec vitae suscipit est
  3. Nulla tempor lobortis orci

  1. 文書を記述するための軽量マークアップ言語のひとつ ↩↩