exdoc-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ExDoc Configuration

ExDoc 配置

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

主题	参考文档
Markdown、速查表（.cheatmd）、Livebook（.livemd）	references/extras-formats.md
自定义头部/正文标签、语法高亮、嵌套结构、注解	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

将ExDoc添加到

mix.exs

的依赖中：

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

在

mix.exs

中配置

project/0

函数：

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

docs/0 函数

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

定义私有

docs/0

函数，保持项目配置整洁：

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

选项	默认值	说明
`main`	`"api-reference"`	首页模块名称或额外文档的文件名（不含扩展名）
`logo`	`nil`	侧边栏显示的Logo图片路径
`output`	`"doc"`	生成文档的输出目录
`formatters`	`["html"]`	输出格式列表（ `"html"` 、 `"epub"` ）
`source_ref`	`"main"`	用于「查看源码」链接的Git引用
`assets`	`nil`	静态资源的源目录到目标目录的映射
`deps`	`[]`	依赖包的文档链接

Setting the Landing Page

设置首页

The

main

option controls what users see first:

elixir

undefined

main

选项控制用户首次看到的页面：

elixir

undefined

Use the README as the landing page (most common)

使用README作为首页（最常用）

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.

docs: [main: "getting-started"]


该值需匹配额外文档的文件名（不含扩展名）或模块名称。

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

额外文档是指API参考之外的页面，以文件路径列表的形式添加：

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

默认情况下，ExDoc使用第一个

h1

标题作为文档标题。可通过关键字元组覆盖：

elixir

defp extras do
  [
    {"README.md", [title: "概述"]},
    {"CHANGELOG.md", [title: "更新日志"]},
    "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

额外文档在侧边栏的显示顺序与列表中的顺序一致。请将最重要的页面放在前面：

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.

在侧边栏中将模块组织为逻辑分类：

elixir

defp groups_for_modules do
  [
    "传感器": [
      WeatherStation.Sensor,
      WeatherStation.Sensor.Temperature,
      WeatherStation.Sensor.Humidity,
      WeatherStation.Sensor.Pressure
    ],
    "数据处理": [
      WeatherStation.Pipeline,
      WeatherStation.Pipeline.Transform,
      WeatherStation.Pipeline.Aggregate
    ],
    "存储": [
      WeatherStation.Repo,
      WeatherStation.Schema.Reading,
      WeatherStation.Schema.Station
    ]
  ]
end

使用正则表达式按模式分组：

elixir

defp groups_for_modules do
  [
    "传感器": [~r/Sensor/],
    "数据模型": [~r/Schema/],
    "数据管道": [~r/Pipeline/]
  ]
end

未匹配到任何分组的模块会显示在默认的「模块」标题下。

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)

使用

groups_for_docs

在模块内对函数进行分组：

elixir

defp docs do
  [
    groups_for_docs: [
      "生命周期": &(&1[:section] == :lifecycle),
      "查询": &(&1[:section] == :queries),
      "变更": &(&1[:section] == :mutations)
    ]
  ]
end

在模块中为函数添加

@doc

元数据标签：

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

在侧边栏中组织指南、速查表和笔记本：

elixir

defp groups_for_extras do
  [
    "指南": [
      "guides/getting-started.md",
      "guides/configuration.md",
      "guides/deployment.md"
    ],
    "速查表": [
      "cheatsheets/query-syntax.cheatmd",
      "cheatsheets/ecto-types.cheatmd"
    ],
    "教程": [
      "notebooks/data-pipeline.livemd",
      "notebooks/sensor-setup.livemd"
    ]
  ]
end

使用通配符模式简化配置：

elixir

defp groups_for_extras do
  [
    "指南": ~r/guides\/.*/,
    "速查表": ~r/cheatsheets\/.*/,
    "教程": ~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.

添加依赖包的文档链接，让ExDoc可以解析跨引用：

elixir

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

这样配置后，类似

t:Ecto.Schema.t/0

的引用会直接跳转到依赖包的文档。

Generating Docs

生成文档

bash

undefined

bash

undefined

Generate HTML docs

生成HTML文档

mix docs

Open in browser

在浏览器中打开

open doc/index.html

undefined

open doc/index.html

undefined

Complete mix.exs Example

完整的mix.exs示例

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

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
    [
      "传感器": [~r/Sensor/],
      "数据处理": [~r/Pipeline/],
      "存储": [~r/Schema|Repo/]
    ]
  end

  defp groups_for_extras do
    [
      "指南": ~r/guides\/.*/,
      "速查表": ~r/cheatsheets\/.*/,
      "教程": ~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

配置速查表或Livebook作为额外文档时 → extras-formats.md
注入自定义CSS/JS、配置语法高亮或调整模块嵌套结构时 → advanced-config.md