existential-birds/beagle / plugins/beagle-elixir/skills/exdoc-config
exdoc-config
VerifiedConfigures ExDoc for Elixir projects including mix.exs setup, extras, groups, cheatsheets, and livebooks. Use when setting up or modifying ExDoc documentation generation.
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:
- Dependencies resolved — Run
mix deps.getfrom the project root. Pass: exit code0, andmix.exsincludesex_docas in Dependency Setup (or the project’s equivalent dev-only docs dep). - Extra paths real — For every path string in
extras/0(and ingroups_for_extras/0if used), confirm that path exists in the repo or you have just created that file. Pass: no stale or typo paths remain when you runmix docs. - Docs build — Run
mix docs. Pass: exit code0, and the HTML entry exists at<output>/index.html(default<project>/doc/index.html; usedocs: [output: ...]if you changedoutput).
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
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:
# 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:
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:
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:
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:
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:
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:
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:
@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:
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:
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:
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
# Generate HTML docs
mix docs
# Open in browser
open doc/index.html
Complete mix.exs Example
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |