Can we link and render external images (that is, from URLs)?

Hello,

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.

https://developer.apple.com/documentation/xcode/formatting-your-documentation-content

Something like:
[![image alt text](image URL link)](anchor link)

Is that possible? Or do we have to use local images ALWAYS?

I tried this:
[

]

But it does not work.
Maybe there is a reason to NOT support this. Is that the case?

Thanks a lot.

1 Like

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.

1 Like

Thanks Joseph_Heck

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.

Hi,

External images is meant to be supported but there seem to be some issue preventing that from working.

I didn't find any existing bug for this. Would you mind creating a new bug in the Swift-DocC component at bugs.swift.org?

1 Like

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 :point_down:
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.

Which will result the following problem/warning

1 Like

@ronnqvist is right, this seems like a bug—thanks for pointing that out @Ricardo1980!

@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.

3 Likes

Create a SR for it
https://bugs.swift.org/browse/SR-15839
Also a pull request here

1 Like

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.

2 Likes

The external media(image and video) support for documentation is landed via Add external media support in documentation by Kyle-Ye · Pull Request #82 · apple/swift-docc · GitHub

The external media(image and video) support for tutorial will be tracked in this SR [SR-16026] Add external media support for DocC tutorial - Swift and be solved in a follow-up PR.

Feel free to test it and report any bug you encounter. cc @Ricardo1980

6 Likes