MkDocs のコードブロックと引用のスタイルをカスタマイズ

Takahiro Iwasa (岩佐孝浩)

2023年1月8日

4 min read

MkDocs

MkDocs は Markdown を使用してドキュメントを作成するツールで、ユーザーはスタイルをカスタマイズできます。この投稿では、コードブロックと引用のスタイルをカスタマイズする方法について説明します。

www.mkdocs.org

MkDocs

Project documentation with Markdown.

公式ページで利用可能なテーマも確認できます。詳細については、公式 MkDocs ドキュメントをご参照ください。

www.mkdocs.org

Choosing Your Theme - MkDocs

MkDocs インストール

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

$ pip install mkdocs

以下のコマンドで新規プロジェクトを作成してください。

$ mkdocs new sample-doc
$ cd sample-doc

デフォルトスタイル

index.md を編集し、以下の内容でサンプルのコードブロックと引用を追加してください。以下のサンプルテキストは、 Microsoft Word のランダムテキストジェネレータ =rand() によって生成しました。


$ echo '
```python
def print_text() -> None:
    text = """
Video provides a powerful way to help you prove your point. When you click Online Video, you can paste in the embed code for the video you want to add. You can also type a keyword to search online for the video that best fits your document.
To make your document look professionally produced, Word provides header, footer, cover page, and text box designs that complement each other. For example, you can add a matching cover page, header, and sidebar. Click Insert and then choose the elements you want from the different galleries.
Themes and styles also help keep your document coordinated. When you click Design and choose a new Theme, the pictures, charts, and SmartArt graphics change to match your new theme. When you apply styles, your headings change to match the new theme.
Save time in Word with new buttons that show up where you need them. To change the way a picture fits in your document, click it and a button for layout options appears next to it. When you work on a table, click where you want to add a row or a column, and then click the plus sign.
Reading is easier, too, in the new Reading view. You can collapse parts of the document and focus on the text you want. If you need to stop reading before you reach the end, Word remembers where you left off - even on another device.
"""
    print(text)


if __name__ == "__main__":
    print_text()
```

> Hello World
' >> docs/index.md

ドキュメンテーションサーバーを起動してください。

$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.04 seconds
INFO     -  [20:24:33] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [20:24:33] Serving on http://127.0.0.1:8000/

ブラウザで http://127.0.0.1:8000/ を開くと、以下のようにドキュメントが表示されるはずです。

デフォルトでは、行の高さがやや狭く、引用にはスタイルがありません。

Customizing

sample-doc/docs/ ディレクトリに以下の内容の extra.css を追加してください。

code {
  line-height: 2;
}

blockquote {
  border-left: 4px solid gray;
  font-style: italic;
  padding-left: 1em;
}

mkdocs.yml に以下の行を追加して、 CSS をサイトに適用してください。

$ echo 'extra_css: [extra.css]' >> mkdocs.yml

ブラウザで http://127.0.0.1:8000/ を開くと、以下のようにドキュメントが表示されるはずです。