swift-docc: @Image seems to be ignored in Articles, one has to use ![]()

While reading abut docc one learns about directives and @Image so one wants to use it… yet it does not seem to work in Articles, and one has to resort to the markdown method ![]() this is rather confusing, as no warning is issued about the “wrong” use or anything else, leading one to dig through and start guessing if one messed up paths, names or something else.

Expected behavior

Option 1: Can we make @Image(source: work in articles, in addition to the markdown style?

Option 2: Actually banning @Image could be an option as in Articles it might be better to use ![]()? But then we should issue warnings when this not supported use is detected.

Actual behavior

When using @Image(source: "example.png", alt: "...") nothing happens, not even an empty <img> is rendered.

Steps to Reproduce

Make some article, and use @Image in it; I did so in the following PR and it did not work: https://github.com/apple/swift-distributed-actors/pull/929/commits/0262b759738b4c92aa6ca10fd89d398f53086159 (open source package)

rdar://94284119

About this issue

Original URL
State: closed
Created 2 years ago
Comments: 16 (10 by maintainers)

Most upvoted comments

Hmm, I don’t think there would be a way for DocC to find what variants are available automatically. However, if you could manually specify the available variants of images, I think that’d be nice. This would require more arguments so that @Image syntax might be more appropriate:
@Image(source: "https://example.com/a.png", alt: "Alt text") {

  @Variant(trait: "dark@2x", source: "https://example.com/a-dark.png")

}

Let’s summary on what we agree on

Split #278 to a. Directive related improvement and b. markdown related fix.(We’d better merge apple/markdown#50 and b first then a otherwise a would have to use a buggy workaround)
Support @Image instead of give a warning and solution suggestion. (This PR need some major update to reflect this new change. I’ll make the PR draft and reenable it for review later)
Future direction. When solving #172, we may consider adding @Varients support to @Image so that we can reference variants for external image too.

Any suggestion or supplement on the above summary is welcomed.

Kyle-Ye on Jun 14, 2022

Mark this is closed since #381 is merged and should fix this issue.

Kyle-Ye on Oct 5, 2022