exdoc-config

ExDoc Configuration

Quick Reference

Topic	Reference
Markdown, cheatsheets (.cheatmd), livebooks (.livemd)	references/extras-formats.md
Custom head/body tags, syntax highlighting, nesting, annotations	references/advanced-config.md

Gates

Use this sequence before claiming ExDoc is wired correctly or that docs build:

1. Dependencies resolved — Run mix deps.get from the project root. Pass: exit code 0, and mix.exs includes ex_doc as in Dependency Setup (or the project’s equivalent dev-only docs dep).
2. Extra paths real — For every path string in extras/0 (and in groups_for_extras/0 if used), confirm that path exists in the repo or you have just created that file. Pass: no stale or typo paths remain when you run mix docs.
3. Docs build — Run mix docs. Pass: exit code 0, and the HTML entry exists at <output>/index.html (default <project>/doc/index.html; use docs: [output: ...] if you changed output).

For cheatsheets, livebooks, or custom head/body assets, follow the same “path exists before listing” rule; see When to Load References.

Dependency Setup

Add ExDoc to mix.exs deps:

defp deps do
  [
    {:ex_doc, "~> 0.34", only: :dev, runtime: false}
  ]
end

Project Configuration

Configure your project/0 function in mix.exs:

def project do
  [
    app: :weather_station,
    version: "0.1.0",
    elixir: "~> 1.17",
    start_permanent: Mix.env() == :prod,
    deps: deps(),

    # ExDoc
    name: "WeatherStation",
    source_url: "https://github.com/acme/weather_station",
    homepage_url: "https://acme.github.io/weather_station",
    docs: docs()
  ]
end

The docs/0 Function

Define a private docs/0 function to keep project config clean:

defp docs do
  [
    main: "readme",
    logo: "priv/static/images/logo.png",
    output: "doc",
    formatters: ["html", "epub"],
    source_ref: "v#{@version}",
    extras: extras(),
    groups_for_modules: groups_for_modules(),
    groups_for_extras: groups_for_extras()
  ]
end