Refactor markdown formatter to improve output setup and file generation logic. Introduced a build file to manage markdown file cleanup and generation, ensuring only relevant files are removed. Updated file writing methods for consistency and clarity.

Author: yordis

lib/ex_doc/formatter/markdown.ex

@@ -13,8 +13,8 @@ defmodule ExDoc.Formatter.Markdown do
     Utils.unset_warned()
 
     config = normalize_config(config)
-    File.rm_rf!(config.output)
-    File.mkdir_p!(config.output)
+    build = Path.join(config.output, ".build-markdown")
+    output_setup(build, config)
 
     extras = Formatter.build_extras(config, ".md")
 
@@ -29,12 +29,14 @@ defmodule ExDoc.Formatter.Markdown do
 
     config = %{config | extras: extras}
 
-    generate_nav(config, nodes_map)
-    generate_extras(config)
-    generate_list(config, nodes_map.modules)
-    generate_list(config, nodes_map.tasks)
-    generate_llm_index(config, nodes_map)
+    all_files =
+      [generate_nav(config, nodes_map)] ++
+      generate_extras(config) ++
+      generate_list(config, nodes_map.modules) ++
+      generate_list(config, nodes_map.tasks) ++
+      [generate_llm_index(config, nodes_map)]
 
+    generate_build(List.flatten(all_files), build)
     config.output |> Path.join("index.md") |> Path.relative_to_cwd()
   end
 
@@ -43,6 +45,40 @@ defmodule ExDoc.Formatter.Markdown do
     %{config | output: output}
   end
 
+  defp output_setup(build, config) do
+    if File.exists?(build) do
+      build
+      |> File.read!()
+      |> String.split("\n", trim: true)
+      |> Enum.map(&Path.join(config.output, &1))
+      |> Enum.each(&File.rm/1)
+
+      File.rm(build)
+    else
+      # Only remove markdown files, not HTML/EPUB files
+      File.mkdir_p!(config.output)
+      if File.exists?(config.output) do
+        config.output
+        |> Path.join("*.md")
+        |> Path.wildcard()
+        |> Enum.each(&File.rm/1)
+
+        llms_file = Path.join(config.output, "llms.txt")
+        if File.exists?(llms_file), do: File.rm(llms_file)
+      end
+    end
+  end
+
+  defp generate_build(files, build) do
+    entries =
+      files
+      |> Enum.uniq()
+      |> Enum.sort()
+      |> Enum.map(&[&1, "\n"])
+
+    File.write!(build, entries)
+  end
+
   defp normalize_output(output) do
     output
     |> String.replace(~r/\r\n?/, "\n")
@@ -59,20 +95,24 @@ defmodule ExDoc.Formatter.Markdown do
       Templates.nav_template(config, nodes)
       |> normalize_output()
 
-    File.write("#{config.output}/index.md", content)
+    filename = "index.md"
+    File.write("#{config.output}/#{filename}", content)
+    filename
   end
 
   defp generate_extras(config) do
-    for {_title, extras} <- config.extras do
-      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
+    for {_title, extras} <- config.extras,
+        %{id: id, source: content} <- extras,
+        not is_map_key(%{id: id, source: content}, :url) do
+      filename = "#{id}.md"
+      output = "#{config.output}/#{filename}"
+
+      if File.regular?(output) do
+        Utils.warn("file #{Path.relative_to_cwd(output)} already exists", [])
+      end
 
-        File.write!(output, normalize_output(content))
-      end)
+      File.write!(output, normalize_output(content))
+      filename
     end
   end
 
@@ -89,12 +129,16 @@ defmodule ExDoc.Formatter.Markdown do
       Templates.module_page(config, module_node)
       |> normalize_output()
 
-    File.write("#{config.output}/#{module_node.id}.md", content)
+    filename = "#{module_node.id}.md"
+    File.write("#{config.output}/#{filename}", content)
+    filename
   end
 
   defp generate_llm_index(config, nodes_map) do
     content = generate_llm_index_content(config, nodes_map)
-    File.write("#{config.output}/llms.txt", content)
+    filename = "llms.txt"
+    File.write("#{config.output}/#{filename}", content)
+    filename
   end
 
   defp generate_llm_index_content(config, nodes_map) do