Organizing page order in ExDoc

Questions / Help
1

Hello All :grinning:

We’re working on some documentation and have been greatly enjoying ExDoc. However, the default behavior for page order in nested groups is alphabetical. Is there an effective way to reorder, or add weighting to ensure pages are displayed in a cascading manner?

Many Thanks!!

2 Likes
2

Hi @devexir, welcome! :wave:

There isn’t a way to add weight to pages or reorder them in a custom order as far as I know. The thing that comes closest IMO is groups. Could that be a viable alternative?

1 Like
3

If anyone else is lead here by searching for it:
Since you can set the title for each page, you can set the order by having sortable filenames and then extract the page title out of them.
Taking a file structure like

❯ e -T docs
docs
├── architecture
└── infrastructure
   ├── 1_providers.md
   ├── 2_kubernetes.md
   └── 3_operating_system.md

I have the following documentation handling in my mix.exs:

defp docs do
  [
    formatters: ["html"],
    extras: Path.wildcard("docs/**/*.md") |> Enum.flat_map(&extract_title/1),
    groups_for_extras: [
      Infrastructure: ~r/infrastructure/,
      Architecture: ~r/architecture/
    ]
  ]
end

defp extract_title(path) do
  [_, filename] = Regex.split(~r/.*\//, path)

  title =
    Regex.named_captures(~r/^(?:\d+_)?(?<title>.+)\.md$/, filename)
    |> Map.get("title")
    |> String.split("_")
    |> Enum.map_join(" ", &String.capitalize/1)

  # While `String.to_atom/1` should generally be avoided, its usage is acceptable here since it will never be called
  # while the actual application is running, and never with user-generated input.
  [{String.to_atom(path), [title: title]}]
end

This leads to proper sorting and page titling.

3 Likes