CSSしたい（html_css_files）

1# config.py
2html_static_path = ["_static"]
3html_css_files = [
4    # "ファイル名",
5    "custom.css",
6]

html_css_filesでカスタムCSSを追加できます。 ファイル名はhtml_static_pathに設定したディレクトリからの相対パスにします。

1html_css_files = [
2    "css/heading.css", # 見出し用
3    "css/font.css",    # フォント用
4]

CSSファイルは複数指定できます。 その場合、リストに記述した順番で読み込まれます。 用途別にファイルを分割してもよいと思います。

メディアクエリしたい

1html_css_files = [
2    # ("ファイル名", {"media": "メディアクエリの種類"}),
3    ("print.css", {"media": "print"}),
4]

tuple形式でメディアクエリーを指定できます。 メディアクエリの種類はall（すべて）、print（印刷）、screen（画面）、speech（音声合成）から選択します。

参考

出力されるlinkタグ（外部ソースへのリンク要素）は次のようになります。

<link href="print.css" rel="stylesheet" media="print">

レイヤーしたい

1# conf.py
2html_css_files = [
3    "custom.css",
4]

custom.cssとCSSのレイヤー機能（@layer）と組み合わせることで、スタイルを柔軟に制御できます。

/* custom.css */
/* @import は custom.css からの相対パス */
@import url("reset.css") layer(reset);
@import url("base.css") layer(base);
@import url("layout.css") layer(layout);
@import url("theme.css") layer(theme);
@import url("components.css") layer(components);
@import url("overrides.css") layer(overrides);

/* レイヤーの優先度 : 低 -> 高 */
@layer reset, base, layout, theme, components, overrides

このサンプルでは、custom.cssの中でCSSファイル@importしています。 それぞれのファイルの内容はCSSの@layerを参照してください。

$ tree
docs/
  |-- conf.py
  |-- _static/
        |-- custom.css
        |-- reset.css
        |-- base.css
        |-- layout.css
        |-- theme.css
        |-- components.css
        |-- overrides.css

_staticディレクトリの中に、それぞれのCSSを配置しま す。 CSSファイルの中身は空でも問題ありません。

注釈

CSSファイルの中身が空でも問題ありませんが、 ファイルがない場合はエラーになります。