Add IDs to nodes upfront

Author: josevalim

lib/ex_doc/doc_ast.ex

@@ -142,16 +142,22 @@ defmodule ExDoc.DocAST do
 
   @doc """
   Adds an id attribute to the given headers.
+
+  A prefix for the id attribute can be given,
+  which is automatically URL encoded to avoid
+  issues.
   """
-  def add_ids_to_headers(doc_ast, headers) do
+  def add_ids_to_headers(doc_ast, headers, prefix \\ "") do
+    prefix = URI.encode(prefix)
+
     doc_ast
     |> map_reduce_tags(%{}, fn {tag, attrs, inner, meta} = ast, seen ->
       if tag in headers and not Keyword.has_key?(attrs, :id) do
         possible_id = inner |> text() |> ExDoc.Utils.text_to_id()
         id_count = Map.get(seen, possible_id, 0)
-        actual_id = if id_count >= 1, do: "#{possible_id}-#{id_count}", else: possible_id
+        partial_id = if id_count >= 1, do: "#{possible_id}-#{id_count}", else: possible_id
         seen = Map.put(seen, possible_id, id_count + 1)
-        {{tag, [id: actual_id] ++ attrs, inner, meta}, seen}
+        {{tag, [id: prefix <> partial_id] ++ attrs, inner, meta}, seen}
       else
         {ast, seen}
       end

lib/ex_doc/formatter/html.ex

@@ -322,8 +322,8 @@ defmodule ExDoc.Formatter.HTML do
       title: "API Reference",
       title_content: title_content,
       headers:
-        if(nodes_map.modules != [], do: ["Modules"], else: []) ++
-          if(nodes_map.tasks != [], do: ["Mix Tasks"], else: [])
+        if(nodes_map.modules != [], do: [{:h2, "Modules", "modules"}], else: []) ++
+          if(nodes_map.tasks != [], do: [{:h2, "Mix Tasks", "mix-tasks"}], else: [])
     }
   end
 
@@ -423,6 +423,7 @@ defmodule ExDoc.Formatter.HTML do
           ast =
             source
             |> Markdown.to_ast(opts)
+            |> ExDoc.DocAST.add_ids_to_headers([:h2, :h3])
             |> sectionize(extension)
 
           {source, ast}
@@ -447,20 +448,20 @@ defmodule ExDoc.Formatter.HTML do
 
     source_path = source_file |> Path.relative_to(File.cwd!()) |> String.replace_leading("./", "")
     source_url = source_url_pattern.(source_path, 1)
-
     search_data = normalize_search_data!(input_options[:search_data])
 
     %{
       source: source,
-      content: content_html,
       group: group,
       id: id,
       source_path: source_path,
       source_url: source_url,
       search_data: search_data,
       title: title,
       title_content: title_html || title,
-      headers: ExDoc.DocAST.extract_headers(ast, [:h2])
+      # TODO: Remove these fields but first we would need to make API reference return DocAST
+      content: content_html,
+      headers: ExDoc.DocAST.extract_headers_with_ids(ast, [:h2])
     }
   end
 

lib/ex_doc/formatter/html/templates.ex

@@ -135,30 +135,18 @@ defmodule ExDoc.Formatter.HTML.Templates do
     %{key: text_to_id(group), name: group, nodes: nodes}
   end
 
-  defp module_sections(%ExDoc.ModuleNode{rendered_doc: nil}), do: [sections: []]
-
   defp module_sections(module) do
-    {sections, _} =
-      module.doc
-      |> ExDoc.DocAST.extract_headers([:h2])
+    sections =
+      (module.doc || [])
+      |> ExDoc.DocAST.extract_headers_with_ids([:h2])
       |> headers_to_id_and_anchors()
-      |> Enum.map_reduce(%{}, fn header, acc ->
-        # TODO Duplicates some of the logic of link_headings/3
-        case Map.fetch(acc, header.id) do
-          {:ok, id} ->
-            {%{header | anchor: "module-#{header.anchor}-#{id}"}, Map.put(acc, header.id, id + 1)}
-
-          :error ->
-            {%{header | anchor: "module-#{header.anchor}"}, Map.put(acc, header.id, 1)}
-        end
-      end)
 
     [sections: sections]
   end
 
   defp headers_to_id_and_anchors(headers) do
-    Enum.map(headers, fn text ->
-      %{id: text, anchor: URI.encode(text_to_id(text))}
+    Enum.map(headers, fn {:h2, text, anchor} ->
+      %{id: text, anchor: anchor}
     end)
   end
 

lib/ex_doc/retriever.ex

@@ -135,7 +135,8 @@ defmodule ExDoc.Retriever do
       relative_path: path_relative_to_cwd(module_data.source_file)
     }
 
-    {doc_line, doc_file, format, source_doc, doc, metadata} = get_module_docs(module_data, source)
+    {doc_line, doc_file, format, source_doc, doc_ast, metadata} =
+      get_module_docs(module_data, source)
 
     group_for_doc = config.group_for_doc
     annotations_for_docs = config.annotations_for_docs
@@ -157,7 +158,7 @@ defmodule ExDoc.Retriever do
       docs_groups: config.docs_groups ++ module_data.default_groups,
       docs: ExDoc.Utils.natural_sort_by(docs, &"#{&1.name}/#{&1.arity}"),
       doc_format: format,
-      doc: doc,
+      doc: normalize_doc_ast(doc_ast, "module-"),
       source_doc: source_doc,
       moduledoc_line: doc_line,
       moduledoc_file: doc_file,
@@ -176,6 +177,12 @@ defmodule ExDoc.Retriever do
     nil
   end
 
+  # TODO: Consider perhaps moving auto-linking here.
+  defp normalize_doc_ast(doc_ast, prefix) do
+    doc_ast
+    |> DocAST.add_ids_to_headers([:h2, :h3], prefix)
+  end
+
   # Helpers
 
   defp get_module_docs(module_data, source) do
@@ -219,17 +226,18 @@ defmodule ExDoc.Retriever do
     defaults = get_defaults(name, arity, Map.get(metadata, :defaults, 0))
 
     doc_ast =
-      (source_doc && doc_ast(content_type, source_doc, file: doc_file, line: doc_line + 1)) ||
+      doc_ast(content_type, source_doc, file: doc_file, line: doc_line + 1) ||
         doc_data.doc_fallback.()
 
     group = group_for_doc.(metadata) || doc_data.default_group
+    id = doc_data.id_key <> nil_or_name(name, arity)
 
     %ExDoc.DocNode{
-      id: doc_data.id_key <> nil_or_name(name, arity),
+      id: id,
       name: name,
       arity: arity,
       deprecated: metadata[:deprecated],
-      doc: doc_ast,
+      doc: normalize_doc_ast(doc_ast, id <> "-"),
       source_doc: source_doc,
       doc_line: doc_line,
       doc_file: doc_file,