Theme like developer.apple.com/documentation

[swiftyfinch]

Feature Name

Apple Official Theme

Description

Hello everyone!

I have an idea to customise the current theme of DocC in the style of the official Apple website.
In my opinion, it looks nicer and is more consistent with official documentation.
It would be great if we had such an ability and some documentation describing how to do it.

I've learned about https://github.com/swiftlang/swift-docc/blob/main/Sources/SwiftDocC/SwiftDocC.docc/Resources/ThemeSettings.spec.json and tried to replace the icons.

{
  "theme": {
    "icons": {
      "single-letter": "/images/single-letter.svg",
      "link": "/images/link.svg"
    }
  }
}

I managed to replace some of them, but I can't understand how to replace the symbols and link icons.
It looks like I can't do it.

• I can't find the link icon in the spec and didn't manage to figure it out on my own:
  class="svg-icon link-icon icon"
  
  

• And I can't understand how to replace symbols such as class, structure, enum, etc. I can only replace them with a single icon by id: "single-letter" in the svg icon.
  
  

Could you help me to highlight how to do it?
Or maybe it needs to implement some improvements here.
And what do you think about describing a separate theme like an Official Apple site one?

Motivation

In my opinion, it looks nicer and is more consistent with official documentation.

Importance

On the one hand, appearance is not super important, but it is a valuable thing, because we have to read a lot of documentation, and it would be better to do so in the same way.

Alternatives Considered

I think that we need at least a few more instruments to implement the official theme.

---

Updated:

• https://forums.swift.org/t/theme-like-developer-apple-com-documentation/73918

[d-ronnqvist]

DocC itself doesn't know anything about the template that the renderer uses to display the documentation pages.

[mportiz08]

I can't find the link icon in the spec and didn't manage to figure it out on my own:

I think it may be the case that only the icons for the items in the "Topics" section are overridable at present, although it would definitely be great to fix that and make them all overridable.

And I can't understand how to replace symbols such as class, structure, enum, etc. I can only replace them with a single icon by id: "single-letter" in the svg icon.

Unfortunately, I think this is another current limitation you've found. Right now, this icon is actually implemented as a Vue component that takes some text as a prop and utilizes it in the resulting SVG—and if it gets overwritten, it will always be a static SVG asset as you noted. It would also be great to fix this in some way to allow for custom icons to do something similar.

[swiftyfinch]

@mportiz08 Thank you for your response! What do you think about aligning with the official documentation theme? I’ve mentioned my points above for reference.

I’d be happy to help, but I don’t have any experience with Vue.