refactor: update Markdown formatting for module and function headers

Author: yordis

lib/ex_doc/formatter/markdown.ex

@@ -157,7 +157,7 @@ defmodule ExDoc.Formatter.Markdown do
     modules_info =
       nodes_map.modules
       |> Enum.map(fn module_node ->
-        "- **#{module_node.title}** (#{module_node.id}.md): #{module_node.doc |> ExDoc.DocAST.synopsis() |> extract_plain_text()}"
+        "- [#{module_node.title}](#{module_node.id}.md): #{module_node.doc |> ExDoc.DocAST.synopsis() |> extract_plain_text()}"
       end)
       |> Enum.join("\n")
 
@@ -166,7 +166,7 @@ defmodule ExDoc.Formatter.Markdown do
         tasks_list =
           nodes_map.tasks
           |> Enum.map(fn task_node ->
-            "- **#{task_node.title}** (#{task_node.id}.md): #{task_node.doc |> ExDoc.DocAST.synopsis() |> extract_plain_text()}"
+            "- [#{task_node.title}](#{task_node.id}.md): #{task_node.doc |> ExDoc.DocAST.synopsis() |> extract_plain_text()}"
           end)
           |> Enum.join("\n")
 
@@ -184,7 +184,7 @@ defmodule ExDoc.Formatter.Markdown do
             _ -> []
           end)
           |> Enum.map(fn extra ->
-            "- **#{extra.title}** (#{extra.id}.md): #{extra.title}"
+            "- [#{extra.title}](#{extra.id}.md)"
           end)
           |> Enum.join("\n")
 

lib/ex_doc/formatter/markdown/templates.ex

@@ -4,27 +4,20 @@ defmodule ExDoc.Formatter.Markdown.Templates do
   require EEx
 
   import ExDoc.Utils,
-    only: [before_closing_body_tag: 2, h: 1, text_to_id: 1]
+    only: [before_closing_body_tag: 2, h: 1]
 
   @doc """
   Generate content from the module template for a given `node`.
   """
   def module_page(config, module_node) do
-    summary =
+    docs =
       for group <- module_node.docs_groups do
         {group.title, group.docs}
       end
 
-    module_template(config, module_node, summary)
+    module_template(config, module_node, docs)
   end
 
-  @doc """
-  Returns the formatted title for the module page.
-  """
-  def module_type(%{type: :task} = _node), do: ""
-  def module_type(%{type: :module} = _node), do: ""
-  def module_type(%{type: type} = _node), do: "(#{type})"
-
   @doc """
   Formats the attribute type used to define the spec of the given `node`.
   """
@@ -33,161 +26,19 @@ defmodule ExDoc.Formatter.Markdown.Templates do
   end
 
   @doc """
-  Generates an ID for a static file.
+  Returns the original markdown documentation from source_doc.
   """
-  def static_file_to_id(static_file) do
-    static_file |> Path.basename() |> text_to_id()
-  end
-
-  def node_doc(%{doc: doc}) when is_list(doc) do
-    # Handle DocAST by converting to Markdown.
-    ExDoc.DocAST.to_markdown(doc)
-  end
-
-  def node_doc(%{doc: doc}) when is_binary(doc), do: doc
   def node_doc(%{source_doc: %{"en" => source}}) when is_binary(source), do: source
-  def node_doc(%{rendered_doc: source}) when is_binary(source), do: source
-
-  def node_doc(%{source_doc: %{"en" => source}}) when is_list(source) do
-    # Handle DocAST by converting to Markdown.
-    # For Erlang docs, we can extract the text content.
-    extract_text_from_doc_ast(source)
-  end
-
   def node_doc(_), do: nil
 
-  @doc """
-  Get synopsis for a node, handling both DocAST and string documentation.
-  """
-  def node_synopsis(%{doc: doc}) when is_list(doc) do
-    # For DocAST, extract synopsis DocAST and convert to Markdown.
-    case extract_synopsis_ast(doc) do
-      nil -> nil
-      synopsis_ast -> ExDoc.DocAST.to_markdown(synopsis_ast)
-    end
-  end
-
-  def node_synopsis(%{doc: doc}) when is_binary(doc) do
-    synopsis(doc)
-  end
-
-  def node_synopsis(%{source_doc: %{"en" => source}}) when is_binary(source) do
-    synopsis(source)
-  end
-
-  def node_synopsis(%{rendered_doc: source}) when is_binary(source) do
-    synopsis(source)
-  end
-
-  def node_synopsis(%{source_doc: %{"en" => source}}) when is_list(source) do
-    case extract_synopsis_ast(source) do
-      nil -> nil
-      synopsis_ast -> synopsis_ast |> ExDoc.DocAST.to_markdown() |> extract_plain_text()
-    end
-  end
-
-  def node_synopsis(_), do: nil
-
-  # Extract synopsis as DocAST (similar to ExDoc.DocAST.synopsis but returns an AST instead of an HTML string).
-  defp extract_synopsis_ast({:p, _attrs, [_ | _] = inner, _meta}) do
-    inner =
-      case Enum.split(inner, -1) do
-        {pre, [post]} when is_binary(post) ->
-          pre ++ [String.trim_trailing(post, ":")]
-
-        _ ->
-          inner
-      end
-
-    {:p, [], ExDoc.DocAST.remove_ids(inner), %{}}
-  end
-
-  defp extract_synopsis_ast([head | _]), do: extract_synopsis_ast(head)
-  defp extract_synopsis_ast(_other), do: nil
-
-  defp extract_text_from_doc_ast(ast) when is_list(ast) do
-    Enum.map_join(ast, "\n\n", &extract_text_from_doc_ast/1)
-  end
-
-  defp extract_text_from_doc_ast({_tag, _attrs, content}) when is_list(content) do
-    Enum.map_join(content, "", &extract_text_from_doc_ast/1)
-  end
-
-  defp extract_text_from_doc_ast({_tag, _attrs, content, _meta}) when is_list(content) do
-    Enum.map_join(content, "", &extract_text_from_doc_ast/1)
-  end
-
-  defp extract_text_from_doc_ast(text) when is_binary(text), do: text
-  defp extract_text_from_doc_ast(_), do: ""
-
-  # Extract plain text from markdown (similar to the one in markdown.ex but here for templates)
-  defp extract_plain_text(markdown) when is_binary(markdown) do
-    markdown
-    |> String.replace(~r/<[^>]*>/, "")
-    |> String.replace(~r/\s+/, " ")
-    |> String.trim()
-    |> case do
-      "" ->
-        nil
-
-      text ->
-        text
-        |> String.slice(0, 150)
-        |> then(fn s -> if String.length(s) == 150, do: s <> "...", else: s end)
-    end
-  end
-
-  defp extract_plain_text(_), do: nil
-
-  @doc """
-  Gets the first paragraph of the documentation of a node. It strips
-  surrounding white-spaces and trailing `:`.
-
-  If `doc` is `nil`, it returns `nil`.
-  """
-  @spec synopsis(String.t()) :: String.t()
-  @spec synopsis(nil) :: nil
-  def synopsis(doc) when is_binary(doc) do
-    case :binary.split(doc, "\n\n") do
-      [left, _] -> (String.trim_trailing(left) |> String.trim_trailing(":")) <> "\n\n"
-      [all] -> all
-    end
-  end
-
-  def synopsis(_), do: nil
-
-  defp rewrite_headings(content) when is_binary(content) do
-    ~r/^(\#{1,6})\s+(.*)/m
-    |> Regex.scan(content)
-    |> Enum.reduce(content, fn [match, level, title], content ->
-      replacement = rewrite_heading(level, title)
-      String.replace(content, match, replacement, global: false)
-    end)
-  end
-
-  defp rewrite_headings(_), do: nil
-
-  defp rewrite_heading("#", title), do: do_rewrite_heading("#####", title)
-  defp rewrite_heading(_, title), do: do_rewrite_heading("######", title)
-
-  defp do_rewrite_heading(level, title) do
-    """
-    #{level} #{title}
-    """
-  end
-
-  defp enc(binary), do: URI.encode(binary) |> String.replace("/", "-")
-
   @doc """
   Creates a chapter which contains all the details about an individual module.
-
-  This chapter can include the following sections: *functions*, *types*, *callbacks*.
   """
   EEx.function_from_file(
     :def,
     :module_template,
     Path.expand("templates/module_template.eex", __DIR__),
-    [:config, :module, :summary],
+    [:config, :module, :docs],
     trim: true
   )
 
@@ -218,24 +69,12 @@ defmodule ExDoc.Formatter.Markdown.Templates do
     trim: true
   )
 
-  # EEx.function_from_file(
-  #   :defp,
-  #   :toc_item_template,
-  #   Path.expand("templates/toc_item_template.eex", __DIR__),
-  #   [:nodes],
-  #   trim: true
-  # )
-
-  # def media_type(_arg), do: nil
-
-  templates = [
-    detail_template: [:node, :module],
-    summary_template: [:name, :nodes]
-  ]
-
-  Enum.each(templates, fn {name, args} ->
-    filename = Path.expand("templates/#{name}.eex", __DIR__)
-    @doc false
-    EEx.function_from_file(:def, name, filename, args, trim: true)
-  end)
+  @doc false
+  EEx.function_from_file(
+    :def,
+    :detail_template,
+    Path.expand("templates/detail_template.eex", __DIR__),
+    [:node, :module],
+    trim: true
+  )
 end

lib/ex_doc/formatter/markdown/templates/detail_template.eex

@@ -1,9 +1,9 @@
-<a id="<%= enc node.id %>"></a>
-#### `<%=h node.signature %>` <%= if node.source_url do %>[🔗](<%= node.source_url %>)<% end %> <%= for annotation <- node.annotations do %>(<%= annotation %>) <% end %>
+# `<%= node.name %>`
+<%= if node.source_url do %>[🔗](<%= node.source_url %>)<% end %>
 
+<%= for annotation <- node.annotations do %>*<%= annotation %>* <% end %>
 <%= if deprecated = node.deprecated do %>
 > This <%= node.type %> is deprecated. <%= h(deprecated) %>.
-
 <% end %>
 <%= if node.specs != [] do %>
 <%= for spec <- node.specs do %>
@@ -12,6 +12,4 @@
 ```
 <% end %>
 <% end %>
-
-<%= rewrite_headings(node_doc(node)) %>
-
+<%= node_doc(node) %>

lib/ex_doc/formatter/markdown/templates/module_template.eex

@@ -1,35 +1,14 @@
-# <%= module.title %> <%= module_type(module) %> (<%= config.project %> v<%= config.version %>)
-
-<%= for annotation <- module.annotations do %>*(<%= annotation %>)* <% end %>
+# `<%=h module.title %>`
+<%= if module.source_url do %>[🔗](<%= module.source_url %>)<% end %>
 
+<%= for annotation <- module.annotations do %>*<%= annotation %>* <% end %>
 <%= if deprecated = module.deprecated do %>
 > This <%= module.type %> is deprecated. <%=h deprecated %>.
-
 <% end %>
-<%= if doc = node_doc(module) do %>
-<%= doc %>
-<% end %>
-
-<%= if summary != [] do %>
-## Table of Contents
-<%= for {name, nodes} <- summary, do: summary_template(name, nodes) %>
-<% end %>
-
-## Contents
-
-<%= for {name, nodes} <- summary, _key = text_to_id(name) do %>
-### <%=h to_string(name) %>
-
+<%= node_doc(module) %>
+<%= for {_name, nodes} <- docs do %>
 <%= for node <- nodes do %>
 <%= detail_template(node, module) %>
 <% end %>
-
-<% end %>
-
----
-
-<%= if module.source_url do %>
-[<%= String.capitalize(to_string(module.type)) %> Source Code](<%= module.source_url %>)
 <% end %>
-
 <%= before_closing_body_tag(config, :markdown) %>

lib/ex_doc/formatter/markdown/templates/summary_template.eex

@@ -334,18 +334,21 @@ defmodule ExDoc.DocASTTest do
 
   describe "highlight" do
     test "with default class" do
+      # Four spaces
       assert highlight("""
                  mix run --no-halt path/to/file.exs
              """) =~
                ~r{<pre><code class=\"makeup elixir\" translate="no">.*}
 
+      # Code block without language
       assert highlight("""
              ```
              mix run --no-halt path/to/file.exs</code></pre>
              ```
              """) =~
                ~r{<pre><code class=\"makeup elixir\" translate="no">.*}
 
+      # Pre IAL
       assert highlight("""
              ```
              mix run --no-halt path/to/file.exs</code></pre>
@@ -354,20 +357,23 @@ defmodule ExDoc.DocASTTest do
              """) =~
                ~r{<pre class="wrap"><code class=\"makeup elixir\" translate="no">.*}
 
+      # Code with language
       assert highlight("""
              ```html
              <foo />
              ```
              """) =~
                ~r{<pre><code class=\"makeup html\" translate="no">.*}
 
+      # Code with shell detection
       assert highlight("""
              ```
              $ hello
              ```
              """) =~
                ~r{<pre><code class=\"makeup shell\" translate="no"><span class="gp unselectable">\$.*}
 
+      # Nested in another element
       assert highlight("""
              > ```elixir
              > hello