Feature request: Can makedocs() accept .html files instead of .md files?

[pat-alt]

This may be a long shot, but I'm wondering if it would be possible to let makedocs() accept self-contained .html files instead of only .md files. I'm working on the docs for my package CounterfactualExplanations.jl and would love to use Quarto in order to have full support for cross-references (images, equations, citations, ...). I'm aware of some Julian ways to facilitate such things (e.g. DocumenterCitations.jl), but the ability to use Quarto would really be a catchall.

[pat-alt]

There is a good workaround: in the YAML header simply specify:

format: 
    commonmark:
        variant: -raw_html

Of course support for HTML docs would still be preferable since by setting variant: -raw_html you lose support for the actual cross-references between citation & reference, figure reference & caption etc. but at least it renders. Again, conscious this may be a long shot and not sure if possible at all, but I'll still leave this issue open for now.

For anyone interested in seeing an example that uses the workaround solution see the following:

1. Jupyter notebook used to actually generate the docs with code.
2. The corresponding markdown doc generated through quarto render and pointed to in my make.jl.
3. The final page in my package docs.

Works well enough, but for some odd reason image captions are not showing? They are rendered in basic Markdown syntax, so not sure why they don't show up.

[mortenpi]

Do you mean that the self-contained HTML file would be the whole thing that gets sent to the browser, or do you imagine that Documenter would still try to generate the sidebar etc. around the provided HTML? The former should kind-of work already, as anything not Markdown just gets copied over to the output directory, although you wouldn't get a link in the sidebar (tangentially related: #344). For the latter, you could wrap things in an at-raw block. Either way though, generating correct links in user-provided HTML is difficult (related: #921).

Works well enough, but for some odd reason image captions are not showing? They are rendered in basic Markdown syntax, so not sure why they don't show up.

Hmm, it looks like we populate the alt attribute, but not title with the caption. This seems to consistent with the spec though, as the title should come from link title (i.e. [alt text](url "title text")), but I believe the Julia Markdown parser does not support parsing link titles.

[pat-alt]

Thanks @mortenpi and apologies for the late reply.

Do you mean that the self-contained HTML file would be the whole thing that gets sent to the browser, or do you imagine that Documenter would still try to generate the sidebar etc. around the provided HTML?

Indeed, I meant the latter, i.e. passing a single HTML file instead of .md - shame it doesn't work, but kind of expected that this would be tricky!

As for this:

Hmm, it looks like we populate the alt attribute, but not title with the caption.

I think it would be really nice to have support for captions and cross-references like in Quarto and R Markdown. Again conscious that this may be easier said than done, but I guess that in an ideal world, Documenter would just accept .qmd documents and render single HTMLs through Quarto.

[mortenpi]

To support the title links, we'd need to support a different Markdown parser, like CommonMark.

For the HTML inclusion, at-raw blocks (or at-eval blocks with text/html show methods) would be the way to go, although it would be up to you ensure that all the links etc. are correct.

[camilogarciabotero]

I want to leave here this post, which showcases a neat integration of Documenter.jl and Quarto. Anyways, I would like to have what @pat-alt suggested on using the HTML files in the make function.

[mortenpi]

Some sort of a Quarto integration would have to be done as a plugin, both to manage dependencies, but I also think it would be a bit too big to be maintained here.