Browser Extension: Add Colors to DocC Documentation Navigation

[Frank-III (frankwang)]

Hi everyone,

I've extended a Chrome extension that adds color-coded tags to DocC documentation sidebars. Originally created by ktiays for Apple's docs, I've modified it to work with any DocC-generated site.

What it does

• Adds color backgrounds to navigation tags (Article, Tutorial, Sample Code, etc.)

• Makes it easier to scan and find what you're looking for

• Works in both light and dark mode

• Now detects and enhances any site using Swift's DocC framework

Before/After

Why I extended it

I love browsing through Point-Free's documentation and other third-party Swift packages, but they all have the same monochrome sidebar. This extension brings the same visual improvements to all DocC sites - whether it's Apple's, yours, or anyone else's.

The extension detects DocC by looking for the webpackChunkswift_docc_render signature, so it automatically works when you visit any DocC documentation.

Get it

GitHub: https://github.com/Frank-III/colorful-apple-documents

It's a Chrome extension you load in developer mode:

1. Clone the repo

2. Chrome → Extensions → Developer Mode

3. Load unpacked → select the folder

4. Visit any DocC site

Small improvement, but it's made my documentation browsing more pleasant. Hope others find it useful too!

Let me know if you run into any issues or have suggestions.

[rauhul (Rauhul Varma)]

I was chatting with @Joseph_Heck about adding something like this directly to docc just a week ago!

[Kyle-Ye (Kyle)]

Cool. For me, using the extension making the docc doc viewing experience more aligned with what we got from Xcode documentation view.

Screenshot of Xcode documentation View on AppKit

Screenshot of Apple developer documentation View on AppKit without the extension

Screenshot of Apple developer documentation View on AppKit with the extension

[ktoso (Konrad 'ktoso' Malawski 🐟🏴‍☠️)]

Very nice, I’d have a request to mark actors as A and distributed actors as D (or DA if it fits) in the same color as Actors

Though the actual best outcome here would be to upstream this into docc!

[marinaaisa (Marina Aísa)]

Hi @Frank-III ! this is a very cool feature and I agree with everyone else that it makes our docs clearer to find.

I’m curious to know if there any reason why you created a plugin instead of contributing to DocC Render directly. It would be a nice feature to add!

Thanks again for your work!

[Kyle-Ye (Kyle)]

This is a great extension! I really appreciate you expanding on ktiays' original work to support all DocC-generated sites. The color-coded tags definitely make navigation much cleaner.

I've created a swift-docc-render branch to test this feature natively, so people can enjoy the colored navigation effect directly without needing to install the browser extension:

Branch: GitHub - Kyle-Ye/swift-docc-render at feature/theme

If documentation is built using a swift-docc-render that includes this code, the colored tags will be there by default - no browser extension needed. This makes the enhancement accessible to everyone viewing the documentation.

Also I was wondering if there are any plans to support specifying custom swift-docc-render artifacts in the SPI config file? Currently, we can use DOCC_HTML_DIR locally, but having the ability to specify an alternative renderer in the SPI configuration would be really valuable for features like this before they land in the official toolchain. cc @finestructure

Would love to hear thoughts from others on this visual enhancement!

[finestructure (Sven A Schmidt)]

@Kyle-Ye

Also I was wondering if there are any plans to support specifying custom swift-docc-render artifacts in the SPI config file? Currently, we can use DOCC_HTML_DIR locally, but having the ability to specify an alternative renderer in the SPI configuration would be really valuable for features like this before they land in the official toolchain. cc @finestructure

Web development isn’t my forte but I believe this would be a security issue if we allowed injection from arbitrary DOCC_HTML_DIRs into the SPI site.

But even if it isn’t, I don’t think we want the look and feel be different on a per package basis. If this is generally accepted as an good improvement we should adopt it either via an official update in docc-render or via a custom version (like yours) that we use by default for all docs going forward.

My preference is strongly the former, just to reduce the amount of customisation we do when generating docs. Each modification we make is something we need to check against when there are issues (and doc generation is one of the most common support requests), so the closer we stay to just the defaults, the easier for us.

[Kyle-Ye (Kyle)]

@finestructure

Web development isn’t my forte but I believe this would be a security issue if we allowed injection from arbitrary DOCC_HTML_DIRs into the SPI site.

But even if it isn’t, I don’t think we want the look and feel be different on a per package basis. If this is generally accepted as an good improvement we should adopt it either via an official update in docc-render or via a custom version (like yours) that we use by default for all docs going forward.

My preference is strongly the former, just to reduce the amount of customisation we do when generating docs. Each modification we make is something we need to check against when there are issues (and doc generation is one of the most common support requests), so the closer we stay to just the defaults, the easier for us.

Got it. I'll then try to propose it to merge into the official upstream.

But since it is a theme, and everyone have their own preference. So I guess upstream may refuse to accept such patch. Any idea or suggestion on this @marinaaisa