An option to write at-example outputs to file

[mortenpi]

Related to #2142, but one way to manage huge figures is to have a way for HTMLWriter to put them in files. I imagine this probably being either a global HTMLWriter option.. or possibly per-block. Needs some thought on how we want to handle filenames etc.

Also, I think this will be limited to only some MIME types.. and now that I think about it, I am not sure we could use it for text/html, since there is no way to actually include it..? It could work for huge SVG images though.

cc @bauglir

[bauglir]

The scenarios that I have seen that are causing issues are primarily the huge SVG images already mentioned, but also GIF animations that are base64 encoded into img tags.

Needs some thought on how we want to handle filenames etc.

A very quick thought, but perhaps derive them from the source filename and keeping an incremental counter for that file is sufficient?

[mortenpi]

Not to make this too complicated, but one more option here would be to have a threshold value in bytes, above which we start writing files. And we could make that user-configurable, so 0 means you write everything to file.. and Inf or nothing means everything goes into the HTML. And Documenter by default uses some "reasonable" default, so that we wouldn't write a gazillion files when you have a lot of tiny examples, but we would use files automatically if we go over that threshold.

A very quick thought, but perhaps derive them from the source filename and keeping an incremental counter for that file is sufficient?

Yep, this seems pretty reasonable. Although, with pretty URLs, we have a whole directory to play with. So an image on foo/bar.md could become foo/bar/example-0001.png next to foo/bar/index.html. With non-pretty URLs, we could do foo/bar-example-0001.png next to foo/bar.html. And if it clashes with a user-provided file, we just bump the counter.

[mortenpi]

One complication I discovered when implementing #2247 with Plots.jl: we prioritize the text/html show method over all the other ones (which is reasonable -- text/html is probably the best representation usually, and we can display it, so we should prefer it):

Documenter.jl/src/html/HTMLWriter.jl

Lines 2137 to 2138 in ae3a4a8

	return if haskey(d, MIME"text/html"())
	rawhtml(d[MIME"text/html"()])

However, we can't write text/html to a file. This means that, in practice, most cases where we need #2247 (large figures), we still end up including the figure directly in the HTML. It seems like we'd somehow need to either automatically/automagically or with a toggle disable the text/html show method.