feat: add Markdown formatter #2148

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

Signed-off-by: Yordis Prieto [email protected]

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/19272855754/artifacts/4534218131

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

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

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

lib/ex_doc/formatter/markdown.ex

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

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

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

lib/ex_doc/formatter/markdown/templates.ex

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

test/ex_doc/formatter/markdown_test.exs

lib/ex_doc/formatter/markdown.ex

eksperimental · 2025-11-05T20:55:01Z

Hi @yordis, here are a few comments:

I generate Elixir docs with this command DOCS_OPTIONS="--warnings-as-errors --formatter markdown" make docs

The docs are created under the markdown/ folder, but this is not consistent with the html and epub formatter.
We should also consider when generating multiple formats where are they going to be placed. Having html and md files in the same folder could be a bit disorganized.
Links are wrongly created:

    [```inline
    Kernel
    ```
    ](Kernel.md)

when it should be `[Kernel](Kernel.md)`

I don't think the title should be part of H1 of every page. What I did in my PR was
instead of

# Kernel  (Elixir v1.20.0-dev)

do

# Kernel

(Elixir v1.20.0-dev)

Bulleted lists are not formatted. They are just plain lines without the -
Headers don't have ###

I think you can use the output generated by my previous PR (#1992)

https://raw.githubusercontent.com/eksperimental/ex_doc_markdown_formatter_docs/refs/heads/main/elixir/Kernel.md

It can work as reference (it was a WIP but the main formatting issues where addressed).

yordis · 2025-11-05T22:43:34Z

@eksperimental should I change the tests to do full equality of the content? Maybe read them from a file snapshot or somthing, I am having a hard time trying to follow the existing tests setup, I can't tell the final structure that easy but I did not want to change it that much neither

eksperimental · 2025-11-06T00:51:11Z

@eksperimental should I change the tests to do full equality of the content? Maybe read them from a file snapshot or somthing, I am having a hard time trying to follow the existing tests setup, I can't tell the final structure that easy but I did not want to change it that much neither

I would focus on the final structure first and then add/update tests accordingly.

yordis · 2025-11-10T18:00:48Z

What should I do about that .build-markdown file? Should that be merged into the existing .build, since I did not see .epub in the .build I guessed it would be a different one

Signed-off-by: Yordis Prieto <[email protected]>

eksperimental · 2025-11-10T23:46:38Z

What should I do about that .build-markdown file? Should that be merged into the existing .build, since I did not see .epub in the .build I guessed it would be a different one

I think having a subfolder per format would be wise.

I think having everything living in the same folder is no longer viable.

yordis · 2025-11-11T15:09:09Z

I think having a subfolder per format would be wise.

I agree with this!

- Updated output directory structure for EPUB, HTML, and Markdown formats to use a consistent `.build` subdirectory. - Introduced `output_setup` and `generate_build` functions to manage build file generation and cleanup. - Adjusted file writing logic to ensure proper paths are used for generated files. - Enhanced test cases to reflect changes in the output directory structure.

yordis · 2025-11-11T16:25:40Z

I think having a subfolder per format would be wise.
@eksperimental implementing the multi-dir I just realized, is that just for the .build files, are you thinking on something like,

tree doc 
doc
├── epub
│   └── ExDoc.epub
├── html
│   ├── 404.html
│   ├── admonition.html
│   ├── api-reference.html
│   ├── changelog.html
│   ├── cheatsheet.html
│   ├── dist
│   │   ├── html-elixir-VYWJUHZE.css
│   │   ├── html-HBZYRXZS.js
│   │   ├── lato-latin-400-normal-W7754I4D.woff2
│   │   ├── lato-latin-700-normal-2XVSBPG4.woff2
│   │   ├── lato-latin-ext-400-normal-N27NCBWW.woff2
│   │   ├── lato-latin-ext-700-normal-Q2L5DVMW.woff2
│   │   ├── remixicon-QPNJX265.woff2
│   │   ├── search_data-B202F4E6.js
│   │   └── sidebar_items-ED2F9D7B.js
│   ├── ExDoc.Markdown.Earmark.html
│   ├── ExDoc.Markdown.html
│   ├── index.html
│   ├── Mix.Tasks.Docs.html
│   ├── readme.html
│   └── search.html
└── markdown
    ├── ExDoc.Markdown.Earmark.md
    ├── ExDoc.Markdown.md
    ├── index.md
    ├── llms.txt
    └── Mix.Tasks.Docs.md

eksperimental · 2025-11-11T16:44:08Z

I think that's fine. Having it as before epub and html in the main folder and only markdown in it's own sub-folder was not consistent. As more formatters are added, having everything in one folder it will become unmanageable.

By having sub-folders give the option to the user to easily create a zip file per formatter for users to download the docs.

Maybe having an option to user sub-folders could be desirable to not to break compatibility of apps using this as hexdocs.pm.

Those are my 2 cents.

- Simplified the output directory structure for EPUB, HTML, and Markdown formatters by removing redundant build directory paths. - Updated the `run` function in each formatter to directly use the output path for building. - Enhanced the `update_output_for_formatter` function to streamline output path management in the documentation generation process. - Adjusted related test cases to reflect the new output structure.

yordis · 2025-11-11T17:01:59Z

not to break compatibility of apps using this as hexdocs.pm.

The reason I asked is because of hexdocs and how people could "deploy" these artifacts, having the subdir for pub or html would introduce breaking change, I am guessing since it will require to add /html /pub if a simply static hosting is in place.

So, should I duplicate the pub and html and keep them as well in the subdirs, or should I just add the markdown?

eksperimental · 2025-11-11T17:08:22Z

Maybe have an optional flag to use sub-folders for now, and not having it the set by default. Later on this can be set by default in v1.0 or remove it completely and make it the default (and only) behavior.

Also I think we should ask @josevalim's opinion.

yordis · 2025-11-11T17:09:59Z

@eksperimental I will wait for @josevalim and hopefully after that we can get a clear path forward, eitherway I can get it done.

yordis commented Oct 2, 2025

View reviewed changes

test/ex_doc/formatter/markdown_test.exs Outdated 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 force-pushed the yordis/add-markdown-formatter branch from 5131f1a to 9770ce7 Compare October 29, 2025 16:49

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

eksperimental suggested changes Oct 30, 2025

View reviewed changes

eksperimental reviewed Oct 31, 2025

View reviewed changes

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

yordis requested review from eksperimental and leandrocp October 31, 2025 16:44

josevalim mentioned this pull request Nov 2, 2025

Make ExDoc.DocAST public and document AST #2165

Closed

eksperimental mentioned this pull request Nov 5, 2025

Road to v1.0 #2155

Open

3 tasks

yordis force-pushed the yordis/add-markdown-formatter branch from 2286b77 to cbc1367 Compare November 10, 2025 16:49

feat: add Markdown formatter

83c8172

Signed-off-by: Yordis Prieto <[email protected]>

yordis force-pushed the yordis/add-markdown-formatter branch from 84aca2b to 83c8172 Compare November 10, 2025 19:25

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eksperimental commented Nov 5, 2025

Uh oh!

yordis commented Nov 5, 2025

Uh oh!

eksperimental commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yordis commented Nov 10, 2025

Uh oh!

eksperimental commented Nov 10, 2025

Uh oh!

yordis commented Nov 11, 2025

Uh oh!

yordis commented Nov 11, 2025

Uh oh!

eksperimental commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yordis commented Nov 11, 2025

Uh oh!

eksperimental commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 2, 2025 •

edited

Loading

leandrocp left a comment •

edited

Loading

leandrocp commented Oct 9, 2025 •

edited

Loading

eksperimental commented Nov 6, 2025 •

edited

Loading

eksperimental commented Nov 11, 2025 •

edited

Loading

eksperimental commented Nov 11, 2025 •

edited

Loading