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

Dependency Setup

Add ExDoc to

mix.exs

deps:

elixir

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

Project Configuration

Configure your

project/0

function in

mix.exs

elixir

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:

elixir

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

Key Options

Option	Default	Description
`main`	`"api-reference"`	Landing page module name or extra filename (without extension)
`logo`	`nil`	Path to logo image displayed in sidebar
`output`	`"doc"`	Output directory for generated docs
`formatters`	`["html"]`	List of output formats ( `"html"` , `"epub"` )
`source_ref`	`"main"`	Git ref used for "View Source" links
`assets`	`nil`	Map of source directory to target directory for static assets
`deps`	`[]`	Links to dependency documentation

Setting the Landing Page

The

main

option controls what users see first:

elixir

# Use the README as the landing page (most common)
docs: [main: "readme"]

# Use a specific module as the landing page
docs: [main: "WeatherStation"]

# Use a custom guide
docs: [main: "getting-started"]

The value matches the extra filename without its extension, or a module name.

Extras

Extras are additional pages beyond the API reference. Add them as a list of file paths:

elixir

defp extras do
  [
    "README.md",
    "CHANGELOG.md",
    "LICENSE.md",
    "guides/getting-started.md",
    "guides/configuration.md",
    "guides/deployment.md",
    "cheatsheets/query-syntax.cheatmd",
    "notebooks/data-pipeline.livemd"
  ]
end

Controlling Extra Titles

By default, ExDoc uses the first

h1

heading as the title. Override with a keyword tuple:

elixir

defp extras do
  [
    {"README.md", [title: "Overview"]},
    {"CHANGELOG.md", [title: "Changelog"]},
    "guides/getting-started.md"
  ]
end

Ordering

Extras appear in the sidebar in the order listed. Put the most important pages first:

elixir

defp extras do
  [
    "README.md",
    "guides/getting-started.md",
    "guides/architecture.md",
    "guides/deployment.md",
    "CHANGELOG.md"
  ]
end

Grouping

Grouping Modules

Organize modules into logical sections in the sidebar:

elixir

defp groups_for_modules do
  [
    "Sensors": [
      WeatherStation.Sensor,
      WeatherStation.Sensor.Temperature,
      WeatherStation.Sensor.Humidity,
      WeatherStation.Sensor.Pressure
    ],
    "Data Processing": [
      WeatherStation.Pipeline,
      WeatherStation.Pipeline.Transform,
      WeatherStation.Pipeline.Aggregate
    ],
    "Storage": [
      WeatherStation.Repo,
      WeatherStation.Schema.Reading,
      WeatherStation.Schema.Station
    ]
  ]
end

Use regex to group by pattern:

elixir

defp groups_for_modules do
  [
    "Sensors": [~r/Sensor/],
    "Schemas": [~r/Schema/],
    "Pipeline": [~r/Pipeline/]
  ]
end

Modules not matching any group appear under a default "Modules" heading.

Grouping Functions

Group functions within a module using

groups_for_docs

elixir

defp docs do
  [
    groups_for_docs: [
      "Lifecycle": &(&1[:section] == :lifecycle),
      "Queries": &(&1[:section] == :queries),
      "Mutations": &(&1[:section] == :mutations)
    ]
  ]
end

Tag functions in your module with

@doc

metadata:

elixir

@doc section: :lifecycle
def start_link(opts), do: GenServer.start_link(__MODULE__, opts)

@doc section: :queries
def get_reading(station_id), do: Repo.get(Reading, station_id)

Grouping Extras

Organize guides, cheatsheets, and notebooks in the sidebar:

elixir

defp groups_for_extras do
  [
    "Guides": [
      "guides/getting-started.md",
      "guides/configuration.md",
      "guides/deployment.md"
    ],
    "Cheatsheets": [
      "cheatsheets/query-syntax.cheatmd",
      "cheatsheets/ecto-types.cheatmd"
    ],
    "Tutorials": [
      "notebooks/data-pipeline.livemd",
      "notebooks/sensor-setup.livemd"
    ]
  ]
end

Use glob patterns for convenience:

elixir

defp groups_for_extras do
  [
    "Guides": ~r/guides\/.*/,
    "Cheatsheets": ~r/cheatsheets\/.*/,
    "Tutorials": ~r/notebooks\/.*/
  ]
end

Dependency Doc Links

Link to documentation for your dependencies so ExDoc cross-references resolve:

elixir

defp docs do
  [
    deps: [
      ecto: "https://hexdocs.pm/ecto",
      phoenix: "https://hexdocs.pm/phoenix",
      plug: "https://hexdocs.pm/plug"
    ]
  ]
end

This enables references like

t:Ecto.Schema.t/0

to link directly to the dependency docs.

Generating Docs

bash

# Generate HTML docs
mix docs

# Open in browser
open doc/index.html

Complete mix.exs Example

elixir

defmodule WeatherStation.MixProject do
  use Mix.Project

  @version "1.3.0"
  @source_url "https://github.com/acme/weather_station"

  def project do
    [
      app: :weather_station,
      version: @version,
      elixir: "~> 1.17",
      start_permanent: Mix.env() == :prod,
      deps: deps(),
      name: "WeatherStation",
      source_url: @source_url,
      homepage_url: "https://acme.github.io/weather_station",
      docs: docs()
    ]
  end

  defp docs do
    [
      main: "readme",
      logo: "priv/static/images/logo.png",
      source_ref: "v#{@version}",
      formatters: ["html"],
      extras: extras(),
      groups_for_modules: groups_for_modules(),
      groups_for_extras: groups_for_extras(),
      deps: [
        ecto: "https://hexdocs.pm/ecto",
        phoenix: "https://hexdocs.pm/phoenix"
      ]
    ]
  end

  defp extras do
    [
      "README.md",
      "CHANGELOG.md",
      "guides/getting-started.md",
      "guides/configuration.md",
      "guides/deployment.md",
      "cheatsheets/query-syntax.cheatmd",
      "notebooks/data-pipeline.livemd"
    ]
  end

  defp groups_for_modules do
    [
      "Sensors": [~r/Sensor/],
      "Data Processing": [~r/Pipeline/],
      "Storage": [~r/Schema|Repo/]
    ]
  end

  defp groups_for_extras do
    [
      "Guides": ~r/guides\/.*/,
      "Cheatsheets": ~r/cheatsheets\/.*/,
      "Tutorials": ~r/notebooks\/.*/
    ]
  end

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

When to Load References

Setting up cheatsheets or livebooks as extras -> extras-formats.md
Injecting custom CSS/JS, configuring syntax highlighting, or tuning module nesting -> advanced-config.md

exdoc-config

NPX Install

Tags

SKILL.md Content

ExDoc Configuration

Quick Reference

Dependency Setup

Project Configuration

The docs/0 Function

Key Options

Setting the Landing Page

Extras

Controlling Extra Titles

Ordering

Grouping

Grouping Modules

Grouping Functions

Grouping Extras

Dependency Doc Links

Generating Docs

Complete mix.exs Example

When to Load References