ex_doc
ExDoc generates HTML and EPUB documentation for Elixir and Erlang projects with offline access, search, and custom pages.
What is ex_doc?
ExDoc is a documentation generation tool for Elixir and Erlang projects that produces HTML and EPUB documentation from source code and Markdown files. It solves the problem of creating professional, accessible, and searchable documentation for libraries and applications in the BEAM ecosystem. It integrates with Mix and Rebar3 to automatically extract API details and supports custom pages, guides, and interactive content.
Elixir and Erlang developers who need to generate and maintain high-quality documentation for their libraries, applications, or open-source projects. It's particularly useful for projects published on Hex.pm that want to host documentation on HexDocs.
Developers choose ExDoc because it's the official, battle-tested tool for the Elixir/Erlang ecosystem, offering a seamless integration with build tools, beautiful default themes, and extensive customization options. Its ability to generate offline-accessible docs with full-text search and cross-linking between dependencies sets it apart from basic documentation generators.
Overview
ExDoc produces HTML and EPUB documentation for Elixir projects
Use Cases
Best For
- Generating HTML documentation for Elixir libraries published on Hex.pm
- Creating offline-accessible EPUB documentation for Erlang applications
- Building documentation sites with custom pages, guides, and livebooks
- Documenting umbrella projects with multiple applications
- Adding interactive content like Vega-Lite plots or Mermaid graphs to docs
- Providing keyboard-accessible documentation with search and autocomplete
Not Ideal For
- Projects requiring documentation for languages outside the Elixir/Erlang ecosystem
- Teams needing real-time collaborative editing or WYSIWYG interfaces for documentation authoring
- Applications prioritizing zero-JavaScript, server-side rendered documentation for SEO or performance reasons
- Environments where installing Erlang development packages is restricted or problematic
Pros & Cons
Pros
Includes full-text search, keyboard shortcuts (press '?' for help), and autocompletion for quick access, enhancing developer experience as detailed in the README.
Generates HTML, Markdown (including llms.txt), and EPUB documents from API docs, ensuring offline accessibility and flexibility, as stated in the features list.
Supports custom pages, guides, livebooks, and JavaScript injections for rendering math, graphs, and more, allowing deep customization via the extensions section.
Produces responsive documentation with night mode support and keyboard accessibility, adhering to modern web standards, highlighted in the features.
Cons
Requires Erlang development packages (e.g., erlang-dev on Debian) for some dependencies, which can complicate setup on certain operating systems, as warned in the README.
Designed specifically for Elixir and Erlang projects, making it unsuitable for documenting codebases in other programming languages, limiting its versatility.
Adding features like KaTeX for math rendering involves manual JavaScript injection and configuration, which may be daunting for developers unfamiliar with web technologies, as shown in the extensions examples.
Frequently Asked Questions
Related Projects
phoenix_swaggerSwagger integration to Phoenix framework
bureaucratGenerate Phoenix API documentation from tests
ex_doc_dashDash.app formatter for ex_doc.
xcribeXCribe is a doc generator for Rest APIs built with Phoenix. The documentation is generated by the test specs.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.