From 8bd3cbae6fde8c7f6ce43861ab6491f25de97c93 Mon Sep 17 00:00:00 2001
From: Mayel de Borniol <git@mayel.space>
Date: Sun, 8 Dec 2024 10:39:18 +0000
Subject: [PATCH 01/10] add markdown formatter / exporter

---
 lib/ex_doc/cli.ex                             |   2 +-
 lib/ex_doc/formatter/html/templates.ex        |   5 +-
 lib/ex_doc/formatter/markdown.ex              | 126 +++++++++++
 lib/ex_doc/formatter/markdown/assets.ex       |  17 ++
 lib/ex_doc/formatter/markdown/templates.ex    | 197 ++++++++++++++++++
 .../markdown/templates/detail_template.eex    |  21 ++
 .../markdown/templates/module_template.eex    |  20 ++
 .../markdown/templates/summary_template.eex   |  13 ++
 8 files changed, 399 insertions(+), 2 deletions(-)
 create mode 100644 lib/ex_doc/formatter/markdown.ex
 create mode 100644 lib/ex_doc/formatter/markdown/assets.ex
 create mode 100644 lib/ex_doc/formatter/markdown/templates.ex
 create mode 100644 lib/ex_doc/formatter/markdown/templates/detail_template.eex
 create mode 100644 lib/ex_doc/formatter/markdown/templates/module_template.eex
 create mode 100644 lib/ex_doc/formatter/markdown/templates/summary_template.eex

diff --git a/lib/ex_doc/cli.ex b/lib/ex_doc/cli.ex
index 91403ff30..bace964f7 100644
--- a/lib/ex_doc/cli.ex
+++ b/lib/ex_doc/cli.ex
@@ -103,7 +103,7 @@ defmodule ExDoc.CLI do
   defp normalize_formatters(opts) do
     formatters =
       case Keyword.get_values(opts, :formatter) do
-        [] -> opts[:formatters] || ["html", "epub"]
+        [] -> opts[:formatters] || ["html", "epub", "markdown"]
         values -> values
       end
 
diff --git a/lib/ex_doc/formatter/html/templates.ex b/lib/ex_doc/formatter/html/templates.ex
index 72407b672..435360578 100644
--- a/lib/ex_doc/formatter/html/templates.ex
+++ b/lib/ex_doc/formatter/html/templates.ex
@@ -64,7 +64,10 @@ defmodule ExDoc.Formatter.HTML.Templates do
     Regex.replace(~r|(<[^>]*) id="[^"]*"([^>]*>)|, doc, ~S"\1\2", [])
   end
 
-  defp enc(binary), do: URI.encode(binary)
+  defp presence([]), do: nil
+  defp presence(other), do: other
+
+  def enc(binary), do: URI.encode(binary)
 
   @doc """
   Create a JS object which holds all the items displayed in the sidebar area
diff --git a/lib/ex_doc/formatter/markdown.ex b/lib/ex_doc/formatter/markdown.ex
new file mode 100644
index 000000000..381b42041
--- /dev/null
+++ b/lib/ex_doc/formatter/markdown.ex
@@ -0,0 +1,126 @@
+defmodule ExDoc.Formatter.Markdown do
+  @moduledoc false
+
+  @mimetype "text/markdown"
+  @assets_dir "MD/assets"
+  alias __MODULE__.{Assets, Templates}
+  alias ExDoc.Formatter.HTML
+  alias ExDoc.Utils
+
+  @doc """
+  Generates Markdown documentation for the given modules.
+  """
+  @spec run([ExDoc.ModuleNode.t()], [ExDoc.ModuleNode.t()], ExDoc.Config.t()) :: String.t()
+  def run(project_nodes, filtered_modules, config) when is_map(config) do
+    Utils.unset_warned()
+
+    config = normalize_config(config)
+    File.rm_rf!(config.output)
+    File.mkdir_p!(Path.join(config.output, "MD"))
+
+    project_nodes =
+      HTML.render_all(project_nodes, filtered_modules, ".md", config, highlight_tag: "samp")
+
+    nodes_map = %{
+      modules: HTML.filter_list(:module, project_nodes),
+      tasks: HTML.filter_list(:task, project_nodes)
+    }
+
+    extras =
+      config
+      |> HTML.build_extras(".xhtml")
+      |> Enum.chunk_by(& &1.group)
+      |> Enum.map(&{hd(&1).group, &1})
+
+    config = %{config | extras: extras}
+
+    static_files = HTML.generate_assets("MD", default_assets(config), config)
+    HTML.generate_logo(@assets_dir, config)
+    HTML.generate_cover(@assets_dir, config)
+
+    # generate_nav(config, nodes_map)
+    generate_extras(config)
+    generate_list(config, nodes_map.modules)
+    generate_list(config, nodes_map.tasks)
+
+    {:ok, epub} = generate_zip(config.output)
+    File.rm_rf!(config.output)
+    Path.relative_to_cwd(epub)
+  end
+
+  defp normalize_config(config) do
+    output =
+      config.output
+      |> Path.expand()
+      |> Path.join("#{config.project}")
+
+    %{config | output: output}
+  end
+
+  defp generate_extras(config) do
+    for {_title, extras} <- config.extras do
+      Enum.each(extras, fn %{id: id, title: title, title_content: _title_content, source: content} ->
+        output = "#{config.output}/MD/#{id}.md"
+        content = """
+        # #{title}
+
+        #{content}
+        """
+
+        if File.regular?(output) do
+          Utils.warn("file #{Path.relative_to_cwd(output)} already exists", [])
+        end
+
+        File.write!(output, content)
+      end)
+    end
+  end
+
+
+
+
+  defp generate_list(config, nodes) do
+    nodes
+    |> Task.async_stream(&generate_module_page(&1, config), timeout: :infinity)
+    |> Enum.map(&elem(&1, 1))
+  end
+
+  defp generate_zip(output) do
+    :zip.create(
+      String.to_charlist("#{output}-markdown.zip"),
+      files_to_add(output),
+      compress: [
+        ~c".md",
+        ~c".jpg",
+        ~c".png"
+      ]
+    )
+  end
+
+  ## Helpers
+
+  defp default_assets(config) do
+    [
+      {Assets.dist(config.proglang), "MD/dist"},
+      {Assets.metainfo(), "META-INF"}
+    ]
+  end
+
+  defp files_to_add(path) do
+    Enum.reduce(Path.wildcard(Path.join(path, "**/*")), [], fn file, acc ->
+      case File.read(file) do
+        {:ok, bin} ->
+          [{file |> Path.relative_to(path) |> String.to_charlist(), bin} | acc]
+
+        {:error, _} ->
+          acc
+      end
+    end)
+  end
+
+  defp generate_module_page(module_node, config) do
+    content = Templates.module_page(config, module_node)
+    File.write("#{config.output}/MD/#{module_node.id}.md", content)
+  end
+
+end
diff --git a/lib/ex_doc/formatter/markdown/assets.ex b/lib/ex_doc/formatter/markdown/assets.ex
new file mode 100644
index 000000000..2a3041226
--- /dev/null
+++ b/lib/ex_doc/formatter/markdown/assets.ex
@@ -0,0 +1,17 @@
+defmodule ExDoc.Formatter.Markdown.Assets do
+  @moduledoc false
+
+  defmacrop embed_pattern(pattern) do
+    ["formatters/markdown", pattern]
+    |> Path.join()
+    |> Path.wildcard()
+    |> Enum.map(fn path ->
+      Module.put_attribute(__CALLER__.module, :external_resource, path)
+      {Path.basename(path), File.read!(path)}
+    end)
+  end
+
+  def dist(_proglang), do: []
+
+  def metainfo, do: embed_pattern("metainfo/*")
+end
diff --git a/lib/ex_doc/formatter/markdown/templates.ex b/lib/ex_doc/formatter/markdown/templates.ex
new file mode 100644
index 000000000..ab9c5b498
--- /dev/null
+++ b/lib/ex_doc/formatter/markdown/templates.ex
@@ -0,0 +1,197 @@
+defmodule ExDoc.Formatter.Markdown.Templates do
+  @moduledoc false
+
+  require EEx
+
+  import ExDoc.Utils,
+    only: [before_closing_body_tag: 2, before_closing_head_tag: 2, h: 1, text_to_id: 1]
+
+  alias ExDoc.Formatter.HTML.Templates, as: H
+
+  @doc """
+  Generate content from the module template for a given `node`
+  """
+  def module_page(config, module_node) do
+    summary = H.module_summary(module_node)
+    module_template(config, module_node, summary)
+  end
+
+  @doc """
+  Generated ID for static file
+  """
+  def static_file_to_id(static_file) do
+    static_file |> Path.basename() |> text_to_id()
+  end
+
+  def node_doc(%{source_doc: %{"en"=> source}}), do: source
+  def node_doc(%{rendered_doc: source}), do: source
+
+  @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(nil), do: nil
+
+  def synopsis(doc) when is_binary(doc) do
+    doc =
+      case :binary.split(doc, "</p>") do
+        [left, _] -> String.trim_trailing(left, ": ")
+        [all] -> all
+      end
+
+    # Remove any anchors found in synopsis.
+    # Old Erlang docs placed anchors at the top of the documentation
+    # for links. Ideally they would have been removed but meanwhile
+    # it is simpler to guarantee they won't be duplicated in docs.
+    Regex.replace(~r|(<[^>]*) id="[^"]*"([^>]*>)|, doc, ~S"\1\2", [])
+  end
+  
+    @doc """
+  Add link headings for the given `content`.
+
+  IDs are prefixed with `prefix`.
+
+  We only link `h2` and `h3` headers. This is kept consistent in ExDoc.SearchData.
+  """
+  @heading_regex ~r/<(h[23]).*?>(.*?)<\/\1>/m
+  @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
+    @heading_regex
+    |> Regex.scan(content)
+    |> Enum.reduce({content, %{}}, fn [match, tag, title], {content, occurrences} ->
+      possible_id = text_to_id(title)
+      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_regex ~r/<h[23].*?(\sclass="(?<class>[^"]+)")?.*?>/
+  @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"
+
+    # The Markdown syntax that we support for the admonition text
+    # blocks is something like this:
+    #
+    #     > ### Never open this door! {: .warning}
+    #     >
+    #     > ...
+    #
+
+    """
+    ## [#{title}](##{prefix}#{id})
+    """
+  end
+
+  def link_moduledoc_headings(content) do
+    link_headings(content, "module-")
+  end
+
+  def link_detail_headings(content, prefix) do
+    link_headings(content, prefix <> "-")
+  end
+
+  @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],
+    trim: true
+  )
+
+  # @doc """
+  # Creates the table of contents.
+
+  # This template follows the EPUB Navigation Document Definition.
+
+  # See http://www.idpf.org/epub/30/spec/epub30-contentdocs.html#sec-xhtml-nav.
+  # """
+  # EEx.function_from_file(
+  #   :def,
+  #   :nav_template,
+  #   Path.expand("templates/nav_template.eex", __DIR__),
+  #   [:config, :nodes],
+  #   trim: true
+  # )
+
+  # @doc """
+  # Creates a new chapter when the user provides additional files.
+  # """
+  # EEx.function_from_file(
+  #   :def,
+  #   :extra_template,
+  #   Path.expand("templates/extra_template.eex", __DIR__),
+  #   [:config, :title, :title_content, :content],
+  #   trim: true
+  # )
+
+
+  # EEx.function_from_file(
+  #   :defp,
+  #   :nav_item_template,
+  #   Path.expand("templates/nav_item_template.eex", __DIR__),
+  #   [:name, :nodes],
+  #   trim: true
+  # )
+
+  # EEx.function_from_file(
+  #   :defp,
+  #   :nav_grouped_item_template,
+  #   Path.expand("templates/nav_grouped_item_template.eex", __DIR__),
+  #   [:nodes],
+  #   trim: true
+  # )
+
+  # EEx.function_from_file(
+  #   :defp,
+  #   :toc_item_template,
+  #   Path.expand("templates/toc_item_template.eex", __DIR__),
+  #   [:nodes],
+  #   trim: true
+  # )
+
+  # "templates/media-types.txt"
+  # |> Path.expand(__DIR__)
+  # |> File.read!()
+  # |> String.split("\n", trim: true)
+  # |> Enum.each(fn line ->
+  #   [extension, media] = String.split(line, ",")
+
+  #   def media_type("." <> unquote(extension)) do
+  #     unquote(media)
+  #   end
+  # end)
+
+  # 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)
+end
diff --git a/lib/ex_doc/formatter/markdown/templates/detail_template.eex b/lib/ex_doc/formatter/markdown/templates/detail_template.eex
new file mode 100644
index 000000000..32fd172ea
--- /dev/null
+++ b/lib/ex_doc/formatter/markdown/templates/detail_template.eex
@@ -0,0 +1,21 @@
+# <%=h node.signature %>
+
+<%= if node.source_url do %>
+[View Source](<%= 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 specs = H.get_specs(node) do %>
+<%= for spec <- specs do %>
+> <%= H.format_spec_attribute(module, node) %> <%= spec %>
+<% end %>
+<% end %>
+
+<%= link_detail_headings(node_doc(node), H.enc(node.id)) %>
diff --git a/lib/ex_doc/formatter/markdown/templates/module_template.eex b/lib/ex_doc/formatter/markdown/templates/module_template.eex
new file mode 100644
index 000000000..750778cda
--- /dev/null
+++ b/lib/ex_doc/formatter/markdown/templates/module_template.eex
@@ -0,0 +1,20 @@
+# <%= module.title %> <%= H.module_type(module) %>
+
+<%= if deprecated = module.deprecated do %>
+> This <%= module.type %> is deprecated. <%=h deprecated %>.
+<% end %>
+
+<%= if doc = node_doc(module) do %>
+<%= H.link_moduledoc_headings(doc) %>
+<% end %>
+
+<%= if summary != [] do %>
+### Summary</h1>
+<%= for {name, nodes} <- summary, do: summary_template(name, nodes) %>
+<% end %>
+
+<%= for {name, nodes} <- summary, key = text_to_id(name) do %>
+## <%=h to_string(name) %>
+<%= for node <- nodes, do: detail_template(node, module) %>
+<% end %>
+<%= before_closing_body_tag(config, :markdown) %>
diff --git a/lib/ex_doc/formatter/markdown/templates/summary_template.eex b/lib/ex_doc/formatter/markdown/templates/summary_template.eex
new file mode 100644
index 000000000..52215651c
--- /dev/null
+++ b/lib/ex_doc/formatter/markdown/templates/summary_template.eex
@@ -0,0 +1,13 @@
+## <%= name %>
+<%= for node <- nodes do %>
+
+### <%=h node.signature %>
+
+<%= if deprecated = node.deprecated do %>
+> <%= h(deprecated) %>
+<% end %>
+
+<%= if doc = node_doc(node) do %>
+<%= synopsis(doc) %>
+<% end %>
+<% end %>

From d295d8e31ccf2f55faf3300d8b68d8a36c442786 Mon Sep 17 00:00:00 2001
From: Mayel de Borniol <git@mayel.space>
Date: Thu, 26 Dec 2024 15:05:36 +0000
Subject: [PATCH 02/10] WIP for https://github.com/elixir-lang/ex_doc/pull/1976

---
 lib/ex_doc.ex                                 |   1 +
 lib/ex_doc/cli.ex                             |   2 +-
 .../html/templates/footer_template.eex        |   6 +
 .../html/templates/module_template.eex        |   8 +
 lib/ex_doc/formatter/markdown.ex              |  49 +++--
 lib/ex_doc/formatter/markdown/assets.ex       |   2 +-
 lib/ex_doc/formatter/markdown/templates.ex    |  77 +++-----
 .../templates/nav_grouped_item_template.eex   |   8 +
 .../markdown/templates/nav_item_template.eex  |   6 +
 .../markdown/templates/nav_template.eex       |   9 +
 .../formatter/markdown/templates_test.exs     | 157 ++++++++++++++++
 test/ex_doc/formatter/markdown_test.exs       | 173 ++++++++++++++++++
 12 files changed, 425 insertions(+), 73 deletions(-)
 create mode 100644 lib/ex_doc/formatter/markdown/templates/nav_grouped_item_template.eex
 create mode 100644 lib/ex_doc/formatter/markdown/templates/nav_item_template.eex
 create mode 100644 lib/ex_doc/formatter/markdown/templates/nav_template.eex
 create mode 100644 test/ex_doc/formatter/markdown/templates_test.exs
 create mode 100644 test/ex_doc/formatter/markdown_test.exs

diff --git a/lib/ex_doc.ex b/lib/ex_doc.ex
index c108c3560..4fdf725a3 100644
--- a/lib/ex_doc.ex
+++ b/lib/ex_doc.ex
@@ -44,6 +44,7 @@ defmodule ExDoc do
     if Code.ensure_loaded?(modname) do
       modname
     else
+      IO.inspect(modname)
       raise "formatter module #{inspect(argname)} not found"
     end
   end
diff --git a/lib/ex_doc/cli.ex b/lib/ex_doc/cli.ex
index bace964f7..91403ff30 100644
--- a/lib/ex_doc/cli.ex
+++ b/lib/ex_doc/cli.ex
@@ -103,7 +103,7 @@ defmodule ExDoc.CLI do
   defp normalize_formatters(opts) do
     formatters =
       case Keyword.get_values(opts, :formatter) do
-        [] -> opts[:formatters] || ["html", "epub", "markdown"]
+        [] -> opts[:formatters] || ["html", "epub"]
         values -> values
       end
 
diff --git a/lib/ex_doc/formatter/html/templates/footer_template.eex b/lib/ex_doc/formatter/html/templates/footer_template.eex
index 5488a0212..2f0042019 100644
--- a/lib/ex_doc/formatter/html/templates/footer_template.eex
+++ b/lib/ex_doc/formatter/html/templates/footer_template.eex
@@ -22,6 +22,12 @@
               Download ePub version
             </a>
           <% end %>
+
+          <%= if "markdown" in config.formatters do %>
+            <a href="<%= config.project %>-markdown.zip" title="Markdown version">
+              Download Markdown version
+            </a>
+          <% end %>
         </span>
       </p>
 
diff --git a/lib/ex_doc/formatter/html/templates/module_template.eex b/lib/ex_doc/formatter/html/templates/module_template.eex
index b509f167b..f057d3f94 100644
--- a/lib/ex_doc/formatter/html/templates/module_template.eex
+++ b/lib/ex_doc/formatter/html/templates/module_template.eex
@@ -9,6 +9,14 @@
         <span class="sr-only">View Source</span>
       </a>
     <% end %>
+    <%= if "markdown" in config.formatters do %>
+      <a href="<%= config.project %>-markdown.zip" title="Markdown version">
+        <%= IO.inspect(module).title %>
+        <i class="ri-markdown-line" aria-hidden="true"></i>
+        <span class="sr-only">Download Markdown version</span>
+      </a>
+    <% end %>
+
     <span translate="no"><%= module.title %></span> <%= module_type(module) %>
     <small class="app-vsn" translate="no">(<%= config.project %> v<%= config.version %>)</small>
     <%= for annotation <- module.annotations do %>
diff --git a/lib/ex_doc/formatter/markdown.ex b/lib/ex_doc/formatter/markdown.ex
index 381b42041..ca0e49178 100644
--- a/lib/ex_doc/formatter/markdown.ex
+++ b/lib/ex_doc/formatter/markdown.ex
@@ -1,7 +1,6 @@
-defmodule ExDoc.Formatter.Markdown do
+defmodule ExDoc.Formatter.MARKDOWN do
   @moduledoc false
 
-  @mimetype "text/markdown"
   @assets_dir "MD/assets"
   alias __MODULE__.{Assets, Templates}
   alias ExDoc.Formatter.HTML
@@ -28,24 +27,24 @@ defmodule ExDoc.Formatter.Markdown do
 
     extras =
       config
-      |> HTML.build_extras(".xhtml")
+      |> HTML.build_extras(".md")
       |> Enum.chunk_by(& &1.group)
       |> Enum.map(&{hd(&1).group, &1})
 
     config = %{config | extras: extras}
 
-    static_files = HTML.generate_assets("MD", default_assets(config), config)
-    HTML.generate_logo(@assets_dir, config)
-    HTML.generate_cover(@assets_dir, config)
-
-    # generate_nav(config, nodes_map)
+    generate_nav(config, nodes_map) 
     generate_extras(config)
     generate_list(config, nodes_map.modules)
     generate_list(config, nodes_map.tasks)
 
-    {:ok, epub} = generate_zip(config.output)
-    File.rm_rf!(config.output)
-    Path.relative_to_cwd(epub)
+    # if config[:generate_zip] do # TODO: add a command line flag?
+    #   {:ok, zip} = generate_zip(config.output)
+    #   File.rm_rf!(config.output)
+    #   Path.relative_to_cwd(zip)
+    # else
+      config.output |> Path.join("index.md") |> Path.relative_to_cwd()
+    # end
   end
 
   defp normalize_config(config) do
@@ -57,6 +56,23 @@ defmodule ExDoc.Formatter.Markdown do
     %{config | output: output}
   end
 
+  defp normalize_output(output) do
+    output
+    |> String.replace(~r/\r\n|\r|\n/, "\n")
+    |> String.replace(~r/\n{2,}/, "\n") 
+  end
+
+  defp generate_nav(config, nodes) do
+    nodes =
+      Map.update!(nodes, :modules, fn modules ->
+        modules |> Enum.chunk_by(& &1.group) |> Enum.map(&{hd(&1).group, &1})
+      end)
+
+    content = Templates.nav_template(config, nodes)
+    |> normalize_output()
+    File.write("#{config.output}/MD/index.md", content)
+  end
+
   defp generate_extras(config) do
     for {_title, extras} <- config.extras do
       Enum.each(extras, fn %{id: id, title: title, title_content: _title_content, source: content} ->
@@ -66,6 +82,7 @@ defmodule ExDoc.Formatter.Markdown do
 
         #{content}
         """
+        |> normalize_output()
 
         if File.regular?(output) do
           Utils.warn("file #{Path.relative_to_cwd(output)} already exists", [])
@@ -77,8 +94,6 @@ defmodule ExDoc.Formatter.Markdown do
   end
 
 
-
-
   defp generate_list(config, nodes) do
     nodes
     |> Task.async_stream(&generate_module_page(&1, config), timeout: :infinity)
@@ -99,13 +114,6 @@ defmodule ExDoc.Formatter.Markdown do
 
   ## Helpers
 
-  defp default_assets(config) do
-    [
-      {Assets.dist(config.proglang), "MD/dist"},
-      {Assets.metainfo(), "META-INF"}
-    ]
-  end
-
   defp files_to_add(path) do
     Enum.reduce(Path.wildcard(Path.join(path, "**/*")), [], fn file, acc ->
       case File.read(file) do
@@ -120,6 +128,7 @@ defmodule ExDoc.Formatter.Markdown do
 
   defp generate_module_page(module_node, config) do
     content = Templates.module_page(config, module_node)
+    |> normalize_output()
     File.write("#{config.output}/MD/#{module_node.id}.md", content)
   end
 
diff --git a/lib/ex_doc/formatter/markdown/assets.ex b/lib/ex_doc/formatter/markdown/assets.ex
index 2a3041226..5001fae5b 100644
--- a/lib/ex_doc/formatter/markdown/assets.ex
+++ b/lib/ex_doc/formatter/markdown/assets.ex
@@ -1,4 +1,4 @@
-defmodule ExDoc.Formatter.Markdown.Assets do
+defmodule ExDoc.Formatter.MARKDOWN.Assets do
   @moduledoc false
 
   defmacrop embed_pattern(pattern) do
diff --git a/lib/ex_doc/formatter/markdown/templates.ex b/lib/ex_doc/formatter/markdown/templates.ex
index ab9c5b498..da57e5341 100644
--- a/lib/ex_doc/formatter/markdown/templates.ex
+++ b/lib/ex_doc/formatter/markdown/templates.ex
@@ -1,10 +1,10 @@
-defmodule ExDoc.Formatter.Markdown.Templates do
+defmodule ExDoc.Formatter.MARKDOWN.Templates do
   @moduledoc false
 
   require EEx
 
   import ExDoc.Utils,
-    only: [before_closing_body_tag: 2, before_closing_head_tag: 2, h: 1, text_to_id: 1]
+    only: [before_closing_body_tag: 2, h: 1, text_to_id: 1]
 
   alias ExDoc.Formatter.HTML.Templates, as: H
 
@@ -119,48 +119,34 @@ defmodule ExDoc.Formatter.Markdown.Templates do
     trim: true
   )
 
-  # @doc """
-  # Creates the table of contents.
-
-  # This template follows the EPUB Navigation Document Definition.
-
-  # See http://www.idpf.org/epub/30/spec/epub30-contentdocs.html#sec-xhtml-nav.
-  # """
-  # EEx.function_from_file(
-  #   :def,
-  #   :nav_template,
-  #   Path.expand("templates/nav_template.eex", __DIR__),
-  #   [:config, :nodes],
-  #   trim: true
-  # )
+  @doc """
+  Creates the table of contents.
 
-  # @doc """
-  # Creates a new chapter when the user provides additional files.
-  # """
-  # EEx.function_from_file(
-  #   :def,
-  #   :extra_template,
-  #   Path.expand("templates/extra_template.eex", __DIR__),
-  #   [:config, :title, :title_content, :content],
-  #   trim: true
-  # )
+  """
+  EEx.function_from_file(
+    :def,
+    :nav_template,
+    Path.expand("templates/nav_template.eex", __DIR__),
+    [:config, :nodes],
+    trim: true
+  )
 
 
-  # EEx.function_from_file(
-  #   :defp,
-  #   :nav_item_template,
-  #   Path.expand("templates/nav_item_template.eex", __DIR__),
-  #   [:name, :nodes],
-  #   trim: true
-  # )
+  EEx.function_from_file(
+    :defp,
+    :nav_item_template,
+    Path.expand("templates/nav_item_template.eex", __DIR__),
+    [:name, :nodes],
+    trim: true
+  )
 
-  # EEx.function_from_file(
-  #   :defp,
-  #   :nav_grouped_item_template,
-  #   Path.expand("templates/nav_grouped_item_template.eex", __DIR__),
-  #   [:nodes],
-  #   trim: true
-  # )
+  EEx.function_from_file(
+    :defp,
+    :nav_grouped_item_template,
+    Path.expand("templates/nav_grouped_item_template.eex", __DIR__),
+    [:nodes],
+    trim: true
+  )
 
   # EEx.function_from_file(
   #   :defp,
@@ -170,17 +156,6 @@ defmodule ExDoc.Formatter.Markdown.Templates do
   #   trim: true
   # )
 
-  # "templates/media-types.txt"
-  # |> Path.expand(__DIR__)
-  # |> File.read!()
-  # |> String.split("\n", trim: true)
-  # |> Enum.each(fn line ->
-  #   [extension, media] = String.split(line, ",")
-
-  #   def media_type("." <> unquote(extension)) do
-  #     unquote(media)
-  #   end
-  # end)
 
   # def media_type(_arg), do: nil
 
diff --git a/lib/ex_doc/formatter/markdown/templates/nav_grouped_item_template.eex b/lib/ex_doc/formatter/markdown/templates/nav_grouped_item_template.eex
new file mode 100644
index 000000000..874ebdbfd
--- /dev/null
+++ b/lib/ex_doc/formatter/markdown/templates/nav_grouped_item_template.eex
@@ -0,0 +1,8 @@
+<%= for {title, nodes} <- nodes do %>
+<%= if title do %>
+- <%=h to_string(title) %>
+<% end %>
+<%= for node <- nodes do %>
+  - [<%=h node.title %>](<%= URI.encode node.id %>.md)
+<% end %>
+<% end %>
diff --git a/lib/ex_doc/formatter/markdown/templates/nav_item_template.eex b/lib/ex_doc/formatter/markdown/templates/nav_item_template.eex
new file mode 100644
index 000000000..aaa568662
--- /dev/null
+++ b/lib/ex_doc/formatter/markdown/templates/nav_item_template.eex
@@ -0,0 +1,6 @@
+<%= unless Enum.empty?(nodes) do %>
+- <%= name %>
+<%= for node <- nodes do %>
+1. [<%=h node.title %>](<%= URI.encode node.id %>.md)
+<% end %>
+<% end %>
diff --git a/lib/ex_doc/formatter/markdown/templates/nav_template.eex b/lib/ex_doc/formatter/markdown/templates/nav_template.eex
new file mode 100644
index 000000000..aa35d02df
--- /dev/null
+++ b/lib/ex_doc/formatter/markdown/templates/nav_template.eex
@@ -0,0 +1,9 @@
+# Table of contents
+
+<%= nav_grouped_item_template config.extras  %>
+<%= unless Enum.empty?(nodes.modules) do %>
+## Modules
+<%= nav_grouped_item_template nodes.modules  %>    
+<% end %>
+<%= nav_item_template "Mix Tasks", nodes.tasks %>
+<%= before_closing_body_tag(config, :markdown) %>
diff --git a/test/ex_doc/formatter/markdown/templates_test.exs b/test/ex_doc/formatter/markdown/templates_test.exs
new file mode 100644
index 000000000..69c3cbc97
--- /dev/null
+++ b/test/ex_doc/formatter/markdown/templates_test.exs
@@ -0,0 +1,157 @@
+defmodule ExDoc.Formatter.MARKDOWN.TemplatesTest do
+  use ExUnit.Case, async: true
+
+  alias ExDoc.Formatter.HTML
+  alias ExDoc.Formatter.MARKDOWN.Templates
+
+  defp source_url do
+    "https://github.com/elixir-lang/elixir"
+  end
+
+  defp homepage_url do
+    "https://elixir-lang.org"
+  end
+
+  defp doc_config(config \\ []) do
+    default = %ExDoc.Config{
+      project: "Elixir",
+      version: "1.0.1",
+      source_url_pattern: "#{source_url()}/blob/master/%{path}#L%{line}",
+      homepage_url: homepage_url(),
+      source_url: source_url(),
+      output: "test/tmp/markdown_templates"
+    }
+
+    struct(default, config)
+  end
+
+  defp get_module_page(names, config \\ []) do
+    config = doc_config(config)
+    {mods, []} = ExDoc.Retriever.docs_from_modules(names, config)
+    [mod | _] = HTML.render_all(mods, [], ".md", config, highlight_tag: "samp")
+    Templates.module_page(config, mod)
+  end
+
+  setup_all do
+    # File.mkdir_p!("test/tmp/markdown_templates")
+    # File.cp_r!("formatters/markdown", "test/tmp/markdown_templates")
+    :ok
+  end
+
+  describe "content_template/5" do
+    test "includes logo as a resource if specified in the config" do
+      nodes = %{modules: [], tasks: []}
+
+      content =
+        [logo: "my_logo.png"]
+        |> doc_config()
+        |> Templates.content_template(nodes, "uuid", "datetime", _static_files = [])
+
+      assert content =~ ~S|<item id="logo" href="assets/logo.png" media-type="image/png"/>|
+    end
+
+
+    test "includes modules as a resource" do
+      module_node = %ExDoc.ModuleNode{
+        module: XPTOModule,
+        doc: nil,
+        id: "XPTOModule",
+        title: "XPTOModule"
+      }
+
+      nodes = %{modules: [module_node], tasks: []}
+
+      content =
+        Templates.content_template(doc_config(), nodes, "uuid", "datetime", _static_files = [])
+
+      assert content =~
+               ~S|<item id="XPTOModule" href="XPTOModule.md" media-type="application/md+xml" properties="scripted"/>|
+
+      assert content =~ ~S|<itemref idref="XPTOModule"/>|
+    end
+  end
+
+  describe "module_page/2" do
+    test "generates only the module name when there's no more info" do
+      module_node = %ExDoc.ModuleNode{
+        module: XPTOModule,
+        doc: nil,
+        id: "XPTOModule",
+        title: "XPTOModule"
+      }
+
+      content = Templates.module_page(doc_config(), module_node)
+
+      assert content =~ ~r{#\s*XPTOModule\s*}
+    end
+
+    test "outputs the functions and docstrings" do
+      content = get_module_page([CompiledWithDocs])
+
+      assert content =~ ~r{#\s*CompiledWithDocs\s*}
+
+      assert content =~ ~s{# Summary</h1>}
+
+      assert content =~
+               ~r{## .*Example.*}ms
+
+      assert content =~
+               ~r{### .*Example H3 heading.*}ms
+
+      assert content =~
+               ~r{moduledoc.*Example.*<samp class="nc">CompiledWithDocs</samp><samp class="o">\.</samp><samp class="n">example</samp>.*}ms
+
+      assert content =~ ~r{example/2.*Some example}ms
+      assert content =~ ~r{example_without_docs/0.*}ms
+      assert content =~ ~r{example_1/0.*> \(macro\)}ms
+
+      assert content =~ ~s{example(foo, bar \\\\ Baz)}
+    end
+
+    test "outputs function groups" do
+      content =
+        get_module_page([CompiledWithDocs],
+          groups_for_docs: [
+            "Example functions": &(&1[:purpose] == :example),
+            Legacy: &is_binary(&1[:deprecated])
+          ]
+        )
+
+      assert content =~ ~r{.*Example functions}ms
+      assert content =~ ~r{.*Legacy}ms
+    end
+
+
+    ## BEHAVIOURS
+
+    test "outputs behavior and callbacks" do
+      content = get_module_page([CustomBehaviourOne])
+
+      assert content =~
+               ~r{# \s*CustomBehaviourOne\s*behaviour\s*}m
+
+      assert content =~ ~r{Callbacks}
+
+      content = get_module_page([CustomBehaviourTwo])
+
+      assert content =~
+               ~r{# \s*CustomBehaviourTwo\s*behaviour\s*}m
+
+      assert content =~ ~r{Callbacks}
+    end
+
+    ## PROTOCOLS
+
+    test "outputs the protocol type" do
+      content = get_module_page([CustomProtocol])
+      assert content =~ ~r{# \s*CustomProtocol\s*protocol\s*}m
+    end
+
+    ## TASKS
+
+    test "outputs the task type" do
+      content = get_module_page([Mix.Tasks.TaskWithDocs])
+      assert content =~ ~r{# \s*mix task_with_docs\s*}m
+    end
+  end
+end
diff --git a/test/ex_doc/formatter/markdown_test.exs b/test/ex_doc/formatter/markdown_test.exs
new file mode 100644
index 000000000..9af39ecf6
--- /dev/null
+++ b/test/ex_doc/formatter/markdown_test.exs
@@ -0,0 +1,173 @@
+defmodule ExDoc.Formatter.MARKDOWNTest do
+  use ExUnit.Case, async: false
+
+  import ExUnit.CaptureIO
+
+  alias ExDoc.Utils
+
+  @moduletag :tmp_dir
+
+  @before_closing_body_tag_content_md "UNIQUE:<dont-escape>&copy;BEFORE-CLOSING-BODY-TAG-HTML</dont-escape>"
+
+  defp before_closing_body_tag(:markdown), do: @before_closing_body_tag_content_md
+
+  def before_closing_body_tag(:markdown, name), do: "#{name}"
+
+  defp doc_config(%{tmp_dir: tmp_dir} = _context) do
+    [
+      app: :elixir,
+      project: "Elixir",
+      version: "1.0.1",
+      formatter: "markdown",
+      output: tmp_dir <> "/markdown",
+      source_beam: "test/tmp/beam",
+      extras: ["test/fixtures/README.md"],
+      skip_undefined_reference_warnings_on: ["Warnings"]
+    ]
+  end
+
+  defp doc_config(context, config) when is_map(context) and is_list(config) do
+    Keyword.merge(doc_config(context), config)
+  end
+
+  defp generate_docs(config) do
+    ExDoc.generate_docs(config[:project], config[:version], config)
+  end
+
+  defp generate_docs(_context, config) do
+    generate_docs(config)
+  end
+
+
+  test "generates a markdown nav file in the default directory", %{tmp_dir: tmp_dir} = context do
+    generate_docs(doc_config(context))
+    assert File.regular?(tmp_dir <> "/markdown/Elixir/MD/nav.md")
+  end
+
+  test "generates a markdown file with erlang as proglang", %{tmp_dir: tmp_dir} = context do
+    config =
+      context
+      |> doc_config()
+      |> Keyword.put(:proglang, :erlang)
+      |> Keyword.update!(:skip_undefined_reference_warnings_on, &["test/fixtures/README.md" | &1])
+
+    generate_docs(config)
+    assert File.regular?(tmp_dir <> "/markdown/Elixir/MD/nav.md")
+  end
+
+  test "generates a markdown file in specified output directory", %{tmp_dir: tmp_dir} = context do
+    config = doc_config(context, output: tmp_dir <> "/markdown/another_dir", main: "RandomError")
+    generate_docs(config)
+
+    assert File.regular?(tmp_dir <> "/markdown/another_dir/nav.md")
+  end
+
+
+  test "generates the readme file", %{tmp_dir: tmp_dir} = context do
+    config = doc_config(context, main: "README")
+    generate_docs(context, config)
+
+    content = File.read!(tmp_dir <> "/markdown/Elixir/MD/readme.md")
+    assert content =~ ~r{<title>README [^<]*</title>}
+    assert content =~ ~r{<a href="RandomError.xhtml"><code(\sclass="inline")?>RandomError</code>}
+
+    assert content =~
+             ~r{<a href="CustomBehaviourImpl.xhtml#hello/1"><code(\sclass="inline")?>CustomBehaviourImpl.hello/1</code>}
+
+    assert content =~
+             ~r{<a href="TypesAndSpecs.Sub.xhtml"><code(\sclass="inline")?>TypesAndSpecs.Sub</code></a>}
+
+    content = File.read!(tmp_dir <> "/markdown/Elixir/MD/nav.md")
+    assert content =~ ~r{<li><a href="readme.xhtml">README</a></li>}
+  end
+
+  test "uses samp as highlight tag for markdown", %{tmp_dir: tmp_dir} = context do
+    generate_docs(context, doc_config(context))
+
+    assert File.read!(tmp_dir <> "/markdown/Elixir/MD/CompiledWithDocs.md") =~
+             "<samp class=\"nc\">CompiledWithDocs<\/samp>"
+  end
+
+  @example_basenames [
+    # "structural" pages
+    "nav.md",
+    "readme.md",
+    # "module pages"
+    "CompiledWithDocs.md",
+    "CompiledWithDocs.Nested.md"
+  ]
+
+  test "before_closing_*_tags required by the user are in the right place",
+       %{tmp_dir: tmp_dir} = context do
+    generate_docs(
+      context,
+      doc_config(context,
+        before_closing_body_tag: &before_closing_body_tag/1
+      )
+    )
+
+    dir = tmp_dir <> "/markdown/Elixir/MD"
+
+    for basename <- @example_basenames do
+      content = File.read!(Path.join(dir, basename))
+      assert content =~ ~r[#{@before_closing_body_tag_content_md}\s]
+    end
+  end
+
+  test "before_closing_*_tags required by the user are in the right place using map",
+       %{tmp_dir: tmp_dir} = context do
+    generate_docs(
+      context,
+      doc_config(context,
+        before_closing_body_tag: %{markdown: "<p>StaticDemo</p>"}
+      )
+    )
+
+    dir = tmp_dir <> "/markdown/Elixir/MD"
+
+    for basename <- @example_basenames do
+      content = File.read!(Path.join(dir, basename))
+      assert content =~ ~r[<p>StaticDemo</p>\s]
+    end
+  end
+
+  test "before_closing_*_tags required by the user are in the right place using a MFA",
+       %{tmp_dir: tmp_dir} = context do
+    generate_docs(
+      context,
+      doc_config(context,
+        before_closing_body_tag: {__MODULE__, :before_closing_body_tag, ["Demo"]}
+      )
+    )
+
+    dir = tmp_dir <> "/markdown/Elixir/MD"
+
+    for basename <- @example_basenames do
+      content = File.read!(Path.join(dir, basename))
+      assert content =~ ~r[<p>Demo</p>\s]
+    end
+  end
+
+  test "assets required by the user end up in the right place", %{tmp_dir: tmp_dir} = context do
+    File.mkdir_p!("test/tmp/markdown_assets/hello")
+    File.touch!("test/tmp/markdown_assets/hello/world.png")
+    File.touch!("test/tmp/markdown_assets/hello/world.pdf")
+
+    generate_docs(
+      context,
+      doc_config(context,
+        assets: %{"test/tmp/markdown_assets" => "assets"},
+        logo: "test/fixtures/elixir.png",
+        cover: "test/fixtures/elixir.png"
+      )
+    )
+
+    assert File.regular?(tmp_dir <> "/markdown/assets/hello/world.png")
+    assert File.regular?(tmp_dir <> "/markdown/assets/hello/world.pdf")
+    assert File.regular?(tmp_dir <> "/markdown/assets/logo.png")
+    assert File.regular?(tmp_dir <> "/markdown/assets/cover.png")
+  after
+    File.rm_rf!("test/tmp/markdown_assets")
+  end
+
+end

From 23b5f0141b0993befc7c0b83ce5db4f589430035 Mon Sep 17 00:00:00 2001
From: Mayel de Borniol <git@mayel.space>
Date: Thu, 26 Dec 2024 15:56:45 +0000
Subject: [PATCH 03/10] cleanup

---
 lib/ex_doc.ex                           |  1 -
 lib/ex_doc/formatter/markdown.ex        | 25 +++++++++----------------
 lib/ex_doc/formatter/markdown/assets.ex | 17 -----------------
 3 files changed, 9 insertions(+), 34 deletions(-)
 delete mode 100644 lib/ex_doc/formatter/markdown/assets.ex

diff --git a/lib/ex_doc.ex b/lib/ex_doc.ex
index 4fdf725a3..c108c3560 100644
--- a/lib/ex_doc.ex
+++ b/lib/ex_doc.ex
@@ -44,7 +44,6 @@ defmodule ExDoc do
     if Code.ensure_loaded?(modname) do
       modname
     else
-      IO.inspect(modname)
       raise "formatter module #{inspect(argname)} not found"
     end
   end
diff --git a/lib/ex_doc/formatter/markdown.ex b/lib/ex_doc/formatter/markdown.ex
index ca0e49178..9ea95c33c 100644
--- a/lib/ex_doc/formatter/markdown.ex
+++ b/lib/ex_doc/formatter/markdown.ex
@@ -1,8 +1,7 @@
 defmodule ExDoc.Formatter.MARKDOWN do
   @moduledoc false
 
-  @assets_dir "MD/assets"
-  alias __MODULE__.{Assets, Templates}
+  alias __MODULE__.{Templates}
   alias ExDoc.Formatter.HTML
   alias ExDoc.Utils
 
@@ -15,7 +14,7 @@ defmodule ExDoc.Formatter.MARKDOWN do
 
     config = normalize_config(config)
     File.rm_rf!(config.output)
-    File.mkdir_p!(Path.join(config.output, "MD"))
+    File.mkdir_p!(config.output)
 
     project_nodes =
       HTML.render_all(project_nodes, filtered_modules, ".md", config, highlight_tag: "samp")
@@ -51,7 +50,7 @@ defmodule ExDoc.Formatter.MARKDOWN do
     output =
       config.output
       |> Path.expand()
-      |> Path.join("#{config.project}")
+      |> Path.join("markdown")
 
     %{config | output: output}
   end
@@ -59,7 +58,7 @@ defmodule ExDoc.Formatter.MARKDOWN do
   defp normalize_output(output) do
     output
     |> String.replace(~r/\r\n|\r|\n/, "\n")
-    |> String.replace(~r/\n{2,}/, "\n") 
+    |> String.replace(~r/\n{3,}/, "\n\n") 
   end
 
   defp generate_nav(config, nodes) do
@@ -70,25 +69,19 @@ defmodule ExDoc.Formatter.MARKDOWN do
 
     content = Templates.nav_template(config, nodes)
     |> normalize_output()
-    File.write("#{config.output}/MD/index.md", content)
+    File.write("#{config.output}/index.md", content)
   end
 
   defp generate_extras(config) do
     for {_title, extras} <- config.extras do
-      Enum.each(extras, fn %{id: id, title: title, title_content: _title_content, source: content} ->
-        output = "#{config.output}/MD/#{id}.md"
-        content = """
-        # #{title}
-
-        #{content}
-        """
-        |> normalize_output()
+      Enum.each(extras, fn %{id: id, source: content} ->
+        output = "#{config.output}/#{id}.md"
 
         if File.regular?(output) do
           Utils.warn("file #{Path.relative_to_cwd(output)} already exists", [])
         end
 
-        File.write!(output, content)
+        File.write!(output, normalize_output(content))
       end)
     end
   end
@@ -129,7 +122,7 @@ defmodule ExDoc.Formatter.MARKDOWN do
   defp generate_module_page(module_node, config) do
     content = Templates.module_page(config, module_node)
     |> normalize_output()
-    File.write("#{config.output}/MD/#{module_node.id}.md", content)
+    File.write("#{config.output}/#{module_node.id}.md", content)
   end
 
 end
diff --git a/lib/ex_doc/formatter/markdown/assets.ex b/lib/ex_doc/formatter/markdown/assets.ex
deleted file mode 100644
index 5001fae5b..000000000
--- a/lib/ex_doc/formatter/markdown/assets.ex
+++ /dev/null
@@ -1,17 +0,0 @@
-defmodule ExDoc.Formatter.MARKDOWN.Assets do
-  @moduledoc false
-
-  defmacrop embed_pattern(pattern) do
-    ["formatters/markdown", pattern]
-    |> Path.join()
-    |> Path.wildcard()
-    |> Enum.map(fn path ->
-      Module.put_attribute(__CALLER__.module, :external_resource, path)
-      {Path.basename(path), File.read!(path)}
-    end)
-  end
-
-  def dist(_proglang), do: []
-
-  def metainfo, do: embed_pattern("metainfo/*")
-end

From 6bd15cc7b8087f0b152ceb89cee5c9b0df6a94e5 Mon Sep 17 00:00:00 2001
From: Mayel de Borniol <git@mayel.space>
Date: Fri, 27 Dec 2024 15:42:48 +0000
Subject: [PATCH 04/10] update footer links & md tests

---
 lib/ex_doc/formatter/html/templates.ex        |  15 +++
 .../html/templates/footer_template.eex        |  46 ++++---
 .../html/templates/module_template.eex        |   7 --
 lib/ex_doc/formatter/markdown.ex              |  38 ++----
 lib/ex_doc/formatter/markdown/templates.ex    |  15 ++-
 .../markdown/templates/detail_template.eex    |   6 +-
 .../markdown/templates/module_template.eex    |   2 +-
 lib/ex_doc/language/elixir.ex                 |   2 +-
 .../formatter/markdown/templates_test.exs     |  50 ++------
 test/ex_doc/formatter/markdown_test.exs       | 118 ++----------------
 10 files changed, 90 insertions(+), 209 deletions(-)

diff --git a/lib/ex_doc/formatter/html/templates.ex b/lib/ex_doc/formatter/html/templates.ex
index 435360578..235e441f1 100644
--- a/lib/ex_doc/formatter/html/templates.ex
+++ b/lib/ex_doc/formatter/html/templates.ex
@@ -209,6 +209,21 @@ defmodule ExDoc.Formatter.HTML.Templates do
 
   defp relative_asset([h | _], output, _pattern), do: Path.relative_to(h, output)
 
+  defp get_hex_url(config, source_path) do
+    case config.package do
+      nil ->
+        nil
+
+      package ->
+        base_url = "https://preview.hex.pm/preview/#{package}/#{config.version}"
+        if source_path, do: "#{base_url}/show/#{source_path}", else: base_url
+    end
+  end
+
+  defp get_markdown_path(node) do
+    if node && node.id, do: URI.encode(node.id), else: "index"
+  end
+
   # TODO: Move link_headings and friends to html.ex or even to autolinking code,
   # so content is built with it upfront instead of added at the template level.
 
diff --git a/lib/ex_doc/formatter/html/templates/footer_template.eex b/lib/ex_doc/formatter/html/templates/footer_template.eex
index 2f0042019..b9feb54ef 100644
--- a/lib/ex_doc/formatter/html/templates/footer_template.eex
+++ b/lib/ex_doc/formatter/html/templates/footer_template.eex
@@ -1,33 +1,43 @@
     <footer class="footer">
       <p>
-        <%= if config.package do %>
-          <span class="line">
-            <a href="https://hex.pm/packages/<%= config.package %>/<%= config.version %>" class="footer-hex-package">Hex Package</a>
+        <span class="line">
 
-            <a href="https://preview.hex.pm/preview/<%= config.package %>/<%= config.version %>">Hex Preview</a>
+          <%= if config.package do %>
+            <a href="https://hex.pm/packages/<%= config.package %>/<%= config.version %>" class="footer-hex-package">Hex Package</a>
+          <% end %>
 
-            <%= source_path = node && Map.get(node, :source_path); if source_path do %>
-              (<a href="https://preview.hex.pm/preview/<%= config.package %>/<%= config.version %>/show/<%= source_path %>">current file</a>)
+          <%
+            hex_url = get_hex_url(config, node && (Map.get(node, :source_path) || Map.get(node, :moduledoc_file)))
+            source_url = node && node.source_url
+          %>
+          <%= if hex_url || source_url do %>
+            View Code:
+            <%= if source_url do %>
+              <a href="<%= source_url %>" title="View Source Code" class="footer-button">Source Repo</a>
             <% end %>
-          </span>
-        <% end %>
 
-        <span class="line">
-          <button class="a-main footer-button display-quick-switch" title="Search HexDocs packages">
-            Search HexDocs
-          </button>
+            <%= if hex_url do %>
+              <a href="<%= hex_url %>" class="footer-button">Hex Preview</a>
+            <% end %>
+          <% end %>
 
-          <%= if "epub" in config.formatters do %>
-            <a href="<%= config.project %>.epub" title="ePub version">
-              Download ePub version
+          <%= if "markdown" in config.formatters do %>
+            <a href="./markdown/<%= get_markdown_path(node) %>.md" title="Markdown version" class="footer-button">
+              View Markdown version
             </a>
           <% end %>
 
-          <%= if "markdown" in config.formatters do %>
-            <a href="<%= config.project %>-markdown.zip" title="Markdown version">
-              Download Markdown version
+          <%= if config.package do %>
+            <a href="https://repo.hex.pm/docs/<%= config.package %>-<%= config.version %>.tar.gz" title="Archive containing docs in all available formats" class="footer-button">
+              Download docs archive
             </a>
           <% end %>
+
+
+          <button class="a-main footer-button display-quick-switch" title="Search HexDocs packages">
+            Search HexDocs
+          </button>
+
         </span>
       </p>
 
diff --git a/lib/ex_doc/formatter/html/templates/module_template.eex b/lib/ex_doc/formatter/html/templates/module_template.eex
index f057d3f94..e8c7e1ad2 100644
--- a/lib/ex_doc/formatter/html/templates/module_template.eex
+++ b/lib/ex_doc/formatter/html/templates/module_template.eex
@@ -9,13 +9,6 @@
         <span class="sr-only">View Source</span>
       </a>
     <% end %>
-    <%= if "markdown" in config.formatters do %>
-      <a href="<%= config.project %>-markdown.zip" title="Markdown version">
-        <%= IO.inspect(module).title %>
-        <i class="ri-markdown-line" aria-hidden="true"></i>
-        <span class="sr-only">Download Markdown version</span>
-      </a>
-    <% end %>
 
     <span translate="no"><%= module.title %></span> <%= module_type(module) %>
     <small class="app-vsn" translate="no">(<%= config.project %> v<%= config.version %>)</small>
diff --git a/lib/ex_doc/formatter/markdown.ex b/lib/ex_doc/formatter/markdown.ex
index 9ea95c33c..a41b8f775 100644
--- a/lib/ex_doc/formatter/markdown.ex
+++ b/lib/ex_doc/formatter/markdown.ex
@@ -32,18 +32,12 @@ defmodule ExDoc.Formatter.MARKDOWN do
 
     config = %{config | extras: extras}
 
-    generate_nav(config, nodes_map) 
+    generate_nav(config, nodes_map)
     generate_extras(config)
     generate_list(config, nodes_map.modules)
     generate_list(config, nodes_map.tasks)
 
-    # if config[:generate_zip] do # TODO: add a command line flag?
-    #   {:ok, zip} = generate_zip(config.output)
-    #   File.rm_rf!(config.output)
-    #   Path.relative_to_cwd(zip)
-    # else
-      config.output |> Path.join("index.md") |> Path.relative_to_cwd()
-    # end
+    config.output |> Path.join("index.md") |> Path.relative_to_cwd()
   end
 
   defp normalize_config(config) do
@@ -58,7 +52,7 @@ defmodule ExDoc.Formatter.MARKDOWN do
   defp normalize_output(output) do
     output
     |> String.replace(~r/\r\n|\r|\n/, "\n")
-    |> String.replace(~r/\n{3,}/, "\n\n") 
+    |> String.replace(~r/\n{3,}/, "\n\n")
   end
 
   defp generate_nav(config, nodes) do
@@ -67,8 +61,10 @@ defmodule ExDoc.Formatter.MARKDOWN do
         modules |> Enum.chunk_by(& &1.group) |> Enum.map(&{hd(&1).group, &1})
       end)
 
-    content = Templates.nav_template(config, nodes)
-    |> normalize_output()
+    content =
+      Templates.nav_template(config, nodes)
+      |> normalize_output()
+
     File.write("#{config.output}/index.md", content)
   end
 
@@ -86,25 +82,12 @@ defmodule ExDoc.Formatter.MARKDOWN do
     end
   end
 
-
   defp generate_list(config, nodes) do
     nodes
     |> Task.async_stream(&generate_module_page(&1, config), timeout: :infinity)
     |> Enum.map(&elem(&1, 1))
   end
 
-  defp generate_zip(output) do
-    :zip.create(
-      String.to_charlist("#{output}-markdown.zip"),
-      files_to_add(output),
-      compress: [
-        ~c".md",
-        ~c".jpg",
-        ~c".png"
-      ]
-    )
-  end
-
   ## Helpers
 
   defp files_to_add(path) do
@@ -120,9 +103,10 @@ defmodule ExDoc.Formatter.MARKDOWN do
   end
 
   defp generate_module_page(module_node, config) do
-    content = Templates.module_page(config, module_node)
-    |> normalize_output()
+    content =
+      Templates.module_page(config, module_node)
+      |> normalize_output()
+
     File.write("#{config.output}/#{module_node.id}.md", content)
   end
-
 end
diff --git a/lib/ex_doc/formatter/markdown/templates.ex b/lib/ex_doc/formatter/markdown/templates.ex
index da57e5341..da963103b 100644
--- a/lib/ex_doc/formatter/markdown/templates.ex
+++ b/lib/ex_doc/formatter/markdown/templates.ex
@@ -16,6 +16,13 @@ defmodule ExDoc.Formatter.MARKDOWN.Templates do
     module_template(config, module_node, summary)
   end
 
+  @doc """
+  Returns the formatted title for the module page.
+  """
+  def module_type(%{type: :task}), do: ""
+  def module_type(%{type: :module}), do: ""
+  def module_type(%{type: type}), do: "(#{type})"
+
   @doc """
   Generated ID for static file
   """
@@ -23,7 +30,7 @@ defmodule ExDoc.Formatter.MARKDOWN.Templates do
     static_file |> Path.basename() |> text_to_id()
   end
 
-  def node_doc(%{source_doc: %{"en"=> source}}), do: source
+  def node_doc(%{source_doc: %{"en" => source}}), do: source
   def node_doc(%{rendered_doc: source}), do: source
 
   @doc """
@@ -49,8 +56,8 @@ defmodule ExDoc.Formatter.MARKDOWN.Templates do
     # it is simpler to guarantee they won't be duplicated in docs.
     Regex.replace(~r|(<[^>]*) id="[^"]*"([^>]*>)|, doc, ~S"\1\2", [])
   end
-  
-    @doc """
+
+  @doc """
   Add link headings for the given `content`.
 
   IDs are prefixed with `prefix`.
@@ -131,7 +138,6 @@ defmodule ExDoc.Formatter.MARKDOWN.Templates do
     trim: true
   )
 
-
   EEx.function_from_file(
     :defp,
     :nav_item_template,
@@ -156,7 +162,6 @@ defmodule ExDoc.Formatter.MARKDOWN.Templates do
   #   trim: true
   # )
 
-
   # def media_type(_arg), do: nil
 
   templates = [
diff --git a/lib/ex_doc/formatter/markdown/templates/detail_template.eex b/lib/ex_doc/formatter/markdown/templates/detail_template.eex
index 32fd172ea..033065073 100644
--- a/lib/ex_doc/formatter/markdown/templates/detail_template.eex
+++ b/lib/ex_doc/formatter/markdown/templates/detail_template.eex
@@ -12,9 +12,9 @@
 > This <%= node.type %> is deprecated. <%= h(deprecated) %>.
 <% end %>
 
-<%= if specs = H.get_specs(node) do %>
-<%= for spec <- specs do %>
-> <%= H.format_spec_attribute(module, node) %> <%= spec %>
+<%= if node.specs != [] do %>
+<%= for spec <- node.specs do %>
+> <%= H.format_spec_attribute(module, node) %>: <%= spec %>
 <% end %>
 <% end %>
 
diff --git a/lib/ex_doc/formatter/markdown/templates/module_template.eex b/lib/ex_doc/formatter/markdown/templates/module_template.eex
index 750778cda..5bbd4f2b9 100644
--- a/lib/ex_doc/formatter/markdown/templates/module_template.eex
+++ b/lib/ex_doc/formatter/markdown/templates/module_template.eex
@@ -1,4 +1,4 @@
-# <%= module.title %> <%= H.module_type(module) %>
+# <%= module.title %> <%= module_type(module) %>
 
 <%= if deprecated = module.deprecated do %>
 > This <%= module.type %> is deprecated. <%=h deprecated %>.
diff --git a/lib/ex_doc/language/elixir.ex b/lib/ex_doc/language/elixir.ex
index 2600849cc..636cfa1a4 100644
--- a/lib/ex_doc/language/elixir.ex
+++ b/lib/ex_doc/language/elixir.ex
@@ -289,7 +289,7 @@ defmodule ExDoc.Language.Elixir do
         {:local, :..}
 
       ["//", "", ""] ->
-        {:local, :"..//"}
+        {:local, :..//}
 
       ["", ""] ->
         {:local, :.}
diff --git a/test/ex_doc/formatter/markdown/templates_test.exs b/test/ex_doc/formatter/markdown/templates_test.exs
index 69c3cbc97..da44e965f 100644
--- a/test/ex_doc/formatter/markdown/templates_test.exs
+++ b/test/ex_doc/formatter/markdown/templates_test.exs
@@ -38,39 +38,6 @@ defmodule ExDoc.Formatter.MARKDOWN.TemplatesTest do
     :ok
   end
 
-  describe "content_template/5" do
-    test "includes logo as a resource if specified in the config" do
-      nodes = %{modules: [], tasks: []}
-
-      content =
-        [logo: "my_logo.png"]
-        |> doc_config()
-        |> Templates.content_template(nodes, "uuid", "datetime", _static_files = [])
-
-      assert content =~ ~S|<item id="logo" href="assets/logo.png" media-type="image/png"/>|
-    end
-
-
-    test "includes modules as a resource" do
-      module_node = %ExDoc.ModuleNode{
-        module: XPTOModule,
-        doc: nil,
-        id: "XPTOModule",
-        title: "XPTOModule"
-      }
-
-      nodes = %{modules: [module_node], tasks: []}
-
-      content =
-        Templates.content_template(doc_config(), nodes, "uuid", "datetime", _static_files = [])
-
-      assert content =~
-               ~S|<item id="XPTOModule" href="XPTOModule.md" media-type="application/md+xml" properties="scripted"/>|
-
-      assert content =~ ~S|<itemref idref="XPTOModule"/>|
-    end
-  end
-
   describe "module_page/2" do
     test "generates only the module name when there's no more info" do
       module_node = %ExDoc.ModuleNode{
@@ -99,11 +66,11 @@ defmodule ExDoc.Formatter.MARKDOWN.TemplatesTest do
                ~r{### .*Example H3 heading.*}ms
 
       assert content =~
-               ~r{moduledoc.*Example.*<samp class="nc">CompiledWithDocs</samp><samp class="o">\.</samp><samp class="n">example</samp>.*}ms
+               ~r{moduledoc.*Example.*CompiledWithDocs\.example.*}ms
 
-      assert content =~ ~r{example/2.*Some example}ms
-      assert content =~ ~r{example_without_docs/0.*}ms
-      assert content =~ ~r{example_1/0.*> \(macro\)}ms
+      assert content =~ ~r{Some example}ms
+      assert content =~ ~r{example_without_docs().*}ms
+      assert content =~ ~r{example_1().*> \(macro\)}ms
 
       assert content =~ ~s{example(foo, bar \\\\ Baz)}
     end
@@ -121,21 +88,20 @@ defmodule ExDoc.Formatter.MARKDOWN.TemplatesTest do
       assert content =~ ~r{.*Legacy}ms
     end
 
-
     ## BEHAVIOURS
 
     test "outputs behavior and callbacks" do
       content = get_module_page([CustomBehaviourOne])
 
       assert content =~
-               ~r{# \s*CustomBehaviourOne\s*behaviour\s*}m
+               ~r{# CustomBehaviourOne \(behaviour\)}m
 
       assert content =~ ~r{Callbacks}
 
       content = get_module_page([CustomBehaviourTwo])
 
       assert content =~
-               ~r{# \s*CustomBehaviourTwo\s*behaviour\s*}m
+               ~r{# CustomBehaviourTwo \(behaviour\)}m
 
       assert content =~ ~r{Callbacks}
     end
@@ -144,14 +110,14 @@ defmodule ExDoc.Formatter.MARKDOWN.TemplatesTest do
 
     test "outputs the protocol type" do
       content = get_module_page([CustomProtocol])
-      assert content =~ ~r{# \s*CustomProtocol\s*protocol\s*}m
+      assert content =~ ~r{# CustomProtocol \(protocol\)}m
     end
 
     ## TASKS
 
     test "outputs the task type" do
       content = get_module_page([Mix.Tasks.TaskWithDocs])
-      assert content =~ ~r{# \s*mix task_with_docs\s*}m
+      assert content =~ ~r{#\s*mix task_with_docs}m
     end
   end
 end
diff --git a/test/ex_doc/formatter/markdown_test.exs b/test/ex_doc/formatter/markdown_test.exs
index 9af39ecf6..9688f5130 100644
--- a/test/ex_doc/formatter/markdown_test.exs
+++ b/test/ex_doc/formatter/markdown_test.exs
@@ -19,7 +19,7 @@ defmodule ExDoc.Formatter.MARKDOWNTest do
       project: "Elixir",
       version: "1.0.1",
       formatter: "markdown",
-      output: tmp_dir <> "/markdown",
+      output: tmp_dir,
       source_beam: "test/tmp/beam",
       extras: ["test/fixtures/README.md"],
       skip_undefined_reference_warnings_on: ["Warnings"]
@@ -38,10 +38,10 @@ defmodule ExDoc.Formatter.MARKDOWNTest do
     generate_docs(config)
   end
 
-
-  test "generates a markdown nav file in the default directory", %{tmp_dir: tmp_dir} = context do
+  test "generates a markdown index file in the default directory",
+       %{tmp_dir: tmp_dir} = context do
     generate_docs(doc_config(context))
-    assert File.regular?(tmp_dir <> "/markdown/Elixir/MD/nav.md")
+    assert File.regular?(tmp_dir <> "/markdown/index.md")
   end
 
   test "generates a markdown file with erlang as proglang", %{tmp_dir: tmp_dir} = context do
@@ -52,122 +52,30 @@ defmodule ExDoc.Formatter.MARKDOWNTest do
       |> Keyword.update!(:skip_undefined_reference_warnings_on, &["test/fixtures/README.md" | &1])
 
     generate_docs(config)
-    assert File.regular?(tmp_dir <> "/markdown/Elixir/MD/nav.md")
+    assert File.regular?(tmp_dir <> "/markdown/index.md")
   end
 
   test "generates a markdown file in specified output directory", %{tmp_dir: tmp_dir} = context do
-    config = doc_config(context, output: tmp_dir <> "/markdown/another_dir", main: "RandomError")
+    config = doc_config(context, output: tmp_dir <> "/another_dir", main: "RandomError")
     generate_docs(config)
 
-    assert File.regular?(tmp_dir <> "/markdown/another_dir/nav.md")
+    assert File.regular?(tmp_dir <> "/another_dir/markdown/index.md")
   end
 
-
   test "generates the readme file", %{tmp_dir: tmp_dir} = context do
     config = doc_config(context, main: "README")
     generate_docs(context, config)
 
-    content = File.read!(tmp_dir <> "/markdown/Elixir/MD/readme.md")
-    assert content =~ ~r{<title>README [^<]*</title>}
-    assert content =~ ~r{<a href="RandomError.xhtml"><code(\sclass="inline")?>RandomError</code>}
+    content = File.read!(tmp_dir <> "/markdown/readme.md")
+    assert content =~ ~r{`RandomError`\n}
 
     assert content =~
-             ~r{<a href="CustomBehaviourImpl.xhtml#hello/1"><code(\sclass="inline")?>CustomBehaviourImpl.hello/1</code>}
+             ~r{\n`CustomBehaviourImpl.hello/1`\n}
 
     assert content =~
-             ~r{<a href="TypesAndSpecs.Sub.xhtml"><code(\sclass="inline")?>TypesAndSpecs.Sub</code></a>}
-
-    content = File.read!(tmp_dir <> "/markdown/Elixir/MD/nav.md")
-    assert content =~ ~r{<li><a href="readme.xhtml">README</a></li>}
-  end
+             ~r{\n`TypesAndSpecs.Sub`\n}
 
-  test "uses samp as highlight tag for markdown", %{tmp_dir: tmp_dir} = context do
-    generate_docs(context, doc_config(context))
-
-    assert File.read!(tmp_dir <> "/markdown/Elixir/MD/CompiledWithDocs.md") =~
-             "<samp class=\"nc\">CompiledWithDocs<\/samp>"
-  end
-
-  @example_basenames [
-    # "structural" pages
-    "nav.md",
-    "readme.md",
-    # "module pages"
-    "CompiledWithDocs.md",
-    "CompiledWithDocs.Nested.md"
-  ]
-
-  test "before_closing_*_tags required by the user are in the right place",
-       %{tmp_dir: tmp_dir} = context do
-    generate_docs(
-      context,
-      doc_config(context,
-        before_closing_body_tag: &before_closing_body_tag/1
-      )
-    )
-
-    dir = tmp_dir <> "/markdown/Elixir/MD"
-
-    for basename <- @example_basenames do
-      content = File.read!(Path.join(dir, basename))
-      assert content =~ ~r[#{@before_closing_body_tag_content_md}\s]
-    end
+    content = File.read!(tmp_dir <> "/markdown/index.md")
+    assert content =~ "# Table of contents\n\n  - [README](readme.md)"
   end
-
-  test "before_closing_*_tags required by the user are in the right place using map",
-       %{tmp_dir: tmp_dir} = context do
-    generate_docs(
-      context,
-      doc_config(context,
-        before_closing_body_tag: %{markdown: "<p>StaticDemo</p>"}
-      )
-    )
-
-    dir = tmp_dir <> "/markdown/Elixir/MD"
-
-    for basename <- @example_basenames do
-      content = File.read!(Path.join(dir, basename))
-      assert content =~ ~r[<p>StaticDemo</p>\s]
-    end
-  end
-
-  test "before_closing_*_tags required by the user are in the right place using a MFA",
-       %{tmp_dir: tmp_dir} = context do
-    generate_docs(
-      context,
-      doc_config(context,
-        before_closing_body_tag: {__MODULE__, :before_closing_body_tag, ["Demo"]}
-      )
-    )
-
-    dir = tmp_dir <> "/markdown/Elixir/MD"
-
-    for basename <- @example_basenames do
-      content = File.read!(Path.join(dir, basename))
-      assert content =~ ~r[<p>Demo</p>\s]
-    end
-  end
-
-  test "assets required by the user end up in the right place", %{tmp_dir: tmp_dir} = context do
-    File.mkdir_p!("test/tmp/markdown_assets/hello")
-    File.touch!("test/tmp/markdown_assets/hello/world.png")
-    File.touch!("test/tmp/markdown_assets/hello/world.pdf")
-
-    generate_docs(
-      context,
-      doc_config(context,
-        assets: %{"test/tmp/markdown_assets" => "assets"},
-        logo: "test/fixtures/elixir.png",
-        cover: "test/fixtures/elixir.png"
-      )
-    )
-
-    assert File.regular?(tmp_dir <> "/markdown/assets/hello/world.png")
-    assert File.regular?(tmp_dir <> "/markdown/assets/hello/world.pdf")
-    assert File.regular?(tmp_dir <> "/markdown/assets/logo.png")
-    assert File.regular?(tmp_dir <> "/markdown/assets/cover.png")
-  after
-    File.rm_rf!("test/tmp/markdown_assets")
-  end
-
 end

From f2cfdc4b84b887542afd3bda7425962d77267286 Mon Sep 17 00:00:00 2001
From: Mayel de Borniol <git@mayel.space>
Date: Fri, 27 Dec 2024 16:37:55 +0000
Subject: [PATCH 05/10] add markdown rendering of AST

---
 lib/ex_doc/doc_ast.ex                         |  62 ++++-
 lib/ex_doc/formatter.ex                       | 251 ++++++++++++++++++
 lib/ex_doc/formatter/epub.ex                  |  11 +-
 lib/ex_doc/formatter/html.ex                  | 241 +----------------
 lib/ex_doc/formatter/markdown.ex              |  12 +-
 test/ex_doc/formatter/epub/templates_test.exs |   2 +-
 test/ex_doc/formatter/html/templates_test.exs |   4 +-
 .../formatter/markdown/templates_test.exs     |   2 +-
 8 files changed, 336 insertions(+), 249 deletions(-)
 create mode 100644 lib/ex_doc/formatter.ex

diff --git a/lib/ex_doc/doc_ast.ex b/lib/ex_doc/doc_ast.ex
index 375c670fa..1fd699745 100644
--- a/lib/ex_doc/doc_ast.ex
+++ b/lib/ex_doc/doc_ast.ex
@@ -27,7 +27,7 @@ defmodule ExDoc.DocAST do
     meta param source track wbr)a
 
   @doc """
-  Transform AST into string.
+  Transform AST into an HTML string.
   """
   def to_string(ast, fun \\ fn _ast, string -> string end)
 
@@ -64,6 +64,66 @@ defmodule ExDoc.DocAST do
     Enum.map(attrs, fn {key, val} -> " #{key}=\"#{val}\"" end)
   end
 
+  @doc """
+  Transform AST into a markdown string.
+  """
+  def to_markdown_string(ast, fun \\ fn _ast, string -> string end)
+
+  def to_markdown_string(binary, _fun) when is_binary(binary) do
+    ExDoc.Utils.h(binary)
+  end
+
+  def to_markdown_string(list, fun) when is_list(list) do
+    result = Enum.map_join(list, "", &to_markdown_string(&1, fun))
+    fun.(list, result)
+  end
+
+  def to_markdown_string({:comment, _attrs, inner, _meta} = ast, fun) do
+    fun.(ast, "<!--#{inner}-->")
+  end
+
+  def to_markdown_string({:code, _attrs, inner, _meta} = ast, fun) do
+    result = """
+    ```
+    #{inner}
+    ```
+    """
+
+    fun.(ast, result)
+  end
+
+  def to_markdown_string({:a, attrs, inner, _meta} = ast, fun) do
+    result = "[#{inner}](#{attrs[:href]})"
+    fun.(ast, result)
+  end
+
+  def to_markdown_string({:hr, _attrs, _inner, _meta} = ast, fun) do
+    result = "\n\n---\n\n"
+    fun.(ast, result)
+  end
+
+  def to_markdown_string({tag, _attrs, _inner, _meta} = ast, fun) when tag in [:p, :br] do
+    result = "\n\n"
+    fun.(ast, result)
+  end
+
+  # @void_elements ~W(area base br col command embed hr img input keygen link
+  #   meta param source track wbr)a
+  def to_markdown_string({tag, _attrs, _inner, _meta} = ast, fun) when tag in @void_elements do
+    result = ""
+    fun.(ast, result)
+  end
+
+  def to_markdown_string({tag, _attrs, inner, %{verbatim: true}} = ast, fun) do
+    result = Enum.join(inner, "")
+    fun.(ast, result)
+  end
+
+  def to_markdown_string({tag, _attrs, inner, _meta} = ast, fun) do
+    result = to_string(inner, fun)
+    fun.(ast, result)
+  end
+
   ## parse markdown
 
   defp parse_markdown(markdown, opts) do
diff --git a/lib/ex_doc/formatter.ex b/lib/ex_doc/formatter.ex
new file mode 100644
index 000000000..960e50705
--- /dev/null
+++ b/lib/ex_doc/formatter.ex
@@ -0,0 +1,251 @@
+defmodule ExDoc.Formatter do
+  @moduledoc false
+
+  alias __MODULE__.{Assets, Templates, SearchData}
+  alias ExDoc.{Markdown, GroupMatcher, Utils}
+
+  @main "api-reference"
+  @assets_dir "assets"
+
+  @doc """
+  Autolinks and renders all docs.
+  """
+  def render_all(project_nodes, filtered_modules, ext, config, opts) do
+    base = [
+      apps: config.apps,
+      deps: config.deps,
+      ext: ext,
+      extras: extra_paths(config),
+      skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on,
+      skip_code_autolink_to: config.skip_code_autolink_to,
+      filtered_modules: filtered_modules
+    ]
+
+    project_nodes
+    |> Task.async_stream(
+      fn node ->
+        language = node.language
+
+        autolink_opts =
+          [
+            current_module: node.module,
+            file: node.moduledoc_file,
+            line: node.moduledoc_line,
+            module_id: node.id,
+            language: language
+          ] ++ base
+
+        docs =
+          for child_node <- node.docs do
+            id = id(node, child_node)
+
+            autolink_opts =
+              autolink_opts ++
+                [
+                  id: id,
+                  line: child_node.doc_line,
+                  file: child_node.doc_file,
+                  current_kfa: {child_node.type, child_node.name, child_node.arity}
+                ]
+
+            specs = Enum.map(child_node.specs, &language.autolink_spec(&1, autolink_opts))
+            child_node = %{child_node | specs: specs}
+            render_doc(child_node, ext, language, autolink_opts, opts)
+          end
+
+        %{
+          render_doc(node, ext, language, [{:id, node.id} | autolink_opts], opts)
+          | docs: docs
+        }
+      end,
+      timeout: :infinity
+    )
+    |> Enum.map(&elem(&1, 1))
+  end
+
+  defp render_doc(%{doc: nil} = node, ext, _language, _autolink_opts, _opts),
+    do: node
+
+  defp render_doc(%{doc: doc} = node, ext, language, autolink_opts, opts) do
+    rendered = autolink_and_render(doc, ext, language, autolink_opts, opts)
+    %{node | rendered_doc: rendered}
+  end
+
+  defp id(%{id: mod_id}, %{id: "c:" <> id}) do
+    "c:" <> mod_id <> "." <> id
+  end
+
+  defp id(%{id: mod_id}, %{id: "t:" <> id}) do
+    "t:" <> mod_id <> "." <> id
+  end
+
+  defp id(%{id: mod_id}, %{id: id}) do
+    mod_id <> "." <> id
+  end
+
+  defp autolink_and_render(doc, ".md", language, autolink_opts, opts) do
+    doc
+    |> language.autolink_doc(autolink_opts)
+    |> ExDoc.DocAST.to_markdown_string()
+  end
+
+  defp autolink_and_render(doc, _html_ext, language, autolink_opts, opts) do
+    doc
+    |> language.autolink_doc(autolink_opts)
+    |> ExDoc.DocAST.to_string()
+    |> ExDoc.DocAST.highlight(language, opts)
+  end
+
+  @doc """
+  Builds extra nodes by normalizing the config entries.
+  """
+  def build_extras(config, ext) do
+    groups = config.groups_for_extras
+
+    language =
+      case config.proglang do
+        :erlang -> ExDoc.Language.Erlang
+        _ -> ExDoc.Language.Elixir
+      end
+
+    source_url_pattern = config.source_url_pattern
+
+    autolink_opts = [
+      apps: config.apps,
+      deps: config.deps,
+      ext: ext,
+      extras: extra_paths(config),
+      language: language,
+      skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on,
+      skip_code_autolink_to: config.skip_code_autolink_to
+    ]
+
+    extras =
+      config.extras
+      |> Task.async_stream(
+        &build_extra(&1, groups, ext, language, autolink_opts, source_url_pattern),
+        timeout: :infinity
+      )
+      |> Enum.map(&elem(&1, 1))
+
+    ids_count = Enum.reduce(extras, %{}, &Map.update(&2, &1.id, 1, fn c -> c + 1 end))
+
+    extras
+    |> Enum.map_reduce(1, fn extra, idx ->
+      if ids_count[extra.id] > 1, do: {disambiguate_id(extra, idx), idx + 1}, else: {extra, idx}
+    end)
+    |> elem(0)
+    |> Enum.sort_by(fn extra -> GroupMatcher.index(groups, extra.group) end)
+  end
+
+  defp build_extra(
+         {input, input_options},
+         groups,
+         ext,
+         language,
+         autolink_opts,
+         source_url_pattern
+       ) do
+    input = to_string(input)
+    id = input_options[:filename] || input |> filename_to_title() |> Utils.text_to_id()
+    source_file = input_options[:source] || input
+    opts = [file: source_file, line: 1]
+
+    {source, ast} =
+      case extension_name(input) do
+        extension when extension in ["", ".txt"] ->
+          source = File.read!(input)
+          ast = [{:pre, [], "\n" <> source, %{}}]
+          {source, ast}
+
+        extension when extension in [".md", ".livemd", ".cheatmd"] ->
+          source = File.read!(input)
+
+          ast =
+            source
+            |> Markdown.to_ast(opts)
+            |> sectionize(extension)
+
+          {source, ast}
+
+        _ ->
+          raise ArgumentError,
+                "file extension not recognized, allowed extension is either .cheatmd, .livemd, .md, .txt or no extension"
+      end
+
+    {title_ast, ast} =
+      case ExDoc.DocAST.extract_title(ast) do
+        {:ok, title_ast, ast} -> {title_ast, ast}
+        :error -> {nil, ast}
+      end
+
+    title_text = title_ast && ExDoc.DocAST.text_from_ast(title_ast)
+    title_html = title_ast && ExDoc.DocAST.to_string(title_ast)
+    content_html = autolink_and_render(ast, ext, language, [file: input] ++ autolink_opts, opts)
+
+    group = GroupMatcher.match_extra(groups, input)
+    title = input_options[:title] || title_text || filename_to_title(input)
+
+    source_path = source_file |> Path.relative_to(File.cwd!()) |> String.replace_leading("./", "")
+    source_url = Utils.source_url_pattern(source_url_pattern, source_path, 1)
+
+    %{
+      source: source,
+      content: content_html,
+      group: group,
+      id: id,
+      source_path: source_path,
+      source_url: source_url,
+      title: title,
+      title_content: title_html || title
+    }
+  end
+
+  defp build_extra(input, groups, ext, language, autolink_opts, source_url_pattern) do
+    build_extra({input, []}, groups, ext, language, autolink_opts, source_url_pattern)
+  end
+
+  defp extra_paths(config) do
+    Map.new(config.extras, fn
+      path when is_binary(path) ->
+        base = Path.basename(path)
+        {base, Utils.text_to_id(Path.rootname(base))}
+
+      {path, opts} ->
+        base = path |> to_string() |> Path.basename()
+        {base, opts[:filename] || Utils.text_to_id(Path.rootname(base))}
+    end)
+  end
+
+  defp disambiguate_id(extra, discriminator) do
+    Map.put(extra, :id, "#{extra.id}-#{discriminator}")
+  end
+
+  defp sectionize(ast, ".cheatmd") do
+    ExDoc.DocAST.sectionize(ast, fn
+      {:h2, _, _, _} -> true
+      {:h3, _, _, _} -> true
+      _ -> false
+    end)
+  end
+
+  defp sectionize(ast, _), do: ast
+
+  defp filename_to_title(input) do
+    input |> Path.basename() |> Path.rootname()
+  end
+
+  def filter_list(:module, nodes) do
+    Enum.filter(nodes, &(&1.type != :task))
+  end
+
+  def filter_list(type, nodes) do
+    Enum.filter(nodes, &(&1.type == type))
+  end
+
+  def extension_name(input) do
+    input
+    |> Path.extname()
+    |> String.downcase()
+  end
+end
diff --git a/lib/ex_doc/formatter/epub.ex b/lib/ex_doc/formatter/epub.ex
index 338cc497e..606b046c7 100644
--- a/lib/ex_doc/formatter/epub.ex
+++ b/lib/ex_doc/formatter/epub.ex
@@ -4,6 +4,7 @@ defmodule ExDoc.Formatter.EPUB do
   @mimetype "application/epub+zip"
   @assets_dir "OEBPS/assets"
   alias __MODULE__.{Assets, Templates}
+  alias ExDoc.Formatter
   alias ExDoc.Formatter.HTML
   alias ExDoc.Utils
 
@@ -17,16 +18,18 @@ defmodule ExDoc.Formatter.EPUB do
     File.mkdir_p!(Path.join(config.output, "OEBPS"))
 
     project_nodes =
-      HTML.render_all(project_nodes, filtered_modules, ".xhtml", config, highlight_tag: "samp")
+      Formatter.render_all(project_nodes, filtered_modules, ".xhtml", config,
+        highlight_tag: "samp"
+      )
 
     nodes_map = %{
-      modules: HTML.filter_list(:module, project_nodes),
-      tasks: HTML.filter_list(:task, project_nodes)
+      modules: Formatter.filter_list(:module, project_nodes),
+      tasks: Formatter.filter_list(:task, project_nodes)
     }
 
     extras =
       config
-      |> HTML.build_extras(".xhtml")
+      |> Formatter.build_extras(".xhtml")
       |> Enum.chunk_by(& &1.group)
       |> Enum.map(&{hd(&1).group, &1})
 
diff --git a/lib/ex_doc/formatter/html.ex b/lib/ex_doc/formatter/html.ex
index 1f07edef0..458a302dc 100644
--- a/lib/ex_doc/formatter/html.ex
+++ b/lib/ex_doc/formatter/html.ex
@@ -2,7 +2,7 @@ defmodule ExDoc.Formatter.HTML do
   @moduledoc false
 
   alias __MODULE__.{Assets, Templates, SearchData}
-  alias ExDoc.{Markdown, GroupMatcher, Utils}
+  alias ExDoc.{Formatter, Markdown, GroupMatcher, Utils}
 
   @main "api-reference"
   @assets_dir "assets"
@@ -18,8 +18,8 @@ defmodule ExDoc.Formatter.HTML do
     build = Path.join(config.output, ".build")
     output_setup(build, config)
 
-    project_nodes = render_all(project_nodes, filtered_modules, ".html", config, [])
-    extras = build_extras(config, ".html")
+    project_nodes = Formatter.render_all(project_nodes, filtered_modules, ".html", config, [])
+    extras = Formatter.build_extras(config, ".html")
 
     # Generate search early on without api reference in extras
     static_files = generate_assets(".", default_assets(config), config)
@@ -27,8 +27,8 @@ defmodule ExDoc.Formatter.HTML do
 
     # TODO: Move this categorization to the language
     nodes_map = %{
-      modules: filter_list(:module, project_nodes),
-      tasks: filter_list(:task, project_nodes)
+      modules: Formatter.filter_list(:module, project_nodes),
+      tasks: Formatter.filter_list(:task, project_nodes)
     }
 
     extras =
@@ -63,89 +63,6 @@ defmodule ExDoc.Formatter.HTML do
     %{config | main: main || @main}
   end
 
-  @doc """
-  Autolinks and renders all docs.
-  """
-  def render_all(project_nodes, filtered_modules, ext, config, opts) do
-    base = [
-      apps: config.apps,
-      deps: config.deps,
-      ext: ext,
-      extras: extra_paths(config),
-      skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on,
-      skip_code_autolink_to: config.skip_code_autolink_to,
-      filtered_modules: filtered_modules
-    ]
-
-    project_nodes
-    |> Task.async_stream(
-      fn node ->
-        language = node.language
-
-        autolink_opts =
-          [
-            current_module: node.module,
-            file: node.moduledoc_file,
-            line: node.moduledoc_line,
-            module_id: node.id,
-            language: language
-          ] ++ base
-
-        docs =
-          for child_node <- node.docs do
-            id = id(node, child_node)
-
-            autolink_opts =
-              autolink_opts ++
-                [
-                  id: id,
-                  line: child_node.doc_line,
-                  file: child_node.doc_file,
-                  current_kfa: {child_node.type, child_node.name, child_node.arity}
-                ]
-
-            specs = Enum.map(child_node.specs, &language.autolink_spec(&1, autolink_opts))
-            child_node = %{child_node | specs: specs}
-            render_doc(child_node, language, autolink_opts, opts)
-          end
-
-        %{
-          render_doc(node, language, [{:id, node.id} | autolink_opts], opts)
-          | docs: docs
-        }
-      end,
-      timeout: :infinity
-    )
-    |> Enum.map(&elem(&1, 1))
-  end
-
-  defp render_doc(%{doc: nil} = node, _language, _autolink_opts, _opts),
-    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}
-  end
-
-  defp id(%{id: mod_id}, %{id: "c:" <> id}) do
-    "c:" <> mod_id <> "." <> id
-  end
-
-  defp id(%{id: mod_id}, %{id: "t:" <> id}) do
-    "t:" <> mod_id <> "." <> id
-  end
-
-  defp id(%{id: mod_id}, %{id: id}) do
-    mod_id <> "." <> id
-  end
-
-  defp autolink_and_render(doc, language, autolink_opts, opts) do
-    doc
-    |> language.autolink_doc(autolink_opts)
-    |> ExDoc.DocAST.to_string()
-    |> ExDoc.DocAST.highlight(language, opts)
-  end
-
   defp output_setup(build, config) do
     if File.exists?(build) do
       build
@@ -237,7 +154,7 @@ defmodule ExDoc.Formatter.HTML do
 
   defp copy_extras(config, extras) do
     for %{source_path: source_path, id: id} when source_path != nil <- extras,
-        ext = extension_name(source_path),
+        ext = Formatter.extension_name(source_path),
         ext == ".livemd" do
       output = "#{config.output}/#{id}#{ext}"
 
@@ -320,48 +237,6 @@ defmodule ExDoc.Formatter.HTML do
     }
   end
 
-  @doc """
-  Builds extra nodes by normalizing the config entries.
-  """
-  def build_extras(config, ext) do
-    groups = config.groups_for_extras
-
-    language =
-      case config.proglang do
-        :erlang -> ExDoc.Language.Erlang
-        _ -> ExDoc.Language.Elixir
-      end
-
-    source_url_pattern = config.source_url_pattern
-
-    autolink_opts = [
-      apps: config.apps,
-      deps: config.deps,
-      ext: ext,
-      extras: extra_paths(config),
-      language: language,
-      skip_undefined_reference_warnings_on: config.skip_undefined_reference_warnings_on,
-      skip_code_autolink_to: config.skip_code_autolink_to
-    ]
-
-    extras =
-      config.extras
-      |> Task.async_stream(
-        &build_extra(&1, groups, language, autolink_opts, source_url_pattern),
-        timeout: :infinity
-      )
-      |> Enum.map(&elem(&1, 1))
-
-    ids_count = Enum.reduce(extras, %{}, &Map.update(&2, &1.id, 1, fn c -> c + 1 end))
-
-    extras
-    |> Enum.map_reduce(1, fn extra, idx ->
-      if ids_count[extra.id] > 1, do: {disambiguate_id(extra, idx), idx + 1}, else: {extra, idx}
-    end)
-    |> elem(0)
-    |> Enum.sort_by(fn extra -> GroupMatcher.index(groups, extra.group) end)
-  end
-
   def generate_redirects(config, ext) do
     config.redirects
     |> Map.new()
@@ -381,90 +256,6 @@ defmodule ExDoc.Formatter.HTML do
     end)
   end
 
-  defp disambiguate_id(extra, discriminator) do
-    Map.put(extra, :id, "#{extra.id}-#{discriminator}")
-  end
-
-  defp build_extra({input, input_options}, groups, language, autolink_opts, source_url_pattern) do
-    input = to_string(input)
-    id = input_options[:filename] || input |> filename_to_title() |> Utils.text_to_id()
-    source_file = input_options[:source] || input
-    opts = [file: source_file, line: 1]
-
-    {source, ast} =
-      case extension_name(input) do
-        extension when extension in ["", ".txt"] ->
-          source = File.read!(input)
-          ast = [{:pre, [], "\n" <> source, %{}}]
-          {source, ast}
-
-        extension when extension in [".md", ".livemd", ".cheatmd"] ->
-          source = File.read!(input)
-
-          ast =
-            source
-            |> Markdown.to_ast(opts)
-            |> sectionize(extension)
-
-          {source, ast}
-
-        _ ->
-          raise ArgumentError,
-                "file extension not recognized, allowed extension is either .cheatmd, .livemd, .md, .txt or no extension"
-      end
-
-    {title_ast, ast} =
-      case ExDoc.DocAST.extract_title(ast) do
-        {:ok, title_ast, ast} -> {title_ast, ast}
-        :error -> {nil, ast}
-      end
-
-    title_text = title_ast && ExDoc.DocAST.text_from_ast(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)
-
-    source_path = source_file |> Path.relative_to(File.cwd!()) |> String.replace_leading("./", "")
-    source_url = Utils.source_url_pattern(source_url_pattern, source_path, 1)
-
-    %{
-      source: source,
-      content: content_html,
-      group: group,
-      id: id,
-      source_path: source_path,
-      source_url: source_url,
-      title: title,
-      title_content: title_html || title
-    }
-  end
-
-  defp build_extra(input, groups, language, autolink_opts, source_url_pattern) do
-    build_extra({input, []}, groups, language, autolink_opts, source_url_pattern)
-  end
-
-  defp extension_name(input) do
-    input
-    |> Path.extname()
-    |> String.downcase()
-  end
-
-  defp sectionize(ast, ".cheatmd") do
-    ExDoc.DocAST.sectionize(ast, fn
-      {:h2, _, _, _} -> true
-      {:h3, _, _, _} -> true
-      _ -> false
-    end)
-  end
-
-  defp sectionize(ast, _), do: ast
-
-  defp filename_to_title(input) do
-    input |> Path.basename() |> Path.rootname()
-  end
-
   @doc """
   Generates the logo from config into the given directory.
   """
@@ -522,14 +313,6 @@ defmodule ExDoc.Formatter.HTML do
     end
   end
 
-  def filter_list(:module, nodes) do
-    Enum.filter(nodes, &(&1.type != :task))
-  end
-
-  def filter_list(type, nodes) do
-    Enum.filter(nodes, &(&1.type == type))
-  end
-
   defp generate_list(nodes, nodes_map, config) do
     nodes
     |> Task.async_stream(&generate_module_page(&1, nodes_map, config), timeout: :infinity)
@@ -556,16 +339,4 @@ defmodule ExDoc.Formatter.HTML do
       config
     end
   end
-
-  defp extra_paths(config) do
-    Map.new(config.extras, fn
-      path when is_binary(path) ->
-        base = Path.basename(path)
-        {base, Utils.text_to_id(Path.rootname(base))}
-
-      {path, opts} ->
-        base = path |> to_string() |> Path.basename()
-        {base, opts[:filename] || Utils.text_to_id(Path.rootname(base))}
-    end)
-  end
 end
diff --git a/lib/ex_doc/formatter/markdown.ex b/lib/ex_doc/formatter/markdown.ex
index a41b8f775..b9bee4809 100644
--- a/lib/ex_doc/formatter/markdown.ex
+++ b/lib/ex_doc/formatter/markdown.ex
@@ -2,7 +2,7 @@ defmodule ExDoc.Formatter.MARKDOWN do
   @moduledoc false
 
   alias __MODULE__.{Templates}
-  alias ExDoc.Formatter.HTML
+  alias ExDoc.Formatter
   alias ExDoc.Utils
 
   @doc """
@@ -17,16 +17,18 @@ defmodule ExDoc.Formatter.MARKDOWN do
     File.mkdir_p!(config.output)
 
     project_nodes =
-      HTML.render_all(project_nodes, filtered_modules, ".md", config, highlight_tag: "samp")
+      project_nodes
+      # |> Enum.map(&elem(&1, 1))
+      |> Formatter.render_all(filtered_modules, ".md", config, highlight_tag: "samp")
 
     nodes_map = %{
-      modules: HTML.filter_list(:module, project_nodes),
-      tasks: HTML.filter_list(:task, project_nodes)
+      modules: Formatter.filter_list(:module, project_nodes),
+      tasks: Formatter.filter_list(:task, project_nodes)
     }
 
     extras =
       config
-      |> HTML.build_extras(".md")
+      |> Formatter.build_extras(".md")
       |> Enum.chunk_by(& &1.group)
       |> Enum.map(&{hd(&1).group, &1})
 
diff --git a/test/ex_doc/formatter/epub/templates_test.exs b/test/ex_doc/formatter/epub/templates_test.exs
index 9b387a8e0..28c68294f 100644
--- a/test/ex_doc/formatter/epub/templates_test.exs
+++ b/test/ex_doc/formatter/epub/templates_test.exs
@@ -28,7 +28,7 @@ defmodule ExDoc.Formatter.EPUB.TemplatesTest do
   defp get_module_page(names, config \\ []) do
     config = doc_config(config)
     {mods, []} = ExDoc.Retriever.docs_from_modules(names, config)
-    [mod | _] = HTML.render_all(mods, [], ".xhtml", config, highlight_tag: "samp")
+    [mod | _] = ExDoc.Formatter.render_all(mods, [], ".xhtml", config, highlight_tag: "samp")
     Templates.module_page(config, mod)
   end
 
diff --git a/test/ex_doc/formatter/html/templates_test.exs b/test/ex_doc/formatter/html/templates_test.exs
index 970e8431a..d13c79c92 100644
--- a/test/ex_doc/formatter/html/templates_test.exs
+++ b/test/ex_doc/formatter/html/templates_test.exs
@@ -32,7 +32,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
   defp get_module_page(names, context, config \\ []) do
     config = doc_config(context, config)
     {mods, []} = ExDoc.Retriever.docs_from_modules(names, config)
-    [mod | _] = HTML.render_all(mods, [], ".html", config, [])
+    [mod | _] = ExDoc.Formatter.render_all(mods, [], ".html", config, [])
     Templates.module_page(mod, @empty_nodes_map, config)
   end
 
@@ -428,7 +428,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
       names = [CompiledWithDocs, CompiledWithoutDocs, DuplicateHeadings]
       config = doc_config(context)
       {nodes, []} = ExDoc.Retriever.docs_from_modules(names, config)
-      nodes = HTML.render_all(nodes, [], ".html", config, [])
+      nodes = ExDoc.Formatter.render_all(nodes, [], ".html", config, [])
 
       [compiled_with_docs, compiled_without_docs, duplicate_headings] =
         create_sidebar_items(%{modules: nodes}, [])["modules"]
diff --git a/test/ex_doc/formatter/markdown/templates_test.exs b/test/ex_doc/formatter/markdown/templates_test.exs
index da44e965f..216f0098c 100644
--- a/test/ex_doc/formatter/markdown/templates_test.exs
+++ b/test/ex_doc/formatter/markdown/templates_test.exs
@@ -28,7 +28,7 @@ defmodule ExDoc.Formatter.MARKDOWN.TemplatesTest do
   defp get_module_page(names, config \\ []) do
     config = doc_config(config)
     {mods, []} = ExDoc.Retriever.docs_from_modules(names, config)
-    [mod | _] = HTML.render_all(mods, [], ".md", config, highlight_tag: "samp")
+    [mod | _] = ExDoc.Formatter.render_all(mods, [], ".md", config, highlight_tag: "samp")
     Templates.module_page(config, mod)
   end
 

From 7128381a8d271616cdc2f95ff824606360d1f1ad Mon Sep 17 00:00:00 2001
From: Mayel de Borniol <git@mayel.space>
Date: Fri, 27 Dec 2024 16:54:57 +0000
Subject: [PATCH 06/10] render spec links in md

---
 lib/ex_doc/autolink.ex        | 5 ++++-
 lib/ex_doc/language/elixir.ex | 6 +++++-
 lib/ex_doc/language/erlang.ex | 6 +++++-
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/lib/ex_doc/autolink.ex b/lib/ex_doc/autolink.ex
index 57d809e3b..32f4eb4ab 100644
--- a/lib/ex_doc/autolink.ex
+++ b/lib/ex_doc/autolink.ex
@@ -99,10 +99,13 @@ defmodule ExDoc.Autolink do
       if app in config.apps do
         path <> ext <> suffix
       else
+        #  TODO: remove this if/when hexdocs.pm starts including .md files
+        ext = ".html"
+
         config.deps
         |> Keyword.get_lazy(app, fn -> base_url <> "#{app}" end)
         |> String.trim_trailing("/")
-        |> Kernel.<>("/" <> path <> ".html" <> suffix)
+        |> Kernel.<>("/" <> path <> ext <> suffix)
       end
     else
       path <> ext <> suffix
diff --git a/lib/ex_doc/language/elixir.ex b/lib/ex_doc/language/elixir.ex
index 636cfa1a4..5ed9c1743 100644
--- a/lib/ex_doc/language/elixir.ex
+++ b/lib/ex_doc/language/elixir.ex
@@ -699,7 +699,11 @@ defmodule ExDoc.Language.Elixir do
         end
 
       if url do
-        ~s[<a href="#{url}">#{ExDoc.Utils.h(call_string)}</a>]
+        if config.ext == ".md" do
+          ~s[\[#{ExDoc.Utils.h(call_string)}\](#{url})]
+        else
+          ~s[<a href="#{url}">#{ExDoc.Utils.h(call_string)}</a>]
+        end
       else
         call_string
       end <> do_typespec(rest, config)
diff --git a/lib/ex_doc/language/erlang.ex b/lib/ex_doc/language/erlang.ex
index 5ed3ded85..5d94c9239 100644
--- a/lib/ex_doc/language/erlang.ex
+++ b/lib/ex_doc/language/erlang.ex
@@ -695,7 +695,11 @@ defmodule ExDoc.Language.Erlang do
         end
 
       if url do
-        ~s|<a href="#{url}">#{string}</a>(|
+        if config.ext == ".md" do
+          ~s|[#{string}\](#{url})(|
+        else
+          ~s|<a href="#{url}">#{string}</a>(|
+        end
       else
         string <> "("
       end

From 857e3165efc73fb71a6edd22aa86ea8a639e2e38 Mon Sep 17 00:00:00 2001
From: Mayel de Borniol <git@mayel.space>
Date: Fri, 27 Dec 2024 17:01:38 +0000
Subject: [PATCH 07/10] render img AST

---
 lib/ex_doc/doc_ast.ex | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/lib/ex_doc/doc_ast.ex b/lib/ex_doc/doc_ast.ex
index 1fd699745..fdb108f89 100644
--- a/lib/ex_doc/doc_ast.ex
+++ b/lib/ex_doc/doc_ast.ex
@@ -107,8 +107,12 @@ defmodule ExDoc.DocAST do
     fun.(ast, result)
   end
 
-  # @void_elements ~W(area base br col command embed hr img input keygen link
-  #   meta param source track wbr)a
+  def to_markdown_string({:img, attrs, _inner, _meta} = ast, fun) do
+    result = "![#{attrs[:alt]}](#{attrs[:src]} \"#{attrs[:title]}\")"
+    fun.(ast, result)
+  end
+
+  # ignoring these: area base col command embed input keygen link meta param source track wbr
   def to_markdown_string({tag, _attrs, _inner, _meta} = ast, fun) when tag in @void_elements do
     result = ""
     fun.(ast, result)

From eb3fbe9e7a96083c6b463809e7c2402871f84ee2 Mon Sep 17 00:00:00 2001
From: Mayel de Borniol <git@mayel.space>
Date: Fri, 27 Dec 2024 17:09:47 +0000
Subject: [PATCH 08/10] fix warnings

---
 lib/ex_doc/doc_ast.ex                                |  4 ++--
 lib/ex_doc/formatter.ex                              |  8 ++------
 lib/ex_doc/formatter/html.ex                         |  2 +-
 lib/ex_doc/formatter/markdown.ex                     | 12 ------------
 lib/ex_doc/formatter/markdown/templates.ex           |  6 +-----
 .../formatter/markdown/templates/module_template.eex |  2 +-
 test/ex_doc/formatter/epub/templates_test.exs        |  1 -
 test/ex_doc/formatter/html/templates_test.exs        |  1 -
 test/ex_doc/formatter/markdown/templates_test.exs    |  1 -
 test/ex_doc/formatter/markdown_test.exs              |  4 ----
 10 files changed, 7 insertions(+), 34 deletions(-)

diff --git a/lib/ex_doc/doc_ast.ex b/lib/ex_doc/doc_ast.ex
index fdb108f89..969df04f7 100644
--- a/lib/ex_doc/doc_ast.ex
+++ b/lib/ex_doc/doc_ast.ex
@@ -118,12 +118,12 @@ defmodule ExDoc.DocAST do
     fun.(ast, result)
   end
 
-  def to_markdown_string({tag, _attrs, inner, %{verbatim: true}} = ast, fun) do
+  def to_markdown_string({_tag, _attrs, inner, %{verbatim: true}} = ast, fun) do
     result = Enum.join(inner, "")
     fun.(ast, result)
   end
 
-  def to_markdown_string({tag, _attrs, inner, _meta} = ast, fun) do
+  def to_markdown_string({_tag, _attrs, inner, _meta} = ast, fun) do
     result = to_string(inner, fun)
     fun.(ast, result)
   end
diff --git a/lib/ex_doc/formatter.ex b/lib/ex_doc/formatter.ex
index 960e50705..9ffdd70c6 100644
--- a/lib/ex_doc/formatter.ex
+++ b/lib/ex_doc/formatter.ex
@@ -1,12 +1,8 @@
 defmodule ExDoc.Formatter do
   @moduledoc false
 
-  alias __MODULE__.{Assets, Templates, SearchData}
   alias ExDoc.{Markdown, GroupMatcher, Utils}
 
-  @main "api-reference"
-  @assets_dir "assets"
-
   @doc """
   Autolinks and renders all docs.
   """
@@ -63,7 +59,7 @@ defmodule ExDoc.Formatter do
     |> Enum.map(&elem(&1, 1))
   end
 
-  defp render_doc(%{doc: nil} = node, ext, _language, _autolink_opts, _opts),
+  defp render_doc(%{doc: nil} = node, _ext, _language, _autolink_opts, _opts),
     do: node
 
   defp render_doc(%{doc: doc} = node, ext, language, autolink_opts, opts) do
@@ -83,7 +79,7 @@ defmodule ExDoc.Formatter do
     mod_id <> "." <> id
   end
 
-  defp autolink_and_render(doc, ".md", language, autolink_opts, opts) do
+  defp autolink_and_render(doc, ".md", language, autolink_opts, _opts) do
     doc
     |> language.autolink_doc(autolink_opts)
     |> ExDoc.DocAST.to_markdown_string()
diff --git a/lib/ex_doc/formatter/html.ex b/lib/ex_doc/formatter/html.ex
index 458a302dc..32cb19f05 100644
--- a/lib/ex_doc/formatter/html.ex
+++ b/lib/ex_doc/formatter/html.ex
@@ -2,7 +2,7 @@ defmodule ExDoc.Formatter.HTML do
   @moduledoc false
 
   alias __MODULE__.{Assets, Templates, SearchData}
-  alias ExDoc.{Formatter, Markdown, GroupMatcher, Utils}
+  alias ExDoc.{Formatter, Utils}
 
   @main "api-reference"
   @assets_dir "assets"
diff --git a/lib/ex_doc/formatter/markdown.ex b/lib/ex_doc/formatter/markdown.ex
index b9bee4809..10fd19514 100644
--- a/lib/ex_doc/formatter/markdown.ex
+++ b/lib/ex_doc/formatter/markdown.ex
@@ -92,18 +92,6 @@ defmodule ExDoc.Formatter.MARKDOWN do
 
   ## Helpers
 
-  defp files_to_add(path) do
-    Enum.reduce(Path.wildcard(Path.join(path, "**/*")), [], fn file, acc ->
-      case File.read(file) do
-        {:ok, bin} ->
-          [{file |> Path.relative_to(path) |> String.to_charlist(), bin} | acc]
-
-        {:error, _} ->
-          acc
-      end
-    end)
-  end
-
   defp generate_module_page(module_node, config) do
     content =
       Templates.module_page(config, module_node)
diff --git a/lib/ex_doc/formatter/markdown/templates.ex b/lib/ex_doc/formatter/markdown/templates.ex
index da963103b..4e873e05f 100644
--- a/lib/ex_doc/formatter/markdown/templates.ex
+++ b/lib/ex_doc/formatter/markdown/templates.ex
@@ -85,13 +85,9 @@ defmodule ExDoc.Formatter.MARKDOWN.Templates do
     |> elem(0)
   end
 
-  @class_regex ~r/<h[23].*?(\sclass="(?<class>[^"]+)")?.*?>/
-  @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"
-
+  defp link_heading(_match, _tag, title, id, prefix) do
     # The Markdown syntax that we support for the admonition text
     # blocks is something like this:
     #
diff --git a/lib/ex_doc/formatter/markdown/templates/module_template.eex b/lib/ex_doc/formatter/markdown/templates/module_template.eex
index 5bbd4f2b9..0972a5f35 100644
--- a/lib/ex_doc/formatter/markdown/templates/module_template.eex
+++ b/lib/ex_doc/formatter/markdown/templates/module_template.eex
@@ -13,7 +13,7 @@
 <%= for {name, nodes} <- summary, do: summary_template(name, nodes) %>
 <% end %>
 
-<%= for {name, nodes} <- summary, key = text_to_id(name) do %>
+<%= for {name, nodes} <- summary, _key = text_to_id(name) do %>
 ## <%=h to_string(name) %>
 <%= for node <- nodes, do: detail_template(node, module) %>
 <% end %>
diff --git a/test/ex_doc/formatter/epub/templates_test.exs b/test/ex_doc/formatter/epub/templates_test.exs
index 28c68294f..0580586b1 100644
--- a/test/ex_doc/formatter/epub/templates_test.exs
+++ b/test/ex_doc/formatter/epub/templates_test.exs
@@ -1,7 +1,6 @@
 defmodule ExDoc.Formatter.EPUB.TemplatesTest do
   use ExUnit.Case, async: true
 
-  alias ExDoc.Formatter.HTML
   alias ExDoc.Formatter.EPUB.Templates
 
   defp source_url do
diff --git a/test/ex_doc/formatter/html/templates_test.exs b/test/ex_doc/formatter/html/templates_test.exs
index d13c79c92..4c72d50ea 100644
--- a/test/ex_doc/formatter/html/templates_test.exs
+++ b/test/ex_doc/formatter/html/templates_test.exs
@@ -1,7 +1,6 @@
 defmodule ExDoc.Formatter.HTML.TemplatesTest do
   use ExUnit.Case, async: true
 
-  alias ExDoc.Formatter.HTML
   alias ExDoc.Formatter.HTML.Templates
 
   @moduletag :tmp_dir
diff --git a/test/ex_doc/formatter/markdown/templates_test.exs b/test/ex_doc/formatter/markdown/templates_test.exs
index 216f0098c..b3c257ff2 100644
--- a/test/ex_doc/formatter/markdown/templates_test.exs
+++ b/test/ex_doc/formatter/markdown/templates_test.exs
@@ -1,7 +1,6 @@
 defmodule ExDoc.Formatter.MARKDOWN.TemplatesTest do
   use ExUnit.Case, async: true
 
-  alias ExDoc.Formatter.HTML
   alias ExDoc.Formatter.MARKDOWN.Templates
 
   defp source_url do
diff --git a/test/ex_doc/formatter/markdown_test.exs b/test/ex_doc/formatter/markdown_test.exs
index 9688f5130..262d7fbcd 100644
--- a/test/ex_doc/formatter/markdown_test.exs
+++ b/test/ex_doc/formatter/markdown_test.exs
@@ -1,10 +1,6 @@
 defmodule ExDoc.Formatter.MARKDOWNTest do
   use ExUnit.Case, async: false
 
-  import ExUnit.CaptureIO
-
-  alias ExDoc.Utils
-
   @moduletag :tmp_dir
 
   @before_closing_body_tag_content_md "UNIQUE:<dont-escape>&copy;BEFORE-CLOSING-BODY-TAG-HTML</dont-escape>"

From 6c3a8099825ab9690da934d9c0831780fc3de9d8 Mon Sep 17 00:00:00 2001
From: Mayel de Borniol <git@mayel.space>
Date: Sun, 5 Jan 2025 13:21:23 +0000
Subject: [PATCH 09/10] clean up

---
 lib/ex_doc/formatter/markdown/templates.ex     | 18 +++++-------------
 .../markdown/templates/module_template.eex     |  2 +-
 2 files changed, 6 insertions(+), 14 deletions(-)

diff --git a/lib/ex_doc/formatter/markdown/templates.ex b/lib/ex_doc/formatter/markdown/templates.ex
index 4e873e05f..08f66113f 100644
--- a/lib/ex_doc/formatter/markdown/templates.ex
+++ b/lib/ex_doc/formatter/markdown/templates.ex
@@ -41,21 +41,13 @@ defmodule ExDoc.Formatter.MARKDOWN.Templates do
   """
   @spec synopsis(String.t()) :: String.t()
   @spec synopsis(nil) :: nil
-  def synopsis(nil), do: nil
-
   def synopsis(doc) when is_binary(doc) do
-    doc =
-      case :binary.split(doc, "</p>") do
-        [left, _] -> String.trim_trailing(left, ": ")
-        [all] -> all
-      end
-
-    # Remove any anchors found in synopsis.
-    # Old Erlang docs placed anchors at the top of the documentation
-    # for links. Ideally they would have been removed but meanwhile
-    # it is simpler to guarantee they won't be duplicated in docs.
-    Regex.replace(~r|(<[^>]*) id="[^"]*"([^>]*>)|, doc, ~S"\1\2", [])
+    case :binary.split(doc, "\n\n") do
+      [left, _] -> String.trim_trailing(left, ": ")
+      [all] -> all
+    end
   end
+  def synopsis(_), do: nil
 
   @doc """
   Add link headings for the given `content`.
diff --git a/lib/ex_doc/formatter/markdown/templates/module_template.eex b/lib/ex_doc/formatter/markdown/templates/module_template.eex
index 0972a5f35..8af1d30fa 100644
--- a/lib/ex_doc/formatter/markdown/templates/module_template.eex
+++ b/lib/ex_doc/formatter/markdown/templates/module_template.eex
@@ -9,7 +9,7 @@
 <% end %>
 
 <%= if summary != [] do %>
-### Summary</h1>
+## Summary
 <%= for {name, nodes} <- summary, do: summary_template(name, nodes) %>
 <% end %>
 

From f552c02dbd08a75b9fec2d8dd0f23a985f5882a3 Mon Sep 17 00:00:00 2001
From: Mayel de Borniol <git@mayel.space>
Date: Mon, 6 Jan 2025 13:13:18 +0000
Subject: [PATCH 10/10] templates & rendering improvements, in part copied from
 https://github.com/elixir-lang/ex_doc/pull/1992

---
 lib/ex_doc/formatter/markdown/templates.ex    | 54 +++++--------------
 .../markdown/templates/detail_template.eex    | 18 +++----
 .../markdown/templates/module_template.eex    | 26 +++++++--
 .../markdown/templates/nav_item_template.eex  |  2 +-
 .../markdown/templates/nav_template.eex       |  2 +-
 .../markdown/templates/summary_template.eex   |  6 ++-
 .../formatter/markdown/templates_test.exs     |  8 +--
 test/ex_doc/formatter/markdown_test.exs       |  2 +-
 8 files changed, 51 insertions(+), 67 deletions(-)

diff --git a/lib/ex_doc/formatter/markdown/templates.ex b/lib/ex_doc/formatter/markdown/templates.ex
index 08f66113f..a34d489df 100644
--- a/lib/ex_doc/formatter/markdown/templates.ex
+++ b/lib/ex_doc/formatter/markdown/templates.ex
@@ -43,63 +43,35 @@ defmodule ExDoc.Formatter.MARKDOWN.Templates do
   @spec synopsis(nil) :: nil
   def synopsis(doc) when is_binary(doc) do
     case :binary.split(doc, "\n\n") do
-      [left, _] -> String.trim_trailing(left, ": ")
+      [left, _] -> String.trim_trailing(left, ": ") <> "\n\n"
       [all] -> all
     end
   end
-  def synopsis(_), do: nil
-
-  @doc """
-  Add link headings for the given `content`.
 
-  IDs are prefixed with `prefix`.
-
-  We only link `h2` and `h3` headers. This is kept consistent in ExDoc.SearchData.
-  """
-  @heading_regex ~r/<(h[23]).*?>(.*?)<\/\1>/m
-  @spec link_headings(String.t() | nil, String.t()) :: String.t() | nil
-  def link_headings(content, prefix \\ "")
-  def link_headings(nil, _), do: nil
+  def synopsis(_), do: nil
 
-  def link_headings(content, prefix) do
+  @heading_regex ~r/^(\#{1,6})\s+(.*)/m
+  defp rewrite_headings(content) when is_binary(content) do
     @heading_regex
     |> Regex.scan(content)
-    |> Enum.reduce({content, %{}}, fn [match, tag, title], {content, occurrences} ->
-      possible_id = text_to_id(title)
-      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}
+    |> Enum.reduce(content, fn [match, level, title], content ->
+      replacement = rewrite_heading(level, title)
+      String.replace(content, match, replacement, global: false)
     end)
-    |> elem(0)
   end
 
-  defp link_heading(match, _tag, _title, "", _prefix), do: match
+  defp rewrite_headings(_), do: nil
 
-  defp link_heading(_match, _tag, title, id, prefix) do
-    # The Markdown syntax that we support for the admonition text
-    # blocks is something like this:
-    #
-    #     > ### Never open this door! {: .warning}
-    #     >
-    #     > ...
-    #
+  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
     """
-    ## [#{title}](##{prefix}#{id})
+    #{level} #{title}
     """
   end
 
-  def link_moduledoc_headings(content) do
-    link_headings(content, "module-")
-  end
-
-  def link_detail_headings(content, prefix) do
-    link_headings(content, prefix <> "-")
-  end
+  defp enc(binary), do: URI.encode(binary) |> String.replace("/", "-")
 
   @doc """
   Creates a chapter which contains all the details about an individual module.
diff --git a/lib/ex_doc/formatter/markdown/templates/detail_template.eex b/lib/ex_doc/formatter/markdown/templates/detail_template.eex
index 033065073..7529996c8 100644
--- a/lib/ex_doc/formatter/markdown/templates/detail_template.eex
+++ b/lib/ex_doc/formatter/markdown/templates/detail_template.eex
@@ -1,21 +1,15 @@
-# <%=h node.signature %>
-
-<%= if node.source_url do %>
-[View Source](<%= node.source_url %>)
-<% end %>
-
-<%= for annotation <- node.annotations do %>
-> (<%= annotation %>)
-<% end %>
+<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 %>
 
 <%= if deprecated = node.deprecated do %>
 > This <%= node.type %> is deprecated. <%= h(deprecated) %>.
 <% end %>
 
 <%= if node.specs != [] do %>
-<%= for spec <- node.specs do %>
-> <%= H.format_spec_attribute(module, node) %>: <%= spec %>
+<%= for spec <- node.specs do %> 
+> <%= H.format_spec_attribute(module, node) %> <%= spec %>
 <% end %>
 <% end %>
 
-<%= link_detail_headings(node_doc(node), H.enc(node.id)) %>
+<%= rewrite_headings(node_doc(node)) %>
+
diff --git a/lib/ex_doc/formatter/markdown/templates/module_template.eex b/lib/ex_doc/formatter/markdown/templates/module_template.eex
index 8af1d30fa..c21285350 100644
--- a/lib/ex_doc/formatter/markdown/templates/module_template.eex
+++ b/lib/ex_doc/formatter/markdown/templates/module_template.eex
@@ -1,20 +1,36 @@
-# <%= module.title %> <%= module_type(module) %>
+# <%= module.title %> <%= module_type(module) %> (<%= config.project %> v<%= config.version %>)
+
+<%= 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 %>
-<%= H.link_moduledoc_headings(doc) %>
+<%= doc %>
 <% end %>
 
 <%= if summary != [] do %>
-## Summary
+## 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) %>
-<%= for node <- nodes, do: detail_template(node, module) %>
+
+### <%=h to_string(name) %>
+
+<%= 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) %>
diff --git a/lib/ex_doc/formatter/markdown/templates/nav_item_template.eex b/lib/ex_doc/formatter/markdown/templates/nav_item_template.eex
index aaa568662..449c46e22 100644
--- a/lib/ex_doc/formatter/markdown/templates/nav_item_template.eex
+++ b/lib/ex_doc/formatter/markdown/templates/nav_item_template.eex
@@ -1,6 +1,6 @@
 <%= unless Enum.empty?(nodes) do %>
 - <%= name %>
 <%= for node <- nodes do %>
-1. [<%=h node.title %>](<%= URI.encode node.id %>.md)
+  - [<%=h node.title %>](<%= URI.encode node.id %>.md)
 <% end %>
 <% end %>
diff --git a/lib/ex_doc/formatter/markdown/templates/nav_template.eex b/lib/ex_doc/formatter/markdown/templates/nav_template.eex
index aa35d02df..48f11c99a 100644
--- a/lib/ex_doc/formatter/markdown/templates/nav_template.eex
+++ b/lib/ex_doc/formatter/markdown/templates/nav_template.eex
@@ -1,4 +1,4 @@
-# Table of contents
+# <%= config.project %> v<%= config.version %> - Documentation - Table of contents
 
 <%= nav_grouped_item_template config.extras  %>
 <%= unless Enum.empty?(nodes.modules) do %>
diff --git a/lib/ex_doc/formatter/markdown/templates/summary_template.eex b/lib/ex_doc/formatter/markdown/templates/summary_template.eex
index 52215651c..7d8ffcb7b 100644
--- a/lib/ex_doc/formatter/markdown/templates/summary_template.eex
+++ b/lib/ex_doc/formatter/markdown/templates/summary_template.eex
@@ -1,7 +1,8 @@
-## <%= name %>
+### <%= name %>
+
 <%= for node <- nodes do %>
 
-### <%=h node.signature %>
+#### [`<%=h node.signature %>`](#<%= enc node.id %>)
 
 <%= if deprecated = node.deprecated do %>
 > <%= h(deprecated) %>
@@ -10,4 +11,5 @@
 <%= if doc = node_doc(node) do %>
 <%= synopsis(doc) %>
 <% end %>
+
 <% end %>
diff --git a/test/ex_doc/formatter/markdown/templates_test.exs b/test/ex_doc/formatter/markdown/templates_test.exs
index b3c257ff2..0a442ed4e 100644
--- a/test/ex_doc/formatter/markdown/templates_test.exs
+++ b/test/ex_doc/formatter/markdown/templates_test.exs
@@ -56,20 +56,20 @@ defmodule ExDoc.Formatter.MARKDOWN.TemplatesTest do
 
       assert content =~ ~r{#\s*CompiledWithDocs\s*}
 
-      assert content =~ ~s{# Summary</h1>}
+      assert content =~ ~s{## Table of Contents}
 
       assert content =~
-               ~r{## .*Example.*}ms
+               ~r{\n## .*Example.*}ms
 
       assert content =~
-               ~r{### .*Example H3 heading.*}ms
+               ~r{\n### .*Example H3 heading.*}ms
 
       assert content =~
                ~r{moduledoc.*Example.*CompiledWithDocs\.example.*}ms
 
       assert content =~ ~r{Some example}ms
       assert content =~ ~r{example_without_docs().*}ms
-      assert content =~ ~r{example_1().*> \(macro\)}ms
+      assert content =~ ~r{example_1().* \(macro\)}ms
 
       assert content =~ ~s{example(foo, bar \\\\ Baz)}
     end
diff --git a/test/ex_doc/formatter/markdown_test.exs b/test/ex_doc/formatter/markdown_test.exs
index 262d7fbcd..99ae3d7f4 100644
--- a/test/ex_doc/formatter/markdown_test.exs
+++ b/test/ex_doc/formatter/markdown_test.exs
@@ -72,6 +72,6 @@ defmodule ExDoc.Formatter.MARKDOWNTest do
              ~r{\n`TypesAndSpecs.Sub`\n}
 
     content = File.read!(tmp_dir <> "/markdown/index.md")
-    assert content =~ "# Table of contents\n\n  - [README](readme.md)"
+    assert content =~ "Table of contents\n\n  - [README](readme.md)"
   end
 end