Can I link (and render) and image inside an Apple Docc file?
It seems Apple Docc is using a dialect of Markdown, and I don't see in the documentation anything about supporting images externally (a URL), that is, linking and rendering images.
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.
Could you help confirm whether this is a bug or a feature-design not to support external images? @franklin
If it was a bug, after the SR is created I can try to solve it in my spare time.
FYI ：
When reading the code, I noticed some relevant information.
There is "DataAsset.Context.download" to try to download the URL, but only used in tutorial's projectFiles and the default value is "DataAsset.Context.display"
Also here it says
The context tracks resources by file name. If the documentation author specified a resource reference using a qualified path, instead of a file name, the context will fail to find that resource.
@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.
：
