Customizing the look and feel of Swift-DocC-Render

Hi. I’d like to propose some Swift-DocC improvements to make it easier to customize the look and feel of rendered documentation.

Right now, it is cumbersome to adjust the visual design of Swift-DocC-Render powered webpages. There are certain elements like colors and typography a user of Swift-DocC might want to modify to better suit their preferences. Or, users of Swift-DocC might want to apply some sort of general visual theme which better integrates with an existing product brand. There should be a relatively convenient way of updating or overriding some of these default styling choices.

Proposed Solution

I propose adding support for a collection of settings which can be used to theme DocC-Render as part of building documentation. As a long term goal, there should be a friendly interface where these settings can be configured and previewed in a simple way. This list of settings should cover things like:

  • base colors and component specific colors
  • font stacks for content/code
  • icons
  • border radius or spacing adjustments
  • indentation size for formatted declarations

As an example of what might be possible with customizing these kinds of settings, here are some annotated screenshots of a working prototype with system font stacks that uses the “Solarized” color palette for inspiration:

In the short term, there should be a new JSON file where these theme related settings can be stored. The DocC compiler would look for a theme-settings.json file¹ in documentation catalogs and include it along with the produced renderer assets in documentation archives if one has been provided. DocC-Render can then utilize this file when rendering documentation. Once there is a user interface for creating these themes, this file could still be used as a way of serializing these choices.

A small snippet from an example JSON file might look like the following:

  "theme": {
    "color": {
      "fill": {
        "light": "#fdf6e3",
        "dark": "#002b36"

As part of this effort, I think it would be essential to create both reference and conceptual documentation that illustrate how these settings can be used to create a unique theme for DocC documentation. There should be an Open API specification for the theme-settings.json file which could be used to both document and validate that it contains valid settings. Additionally, it would be helpful to create an article that explains what some of the important settings are and maybe even a tutorial detailing how to create an example theme file like the one used in the above screenshots.

Alternatives Considered

A simpler solution that has been discussed before is providing a system where DocC users can provide additional top level CSS stylesheets to customize pages. Styling DocC-Render pages like this would be difficult due to the way the renderer is structured today. Components are developed using “scoped CSS" tooling which means that oftentimes there may be the same generic CSS classes used for completely different things—a global stylesheet wouldn’t have an easy way of distinguishing the right selectors to apply styles to the right elements. Perhaps this could be mitigated in the future when browsers have better support for the new CSS Layers technology.

Another way of approaching this problem might be to allow the Vue components themselves to be easily extended and themed. While some of this is already technically possible today, I don’t think DocC users should have to become deeply involved in the Node.js or Vue ecosystem to make simple stylistic updates. It should be simple to update small settings without having to build a new or modified version of the app itself.


[1]: This file is already included with documentation archives and does have some limited support for overriding theme settings already, however it’s not something that DocC persists from the documentation catalog when compiling documentation, which makes it not very usable in its current state.


This looks really great @marcus_ortiz! Your demo website looks really slick. Could you share the theme-settings.json file you used for it so that we can see how you customized it?

On another note, I'm noticing that when you hover over a row in the sidebar, the text color doesn't invert making it harder to read it. Is this something that could be customized as well?

Here is a link to the file used for this demo:

I will be preparing a more formal spec of what settings are allowed as part of this work.

Yes, that would be the goal. I didn't fully customize everything for this demo, but it would be essential to allow for accessible customization like that.



The implementation for this proposal has officially landed on the main branches of the swift-docc and swift-docc-render repositories. :tada:

The Swift-DocC documentation has been updated with some basic documentation on how to utilize the theme-settings.json file.

Additionally, if you prefer to learn by example, I have added a custom theme-settings.json file to my fork of the Swift-DocC documentation and you can see it running here to get a sense for the kind of customization that can be achieved.


I'm glad that quick navigation was useful for the feature flag example. Thanks for working on this!


the theming does not seam to work anymore with the current version of docc, very frustrating but thanks for the effort in improving this.

Sorry to hear you're encountering issues with this @doozMen. If you're able to, it would be much appreciated if you could file an issue on the apple/swift-docc-render GitHub repo with more details on what version of DocC you're having difficulties with this so that we can try to diagnose what might be going wrong and see if there's a bug we can fix.

1 Like

I've been testing the theming feature in the latest toolchain and the 5.8 dev version and is working fine for me.

@doozMen would you mind sharing more details on the bug you're experiencing?

1 Like

I have an example. In the code, js/index.something, it looks for r + theme-settings.json. When my basepath in a script tag in index,html was removed, it looked for undefinedtheme-settings.json, so I'm guessing r should represent the basepath.

For example, my docs are

It's looking for

rather than

Any suggestions on how to get the docs working would be much appreciated. Thanks!

@denisecase how are you generating the docs? If you're using the Swift-DocC Plugin, there is a --hosting-base-path argument that can be used to configure the base path for where the docs are being hosted. In your case, this would look something like --hosting-base-path MandArt-Docs and the resulting top level URL would likely be something like Documentation after the docs have been generated using that configuration.

1 Like

I tried your suggestion - but I host in GitHub Pages from the root folder of the MandArt-Docs repo, so when I add:

it might find theme-settings.json, but there's no MandArt-Docs in the path to favicon, etc.

I'm calling this from the root of the MandArt repo - might have to do with the transition to static hosting or other issues with using 2 repos / etc.

swift package generate-documentation
--target MandArt

I'll keep reading and learning. If you have any other suggestions, I'd be grateful - GitHub Pages is such a good way to host the docs. Thanks!

Yeah, the argument for the hosting base path is a key piece missing from that command that should enable you to host the generated docs on GitHub Pages. The Publishing to GitHub Pages article for the Swift-DocC Plugin documentation talks about this more in-depth.

I would add the argument --hosting-base-path MandArt-Docs to your generate-documentation command, and that should resolve issues you might be seeing with paths to assets, like the theme-settings.json file.

1 Like

This path relates to the way that GitHub Pages works where the URL will always contain this prefix that maps to the repo name—it's not tied to the folder where the docs are contained necessarily—I think that point may possibly be causing a little confusion.

1 Like

I used 5.7 so that might be the issue

This works perfectly - looks great - thank you!

I also needed to look in the documentation/repo folder to get the good stuff:


Have you tried to use mathematical formulas in these data-driven docs? Not quite sure how that's going to work with all the JSON/coding going on behind the scenes.


I've been testing the theming feature in the latest toolchain and the 5.8 dev version and is working fine for me.

I use DocC plugin and my theme-settings.json file was not copied over into the output folder and the "standard" theme-settings.json file was in the output folder instead :frowning:
That's when using Swift 5.7

After I switched toolchain to Swift 5.8 I no longer have the issue!!

Thanks for the tip/info that Swift 5.8 works fine :slight_smile: