mix docs で生成されるドキュメントの見た目をカスタマイズする

独自のスタイルシート

mix docs コマンドは mix.exs に定義された project/0 の :docs エントリーに設定を書くことができる。:assets オプションと :before_closing_head_tag オプションを組み合わせることで、独自のスタイルシートを追加できる。

def project do
  [
    apps_path: "apps",
    build_embedded: Mix.env() == :prod,
    start_permanent: Mix.env() == :prod,
    aliases: aliases(),
    deps: deps(),

    # Docs
    name: "MyProject",
    docs: [
      assets: "etc/assets",
      before_closing_head_tag: &docs_before_closing_head_tag/1
    ]
  ]
end

etc/assets/doc.css を配置し、docs_before_closing_head_tag/1 関数は以下のように定義する。

defp docs_before_closing_head_tag(:html) do
  ~s{<link rel="stylesheet" href="assets/doc.css">}
end
defp docs_before_closing_head_tag(_), do: ""

各オプションの詳細は mix docs コマンドのリファレンスを参照してほしい。

HTML 要素のクラスや属性のカスタマイズ

ExDocs はデフォルトで pragdave/earmark を Markdown レンダラに使っており、独自拡張を使うと任意のブロック要素にクラスや属性を指定できる。たとえば、以下の例では、コードブロックの pre 要素に class="diagram" を指定している。

```
Code text
```
{: .diagram }