Formatters discussion

[eksperimental]

I'm opening up this issue to discuss about the formatters

Currently ExDoc support two formats, HTML and Epub. Recently we are introducing Markdown in two separate PRs.
#1992
#1976

The first PR came from the need to generate Erlang manpages #1962

The second one came from need to feed the AI Coding tools https://elixirforum.com/t/generate-docs-markdown-similar-to-epub/67946

What I see is that with this new Markdown formatters we are duplicating the logic three times (one per format) and formatted markdowns may look good if you visualize them with a markdown reader, but they may skip information needed for the OTP manpages. It felt a bit contrived while doing the PR.

I think we should generate an agnostic format (that could very well be JSON) and then build the HTML, EPub, Markdown and whatever format is needed in the future.
This way the logic will be in one place.

Reading the thread about LLMs https://elixirforum.com/t/generate-docs-markdown-similar-to-epub/67946
We may do away with the JSON format without the need to create a Markdown version of it.

A plugin system for the formatters may be needed and these could be implemented as a separate Elixir package (it could be as simple as a module that implements a formatter behaviour).

Opinions?

/cc @zuiderkwast, @garazdawi, @mayel, @josevalim, @mjrusso

[josevalim]

Yes, our goal is to simplify the formatter contract to make it easier to implement the new one. My goal is to implement the Markdown format and then refactor all common and uncommon logic. But to me, we need to implement them first, then extract it out. It is something we want to do (and a blocker for merging this) but I have had low priority to focus on it.

[josevalim]

I have posted important updates here: #1976 (comment)