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.
Notes
[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.
