I suspect the design and intention is that the documentation should be entirely self-contained, but that said I didn't track down through the rendering why it doesn't show images when I tried the same.
For what it's worth, the image reference that I included in the markdown did get encoded by DocC — as the external image reference — but didn't flow over into any visible content once it came out the other side of the rendering process through DocC-render.
Given that the primary output was designed as a "documentation archive", I'd suggest leaning into the expectation that it should be fully self-contained and planning on replicating (or just downloading) any image content and including it within the documentation catalog's asset folder.
That's exactly what I thought. But on the other hand, apart from the Xcode package (which should be self contained), it is also possible to publish this on a server (you know, using the proper configuration, routing...) so, evidently, on this case, we have internet.
Thanks for your opinion!
I guess I will try to avoid this.
@Joseph_Heck, your point regarding documentation archives being self-contained is certainly very valid, but I think this is a decision that should be left to the owner of the docs. It seems quite beneficial to make DocC more flexible in this case.
On the implementation side, one idea would be to not register assets with URLs that explicitly specify a scheme (using a scheme implies your asset is managed by a system external to DocC) in the DocumentationContext, and create an object in references for them during rendering, like we do for other non-doc links.
I'm glad to hear it was a bug. Since the project doesn't have a lot of detail about it's design, what's intended, etc. I was trying to infer intention, and the self-contained aspect seemed fairly plausible. I totally agree it's better if remote/URL referenced images were supported - as well as any number of other content types.