feat: add Markdown formatter

[yordis]

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

[github-actions]

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

[yordis]

@josevalim any thoughts here thus far?

[josevalim]

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

[yordis]

@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]

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]

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]

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]

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)