Convert link headings into DocAST traversals

josevalim · josevalim · commit 3efa2d70f267 · 2025-05-08T14:06:09.000+02:00
diff --git a/assets/css/content/general.css b/assets/css/content/general.css
@@ -205,9 +205,10 @@
 .content-inner .section-heading i {
   font-size: var(--icon-size);
   color: var(--mainLight);
-  margin-top: 0.1em;
+  top: -2px;
   margin-left: calc(-1 * (var(--icon-size) + var(--icon-spacing)));
   padding-right: var(--icon-spacing);
+  position: relative;
   opacity: 0;
 }
 
diff --git a/formatters/html/dist/html-elixir-J3PIVQVA.css b/formatters/html/dist/html-elixir-J3PIVQVA.css
diff --git a/formatters/html/dist/html-elixir-M6JNNWMH.css b/formatters/html/dist/html-elixir-M6JNNWMH.css
diff --git a/formatters/html/dist/html-erlang-5OIFJN4X.css b/formatters/html/dist/html-erlang-5OIFJN4X.css
diff --git a/formatters/html/dist/html-erlang-ZK43ZOAC.css b/formatters/html/dist/html-erlang-ZK43ZOAC.css
diff --git a/lib/ex_doc/formatter/epub.ex b/lib/ex_doc/formatter/epub.ex
@@ -62,12 +62,10 @@ defmodule ExDoc.Formatter.EPUB do
 
   defp generate_extras(config) do
     for {_title, extras} <- config.extras,
-        extra_config <- extras,
-        not is_map_key(extra_config, :url) do
-      %{id: id, title: title, title_content: title_content, content: content} = extra_config
-
-      output = "#{config.output}/OEBPS/#{id}.xhtml"
-      html = Templates.extra_template(config, title, title_content, content)
+        node <- extras,
+        not is_map_key(node, :url) do
+      output = "#{config.output}/OEBPS/#{node.id}.xhtml"
+      html = Templates.extra_template(config, node)
 
       if File.regular?(output) do
         Utils.warn("file #{Path.relative_to_cwd(output)} already exists", [])
diff --git a/lib/ex_doc/formatter/epub/templates.ex b/lib/ex_doc/formatter/epub/templates.ex
@@ -9,6 +9,9 @@ defmodule ExDoc.Formatter.EPUB.Templates do
   alias ExDoc.Formatter.HTML.Templates, as: H
   alias ExDoc.Formatter.EPUB.Assets
 
+  # The actual rendering happens here
+  defp render_doc(ast), do: ast && ExDoc.DocAST.to_string(ast)
+
   @doc """
   Generate content from the module template for a given `node`
   """
@@ -76,7 +79,7 @@ defmodule ExDoc.Formatter.EPUB.Templates do
     :def,
     :extra_template,
     Path.expand("templates/extra_template.eex", __DIR__),
-    [:config, :title, :title_content, :content],
+    [:config, :node],
     trim: true
   )
 
diff --git a/lib/ex_doc/formatter/epub/templates/extra_template.eex b/lib/ex_doc/formatter/epub/templates/extra_template.eex
@@ -1,8 +1,8 @@
-<%= head_template(config, title) %>
+<%= head_template(config, node.title) %>
     <h1 id="content">
-      <%=h title_content %>
+      <%=h node.title_content %>
     </h1>
-    <%= H.link_headings(content) %>
+    <%= render_doc(node.doc) %>
     <%= before_closing_body_tag(config, :epub) %>
   </body>
 </html>
diff --git a/lib/ex_doc/formatter/epub/templates/module_template.eex b/lib/ex_doc/formatter/epub/templates/module_template.eex
@@ -9,9 +9,9 @@
       </div>
     <% end %>
 
-    <%= if doc = module.rendered_doc do %>
+    <%= if doc = module.doc do %>
       <section id="moduledoc" class="docstring">
-        <%= H.link_moduledoc_headings(doc) %>
+        <%= render_doc(doc) %>
       </section>
     <% end %>
 
diff --git a/lib/ex_doc/formatter/html.ex b/lib/ex_doc/formatter/html.ex
@@ -32,6 +32,7 @@ defmodule ExDoc.Formatter.HTML do
       tasks: filter_list(:task, project_nodes)
     }
 
+    # TODO: api reference should not be treated as an extra
     extras =
       if config.api_reference do
         [build_api_reference(nodes_map, config) | extras]
@@ -125,8 +126,8 @@ defmodule ExDoc.Formatter.HTML do
     do: node
 
   defp render_doc(%{doc: doc} = node, language, autolink_opts, opts) do
-    rendered = autolink_and_render(doc, language, autolink_opts, opts)
-    %{node | rendered_doc: rendered}
+    doc = autolink_and_highlight(doc, language, autolink_opts, opts)
+    %{node | doc: doc, rendered_doc: ExDoc.DocAST.to_string(doc)}
   end
 
   defp id(%{id: mod_id}, %{id: "c:" <> id}) do
@@ -141,11 +142,10 @@ defmodule ExDoc.Formatter.HTML do
     mod_id <> "." <> id
   end
 
-  defp autolink_and_render(doc, language, autolink_opts, opts) do
+  defp autolink_and_highlight(doc, language, autolink_opts, opts) do
     doc
     |> language.autolink_doc(autolink_opts)
     |> ExDoc.DocAST.highlight(language, opts)
-    |> ExDoc.DocAST.to_string()
   end
 
   defp output_setup(build, config) do
@@ -314,13 +314,13 @@ defmodule ExDoc.Formatter.HTML do
       ~s{API Reference <small class="app-vsn">#{config.project} v#{config.version}</small>}
 
     %{
-      content: api_reference,
       group: nil,
       id: "api-reference",
       source_path: nil,
       source_url: config.source_url,
       title: "API Reference",
       title_content: title_content,
+      content: api_reference,
       headers:
         if(nodes_map.modules != [], do: [{:h2, "Modules", "modules"}], else: []) ++
           if(nodes_map.tasks != [], do: [{:h2, "Mix Tasks", "mix-tasks"}], else: [])
@@ -425,6 +425,7 @@ defmodule ExDoc.Formatter.HTML do
             |> Markdown.to_ast(opts)
             |> ExDoc.DocAST.add_ids_to_headers([:h2, :h3])
             |> sectionize(extension)
+            |> autolink_and_highlight(language, [file: input] ++ autolink_opts, opts)
 
           {source, ast}
 
@@ -441,7 +442,6 @@ defmodule ExDoc.Formatter.HTML do
 
     title_text = title_ast && ExDoc.DocAST.text(title_ast)
     title_html = title_ast && ExDoc.DocAST.to_string(title_ast)
-    content_html = autolink_and_render(ast, language, [file: input] ++ autolink_opts, opts)
 
     group = GroupMatcher.match_extra(groups, input)
     title = input_options[:title] || title_text || filename_to_title(input)
@@ -454,13 +454,13 @@ defmodule ExDoc.Formatter.HTML do
       source: source,
       group: group,
       id: id,
+      doc: ast,
       source_path: source_path,
       source_url: source_url,
       search_data: search_data,
       title: title,
       title_content: title_html || title,
-      # TODO: Remove these fields but first we would need to make API reference return DocAST
-      content: content_html,
+      # Remove this field when API reference is no longer treated as an extra
       headers: ExDoc.DocAST.extract_headers_with_ids(ast, [:h2])
     }
   end
diff --git a/lib/ex_doc/formatter/html/templates.ex b/lib/ex_doc/formatter/html/templates.ex
@@ -172,94 +172,49 @@ defmodule ExDoc.Formatter.HTML.Templates do
   defp sidebar_type(:livemd), do: "extras"
   defp sidebar_type(:extra), do: "extras"
 
-  # TODO: Adding the link headings must be done via DocAST instead of using regexes.
+  @section_header_class_name "section-heading"
 
   @doc """
-  Add link headings for the given `content`.
+  Renders the document in the page.
 
-  IDs are prefixed with `prefix`.
-
-  We only link `h2` and `h3` headers. This is kept consistent in ExDoc.SearchData.
+  For now it enriches the document by adding fancy anchors
+  around h2 and h3 tags with IDs.
   """
-  @spec link_headings(String.t() | nil, String.t()) :: String.t() | nil
-  def link_headings(content, prefix \\ "")
-  def link_headings(nil, _), do: nil
-
-  def link_headings(content, prefix) do
-    ~r/<(h[23]).*?>(.*?)<\/\1>/m
-    |> Regex.scan(content)
-    |> Enum.reduce({content, %{}}, fn [match, tag, title], {content, occurrences} ->
-      possible_id = title |> ExDoc.Utils.strip_tags() |> text_to_id()
-      id_occurred = Map.get(occurrences, possible_id, 0)
-
-      anchor_id = if id_occurred >= 1, do: "#{possible_id}-#{id_occurred}", else: possible_id
-      replacement = link_heading(match, tag, title, anchor_id, prefix)
-      linked_content = String.replace(content, match, replacement, global: false)
-      incremented_occs = Map.put(occurrences, possible_id, id_occurred + 1)
-      {linked_content, incremented_occs}
-    end)
-    |> elem(0)
-  end
-
-  @class_separator " "
-  defp link_heading(match, _tag, _title, "", _prefix), do: match
-
-  defp link_heading(match, tag, title, id, prefix) do
-    section_header_class_name = "section-heading"
-
-    # NOTE: This addition is mainly to preserve the previous `class` attributes
-    # from the headers, in case there is one. Now with the _admonition_ text
-    # block, we inject CSS classes. So far, the supported classes are:
-    # `warning`, `info`, `error`, and `neutral`.
-    #
-    # The Markdown syntax that we support for the admonition text
-    # blocks is something like this:
-    #
-    #     > ### Never open this door! {: .warning}
-    #     >
-    #     > ...
-    #
-    # That should produce the following HTML:
-    #
-    #      <blockquote>
-    #        <h3 class="warning">Never open this door!</h3>
-    #        <p>...</p>
-    #      </blockquote>
-    #
-    # The original implementation discarded the previous CSS classes. Instead,
-    # it was setting `#{section_header_class_name}` as the only CSS class
-    # associated with the given header.
-    class_attribute =
-      case Regex.named_captures(~r/<h[23].*?(\sclass="(?<class>[^"]+)")?.*?>/, match) do
-        %{"class" => ""} ->
-          section_header_class_name
-
-        %{"class" => previous_classes} ->
-          # Let's make sure that the `section_header_class_name` is not already
-          # included in the previous classes for the header
-          previous_classes
-          |> String.split(@class_separator)
-          |> Enum.reject(&(&1 == section_header_class_name))
-          |> Enum.join(@class_separator)
-          |> Kernel.<>(" #{section_header_class_name}")
-      end
-
-    """
-    <#{tag} id="#{prefix}#{id}" class="#{class_attribute}">
-      <a href="##{prefix}#{id}" class="hover-link">
-        <i class="ri-link-m" aria-hidden="true"></i>
-      </a>
-      <span class="text">#{title}</span>
-    </#{tag}>
-    """
-  end
+  def render_doc(nil), do: ""
 
-  def link_moduledoc_headings(content) do
-    link_headings(content, "module-")
+  def render_doc(ast) do
+    ast
+    |> add_fancy_anchors()
+    |> ExDoc.DocAST.to_string()
   end
 
-  def link_detail_headings(content, prefix) do
-    link_headings(content, prefix <> "-")
+  defp add_fancy_anchors(ast) do
+    ExDoc.DocAST.map_tags(ast, fn
+      {tag, attrs, inner, meta} = ast when tag in [:h2, :h3] ->
+        if id = Keyword.get(attrs, :id) do
+          attrs =
+            Keyword.update(
+              attrs,
+              :class,
+              @section_header_class_name,
+              &(&1 <> " " <> @section_header_class_name)
+            )
+
+          {tag, attrs,
+           [
+             {:a, [href: "##{id}", class: "hover-link"],
+              [
+                {:i, [class: "ri-link-m", "aria-hidden": "true"], [], %{}}
+              ], %{}},
+             {:span, [class: "text"], inner, %{}}
+           ], meta}
+        else
+          ast
+        end
+
+      ast ->
+        ast
+    end)
   end
 
   templates = [
diff --git a/lib/ex_doc/formatter/html/templates/detail_template.eex b/lib/ex_doc/formatter/html/templates/detail_template.eex
@@ -33,6 +33,6 @@
       </div>
     <% end %>
 
-    <%= link_detail_headings(node.rendered_doc, enc(node.id)) %>
+    <%= render_doc(node.doc) %>
   </section>
 </section>
diff --git a/lib/ex_doc/formatter/html/templates/extra_template.eex b/lib/ex_doc/formatter/html/templates/extra_template.eex
@@ -26,7 +26,7 @@
     </div>
   <% end %>
 
-  <%= link_headings(node.content) %>
+  <%= node[:content] || render_doc(node.doc) %>
 </div>
 
 <div class="bottom-actions" id="bottom-actions">
diff --git a/lib/ex_doc/formatter/html/templates/module_template.eex b/lib/ex_doc/formatter/html/templates/module_template.eex
@@ -24,9 +24,9 @@
     </div>
   <% end %>
 
-  <%= if doc = module.rendered_doc do %>
+  <%= if doc = module.doc do %>
     <section id="moduledoc">
-      <%= link_moduledoc_headings(doc) %>
+      <%= render_doc(doc) %>
     </section>
   <% end %>
 </div>
diff --git a/lib/ex_doc/retriever.ex b/lib/ex_doc/retriever.ex
@@ -177,7 +177,7 @@ defmodule ExDoc.Retriever do
     nil
   end
 
-  # TODO: Consider perhaps moving auto-linking here.
+  # TODO: Consider moving auto-linking here.
   defp normalize_doc_ast(doc_ast, prefix) do
     doc_ast
     |> DocAST.add_ids_to_headers([:h2, :h3], prefix)
diff --git a/test/ex_doc/formatter/epub/templates_test.exs b/test/ex_doc/formatter/epub/templates_test.exs
@@ -108,10 +108,10 @@ defmodule ExDoc.Formatter.EPUB.TemplatesTest do
       assert content =~ ~s{<h1 class="section-heading">Summary</h1>}
 
       assert content =~
-               ~r{<h2 id="module-example-unicode-escaping" class="section-heading">.*Example.*</h2>}ms
+               ~r{<h2 id="module-example-unicode-escaping">.*Example.*</h2>}ms
 
       assert content =~
-               ~r{<h3 id="module-example-h3-heading" class="section-heading">.*Example H3 heading.*</h3>}ms
+               ~r{<h3 id="module-example-h3-heading">.*Example H3 heading.*</h3>}ms
 
       assert content =~
                ~r{moduledoc.*Example.*<samp class="nc">CompiledWithDocs</samp><samp class="o">\.</samp><samp class="n">example</samp>.*}ms
diff --git a/test/ex_doc/formatter/html/templates_test.exs b/test/ex_doc/formatter/html/templates_test.exs
