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. https://github.com/elixir-lang/ex_doc/pull/1992 https://github.com/elixir-lang/ex_doc/pull/1976

The first PR came from the need to generate Erlang manpages https://github.com/elixir-lang/ex_doc/issues/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