ex_doc

# ExDoc

[![Build Status](https://github.com/elixir-lang/ex_doc/workflows/CI/badge.svg)](https://github.com/elixir-lang/ex_doc/actions?query=workflow%3A%22CI%22)

ExDoc is a tool to generate documentation for Erlang and Elixir projects. To see an example, [you can access Elixir's official docs](https://elixir.hexdocs.pm/).

## Features

ExDoc ships with many features:

  * Automatically generates offline-accessible HTML, Markdown (including `llms.txt`), and EPUB documents from your API documentation.
  * When hosted, ExDoc relies on browser's page transitions for better UX, caching, and enhanced accessibility.
  * Responsive design, covering phones and tablets.
  * Support for custom pages, guides, livebooks and cheatsheets.
  * Support for custom grouping of modules, functions, and pages in the sidebar.
  * Customizable logo and favicon.
  * A direct link back to the source code for every documented entity.
  * Full-text search.
  * Keyboard shortcuts. (Press `?` to show help.)
  * Quick-search with autocompletion support. (`s` keyboard shortcut.)
  * Go-to shortcut with auto-complete to take the reader to any HexDocs package documentation. (`g` keyboard shortcut.)
  * Support for night mode, activated according to the browser preference.
  * Tooltips for links to modules and functions, both for the current project and other projects.
  * Version dropdown and "Go to latest" notifications, automatically configured when hosted on HexDocs.

## Usage

You can use ExDoc with Mix (recommended for Elixir projects), with Rebar (recommended for Erlang projects), or via the command line.

<!-- tabs-open -->

### Mix

ExDoc requires Elixir v1.15 or later. Then add ExDoc as a dependency:

```elixir
def deps do
  [
    {:ex_doc, "~> 0.34", only: :dev, runtime: false, warn_if_outdated: true},
  ]
end
```

Then run `mix deps.get`.

> #### Erlang development environment {: .warning}
>
> Some Operating System distributions split Erlang into multiple packages, and at least one ExDoc dependency (`earmark_parser`) requires the Erlang development environment. If you see a message like "/usr/lib/erlang/lib/parsetools-2.3.1/include/yeccpre.hrl: no such file or directory", it means you lack this environment. For instance, on the Debian operating system and its derivatives, you need to `apt install erlang-dev`.

ExDoc will automatically pull in information from your projects, such as the application and version. However, you may want to set `:name`, `:source_url` and `:homepage_url` in order to have nicer output from ExDoc:

```elixir
def project do
  [
    app: :my_app,
    version: "0.1.0-dev",
    deps: deps(),

    # Docs
    name: "MyApp",
    source_url: "https://github.com/USER/PROJECT",
    homepage_url: "http://YOUR_PROJECT_HOMEPAGE",
    docs: &docs/0
  ]
end

defp docs do
  [
    main: "readme", # can be changed to a module name, if you prefer
    logo: "path/to/logo.png",
    extras: ["README.md"]
  ]
end
```

Now you are ready to generate your project docum