feat: add Markdown formatter #2148

yordis · 2025-10-02T21:39:46Z

Signed-off-by: Yordis Prieto yordis.prieto@gmail.com

test/ex_doc/formatter/markdown_test.exs

github-actions · 2025-10-02T21:41:00Z

📦 Docs artifacts are ready: https://github.com/elixir-lang/ex_doc/actions/runs/18916968511/artifacts/4408945305

yordis · 2025-10-06T17:12:58Z

@josevalim any thoughts here thus far?

josevalim · 2025-10-06T17:14:02Z

Sorry, a bit busy with Elixir v1.19-rc and today I was out of focus. It is in my inbox and I will review it as soon as I can.

leandrocp

Hey @yordis that's amazing! Let me share some ideas that could be useful.

I was inspecting the generated Markdown files and thinking if we could apply some changes. See the differences here https://gist.github.com/leandrocp/ee4f0ba8325b410b8650ccd26b9b2351 (CompiledWithDocs.md vs CompiledWithDocs_PROPOSAL.md)

Use frontmatter block to describe global values/notes
Use the format "Summary / Functions" similar to HTML pages (so Functions become a level 2 heading)
Include source links
Reorganize metadata, for eg: add (deprecated) and doc in summary
Remove links to hexdocs.pm because 1) it breaks the content and I guess that would make it harder for LLMs to parse; 2) I'm not sure it should link to html pages

You can see some examples on https://shopify.dev/docs/api/liquid/basics.md and https://vercel.com/docs/rest-api/reference/sdk.md

lib/ex_doc/doc_ast.ex

lib/ex_doc/formatter/markdown/templates.ex

yordis · 2025-10-08T19:14:54Z

@leandrocp thanks for the help, about the formatting, I do not have any strong opinions of the final output, I will leave it to @josevalim and you to decide on that front, I can adjust it

josevalim · 2025-10-09T11:26:14Z

Just a heads up I am on holidays. This is still on top of my list but I cannot promise anything until I am back (next Wednesday). Sorry!

leandrocp · 2025-10-09T11:38:09Z

Hey @yordis no strong opinions either, just trying to figure out a format that presents all the info.

Regarding links, just to be clear it should contain links eventually but I believe that HexDocs must define how to serve Markdown pages first, for eg something like https://hexdocs.pm/elixir/1.18.4/Enum.md

josevalim · 2025-10-09T12:18:03Z

Some additional context: ExDoc is not tied to HexDocs and vice versa. We should design links with the assumptions it is served by any static host. I am thinking just using Enum.md with an anchor, same as html, is fine though? The anchor won’t actually work, but at least it is some context?

leandrocp · 2025-10-09T12:33:21Z

just using Enum.md with an anchor, same as html, is fine though?

Yeah it seems appropriate.

Shopify docs links to "canonical" URLs, for eg in https://shopify.dev/docs/api/liquid/tags/form you can see a bunch of anchor links, but in the .md docs (https://shopify.dev/docs/api/liquid/tags/form.md) they are rendered as [`cart`](https://shopify.dev/docs/api/liquid/tags/form#form-cart)

Vercel is not much different, they include relative links inside .md docs, for eg [Deployments Automation](/examples/deployments-automation)

Claude use relative links with anchors, for eg in https://docs.claude.com/en/docs/build-with-claude/prompt-caching you can see a link <a href="#pricing" class="link">at additional cost</a> which is rendered as [at additional cost](#pricing) in the .md docs (https://docs.claude.com/en/docs/build-with-claude/prompt-caching.md)

lib/ex_doc/formatter/markdown/templates.ex

lib/ex_doc/doc_ast.ex

josevalim · 2025-10-17T13:49:17Z

I am back. My goal is to release the new hexdocs.pm, review #2055, and then focus on this.

yordis · 2025-10-17T18:08:07Z

I am around, once you folks aligned, please share a action-driven feedback, I am can put the work on

lib/ex_doc/formatter/markdown.ex

lib/ex_doc/doc_ast.ex

lib/ex_doc/formatter.ex

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

… function calls

…rgument and updating related calls

…ation synopses for Markdown

…c_ast.ex and templates.ex

yordis · 2025-10-29T17:35:04Z

@josevalim could you give a second pass to the code review 🙏🏻

…nd Markdown templates

…n EPUB templates

eksperimental · 2025-10-30T13:45:26Z

lib/ex_doc/formatter/markdown.ex

@@ -0,0 +1,177 @@
+defmodule ExDoc.Formatter.MARKDOWN do


This doesn't follow the naming convention.

Suggested change

defmodule ExDoc.Formatter.MARKDOWN do

defmodule ExDoc.Formatter.Markdown do

@eksperimental I had the same reaction, but there is code path that assume the module as all uppercase, so I had to rollback to this. I will fix at some point

eksperimental · 2025-10-30T13:46:14Z

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

+<%= if deprecated = node.deprecated do %>
+> This <%= node.type %> is deprecated. <%= h(deprecated) %>.
+<% end %>
+


Suggested change

<%= if deprecated = node.deprecated do %>

> This <%= node.type %> is deprecated. <%= h(deprecated) %>.

<% end %>

<%= if deprecated = node.deprecated do %>

> This <%= node.type %> is deprecated. <%= h(deprecated) %>.

<% end %>

eksperimental · 2025-10-30T13:46:39Z

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

+<%= if deprecated = module.deprecated do %>
+> This <%= module.type %> is deprecated. <%=h deprecated %>.
+<% end %>
+


Suggested change

<%= if deprecated = module.deprecated do %>

> This <%= module.type %> is deprecated. <%=h deprecated %>.

<% end %>

<%= if deprecated = module.deprecated do %>

> This <%= module.type %> is deprecated. <%=h deprecated %>.

<% end %>

eksperimental · 2025-10-30T13:47:32Z

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

+<%= for {name, nodes} <- summary, _key = text_to_id(name) do %>
+
+### <%=h to_string(name) %>


Suggested change

<%= for {name, nodes} <- summary, _key = text_to_id(name) do %>

### <%=h to_string(name) %>

<%= for {name, nodes} <- summary, _key = text_to_id(name) do %>

### <%=h to_string(name) %>

eksperimental · 2025-10-30T13:48:08Z

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

+<%= if deprecated = node.deprecated do %>
+> <%= h(deprecated) %>
+<% end %>
+


Suggested change

<%= if deprecated = node.deprecated do %>

> <%= h(deprecated) %>

<% end %>

<%= if deprecated = node.deprecated do %>

> <%= h(deprecated) %>

<% end %>

eksperimental · 2025-10-30T14:05:28Z

lib/ex_doc/formatter/markdown/templates.ex

+
+  def node_synopsis(_), do: nil
+
+  # Extract synopsis as DocAST (similar to ExDoc.DocAST.synopsis but returns AST instead of HTML string)


Suggested change

# Extract synopsis as DocAST (similar to ExDoc.DocAST.synopsis but returns AST instead of HTML string)

# Extract synopsis as DocAST (similar to ExDoc.DocAST.synopsis but returns an AST instead of an HTML string).

eksperimental · 2025-10-30T14:17:27Z

lib/ex_doc/formatter/markdown/templates.ex

+  @spec synopsis(nil) :: nil
+  def synopsis(doc) when is_binary(doc) do
+    case :binary.split(doc, "\n\n") do
+      [left, _] -> String.trim_trailing(left, ": ") <> "\n\n"


String.trim_trailing/2 does not strip every character in the second argument.
Also note that String.trim_trailing/1 removes all Unicode white-spaces, so it's better to use that. There's an edgecase that will not be covered though "foo : : :"

Suggested change

[left, _] -> String.trim_trailing(left, ": ") <> "\n\n"

[left, _] -> String.trim_trailing(left) |> String.trim_trailing(left, ":") <> "\n\n"

eksperimental · 2025-10-30T14:21:04Z

lib/ex_doc/formatter/markdown/templates.ex

+  @heading_regex ~r/^(\#{1,6})\s+(.*)/m
+  defp rewrite_headings(content) when is_binary(content) do
+    @heading_regex


Storing regular expressions in module attributes has been deprecated in Elixir v1.19.

Suggested change

@heading_regex ~r/^(\#{1,6})\s+(.*)/m

defp rewrite_headings(content) when is_binary(content) do

@heading_regex

defp rewrite_headings(content) when is_binary(content) do

~r/^(\#{1,6})\s+(.*)/m

eksperimental · 2025-10-30T14:24:23Z

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

@@ -0,0 +1,9 @@
+# <%= config.project %> v<%= config.version %> - Documentation - Table of contents


Suggested change

# <%= config.project %> v<%= config.version %> - Documentation - Table of contents

# <%= config.project %> v<%= config.version %> - Documentation - Table of Contents

eksperimental · 2025-10-30T14:24:37Z

test/ex_doc/formatter/markdown_test.exs

+    generate_docs(doc_config(context))
+
+    content = File.read!(tmp_dir <> "/markdown/index.md")
+    assert content =~ ~r{^# Elixir v1\.0\.1 - Documentation - Table of contents$}m


Suggested change

assert content =~ ~r{^# Elixir v1\.0\.1 - Documentation - Table of contents$}m

assert content =~ ~r{^# Elixir v1\.0\.1 - Documentation - Table of Contents$}m

yordis commented Oct 2, 2025

View reviewed changes

test/ex_doc/formatter/markdown_test.exs Show resolved Hide resolved

leandrocp reviewed Oct 7, 2025

View reviewed changes

lib/ex_doc/doc_ast.ex Outdated Show resolved Hide resolved

lib/ex_doc/formatter/markdown/templates.ex Show resolved Hide resolved

yordis force-pushed the yordis/add-markdown-formatter branch from e1c6f8f to a6870e3 Compare October 8, 2025 19:10

yordis marked this pull request as ready for review October 8, 2025 19:12

yordis requested a review from josevalim October 8, 2025 19:14

yordis force-pushed the yordis/add-markdown-formatter branch from a6870e3 to 5131f1a Compare October 8, 2025 19:16

eksperimental suggested changes Oct 13, 2025

View reviewed changes

josevalim reviewed Oct 27, 2025

View reviewed changes

lib/ex_doc/formatter/markdown.ex Outdated Show resolved Hide resolved

josevalim reviewed Oct 27, 2025

View reviewed changes

lib/ex_doc/formatter/markdown.ex Outdated Show resolved Hide resolved

josevalim reviewed Oct 27, 2025

View reviewed changes

lib/ex_doc/doc_ast.ex Outdated Show resolved Hide resolved

josevalim reviewed Oct 27, 2025

View reviewed changes

lib/ex_doc/formatter.ex Outdated Show resolved Hide resolved

yordis added 5 commits October 29, 2025 12:21

feat: add Markdown formatter

c6e237a

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

fix

7297cd3

refactor: rename to_markdown_string to to_markdown and update related…

1e5c09f

… function calls

refactor: simplify to_markdown function by removing post-processing a…

b4a4ba5

…rgument and updating related calls

feat: implement node_synopsis function to extract and format document…

9770ce7

…ation synopses for Markdown

yordis force-pushed the yordis/add-markdown-formatter branch from 5131f1a to 9770ce7 Compare October 29, 2025 16:49

style: update comments for clarity and improve code readability in do…

97cdfa0

…c_ast.ex and templates.ex

yordis requested a review from josevalim October 29, 2025 17:35

yordis requested a review from eksperimental October 29, 2025 17:35

yordis added 2 commits October 29, 2025 13:35

style: add period to documentation comments for consistency in EPUB a…

c1970a7

…nd Markdown templates

style: add period to documentation comment for module_page function i…

abe0e26

…n EPUB templates

eksperimental suggested changes Oct 30, 2025

View reviewed changes

	defmodule ExDoc.Formatter.MARKDOWN do
	defmodule ExDoc.Formatter.Markdown do

		<%= for {name, nodes} <- summary, _key = text_to_id(name) do %>

		### <%=h to_string(name) %>


		def node_synopsis(_), do: nil

		# Extract synopsis as DocAST (similar to ExDoc.DocAST.synopsis but returns AST instead of HTML string)

	[left, _] -> String.trim_trailing(left, ": ") <> "\n\n"
	[left, _] -> String.trim_trailing(left) \|> String.trim_trailing(left, ":") <> "\n\n"

		@@ -0,0 +1,9 @@
		# <%= config.project %> v<%= config.version %> - Documentation - Table of contents

	assert content =~ ~r{^# Elixir v1\.0\.1 - Documentation - Table of contents$}m
	assert content =~ ~r{^# Elixir v1\.0\.1 - Documentation - Table of Contents$}m

feat: add Markdown formatter #2148

Are you sure you want to change the base?

feat: add Markdown formatter #2148

Conversation

yordis commented Oct 2, 2025

Uh oh!

Uh oh!

github-actions bot commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yordis commented Oct 6, 2025

Uh oh!

josevalim commented Oct 6, 2025

Uh oh!

leandrocp left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

yordis commented Oct 8, 2025

Uh oh!

josevalim commented Oct 9, 2025

Uh oh!

leandrocp commented Oct 9, 2025

Uh oh!

josevalim commented Oct 9, 2025

Uh oh!

leandrocp commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

josevalim commented Oct 17, 2025

Uh oh!

yordis commented Oct 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yordis commented Oct 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Oct 2, 2025 •

edited

Loading

leandrocp left a comment •

edited

Loading

leandrocp commented Oct 9, 2025 •

edited

Loading