MkDocs のコードブロックとブロック引用のスタイリング
はじめに
MkDocs は、Markdown を使用してドキュメントを作成するための強力なツールです。スタイルのカスタマイズが柔軟に行え、ドキュメントを視覚的に魅力的で、プロフェッショナルに仕上げることができます。
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/ を開きます。デフォルトスタイルのドキュメントが表示されます。この時点では、コードブロックの行間が狭すぎたり、引用のスタイリングが不足していることに気づくかもしれません。
スタイルのカスタマイズ
外観を改善するには、sample-doc/docs/ ディレクトリに extra.css という名前の CSS ファイルを作成し、以下の内容を追加します。
code {
line-height: 2;
}
blockquote {
border-left: 4px solid gray;
font-style: italic;
padding-left: 1em;
}
この CSS ファイルを mkdocs.yml 設定ファイルに追加します。
echo 'extra_css: [extra.css]' >> mkdocs.yml
MkDocs サーバーを再起動します。
mkdocs serve
ブラウザで http://127.0.0.1:8000/ を開きます。以下の更新されたドキュメントが確認できます。
- コードブロックの行間が改善され、読みやすさが向上しています。
- 引用がスタイリングされ、境界線と斜体テキストで強調表示されています。
まとめ
MkDocs のスタイルをカスタマイズすることで、ドキュメントをより魅力的で読みやすいものにできます。これらの簡単な調整により、ドキュメントに際立ちを与え、よりプロフェッショナルな印象を実現できます。
さらなるカスタマイズアイデアについては、公式 MkDocs ドキュメントをご参照ください。
Happy Coding! 🚀
