Customize how your ExDoc documentation looks

Documentation is a first-class citizen in the Elixir eco-system. ExDoc produces your project’s documentation in HTML format. Let’s learn how to customize its HTML and CSS.

Customizing style sheets

You may already know, ExDoc has a configuration filed named :docs in project/0 defined in the file mix.exs. You can add your custom stylesheet for the documentation with the options both :assets and :before_closing_tag.

:assets — Path to a directory that will be copied as is to the “assets” directory in the output path. Its entries may be referenced in your docs under “assets/ASSET.EXTENSION”; defaults to no assets directory.

:before_closing_tag — a function that takes as argument an atom specifying the formatter being used (:html or :epub) and returns a literal HTML string to be included just before the closing head tag (</head>). The atom given as argument can be used to include different content in both formats. Useful to inject custom assets, such as CSS stylesheets.

If you interest other options, run mix help docs or see the reference.

Okay, we’ve configured properly our project to add custom stylesheet. Next, place the file etc/assets/doc.css and implement docs_before_closing_head_tag/1 function.

Adding HTML attributes

The default markdown renderer used by ExDoc is pragdave/earmark which supports the IAL (Inline Attributes List) extension. You can add HTML attributes to any block elements. For example, in the following code, I added class="diagram" to the pre element for a code block.

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

With this trick and a custom stylesheet, you can change the look of any block element in your document 🎉

This article was translated from the original post by the author.