Programmer’s Guide to JavaDoc CSS Themes

2 Programmer’s Guide to JavaDoc CSS Themes

API documentation generated by JavaDoc comes with a default CSS stylesheet (see Cascading Style Sheets home page) that defines its visual properties such as fonts, colors, and spacing. While the default stylesheet is built with the goals of accessibility and appeal to the widest possible audience, there may be projects that prefer a custom style that extendes or replaces the default stylesheet. This document provides information on how to achieve this, including an example stylesheet for a dark CSS theme.

Topics

Command line options

The javadoc tool provides two command line options to customize stylesheets for the generated documentation.

The --add-stylesheet option adds a stylesheet to the generated documentation in addition to the default stylesheet. Rules in the added stylesheet override corresponding rules in the default stylesheet, so this option can be used to set styles that selectively change styles in the default stylesheet.
The --main-stylesheet option replaces the default stylesheet with the one provided as argument to the command line option. This means the custom stylesheet is solely responsible for the style of the documentation. It is advisable to use the default stylesheet as a starting point for the custom stylesheet.

For this guide we will use the --add-stylesheet option, because we want to build on the built-in stylesheet, overriding only the properties we want to change. Of course, replacing the default stylesheet opens up more possiblities, but it is much more involved and beyond the scope of this guide.

Stucture of Generated Documentation

The output of the documentation generated by the JavaDoc Standard Doclet is described in JavaDoc Output Generated by the Standard Doclet, which includes a list of CSS classes used in generated API documentation. While this may serve as a reference for for those wanting to write their own JavaDoc stylesheet from the ground up, it is probably sufficient and much simpler to customize styles using the custom properties described below.

Custom Properties

CSS Custom Properties (see Using CSS custom properties (variables)) are a convenient way to define CSS values in one place and use them anywhere in the stylesheet. The JavaDoc default stylesheet uses CSS custom properties for all fonts and colors, making it possible to create a complete CSS theme by simply providing a stylesheet containing redefined custom properties.

CSS custom property names always begin with a double hyphen (--). In order to be usable by all page elements, the JavaDoc stylesheet defines its custom properties in the :root pseudo class. The following example shows how to set the body font size to 15 px.

:root {   --body-font-size: 15px;}

The number of custom properties in the default stylesheet was intentionally kept small, and many of the variables are used in more than one place. While this makes it simpler to create consistent themes, it also limits the freedom of choosing specific styles for individual page elements. This is a deliberate choice, the limitation can be bypassed by directly overriding the underlying CSS rules.

The following subsections document the custom properties used in the default stylesheet.

Font families

The following properties define the font families used for various kinds of text in the page.

--body-font-family: Defines the base font family for the page
--block-font-family: Defines the font family used for blocks of documentation
--code-font-family: Defines the font family used to display program code

Font sizes

The following custom properties define font sizes for basic text in the page. Note that font sizes for specific elements such as headings and navigation links are derived from these custom properties:

--body-font-size: Defines the base font size for normal text
--code-font-size: Defines the base font size for program code

Background colors

The following custom properties define background colors for various generic page elements.

--body-background-color: Defines the main background color of the page
--section-background-color: Defines the background color of primary page sections
--detail-background-color: Defines the background color of the details section
--navbar-background-color: Defines the background color of the primary navigation bar and inactive tab buttons
--subnav-background-color: Defines the background color of the secondary navigation bar and table headers
--selected-background-color: Defines the background color of selected navigation items and tab buttons
--even-row-color: Defines the background color of even-numbered table rows in summary tables
--odd-row-color: Defines the background color of odd-numbered table rows in summary tables

Text colors

The following custom properties define text colors of various generic page elements.

--body-text-color: Defines the main text color of the page
--block-text-color: Defines the text color for text blocks
--navbar-text-color: Defines the text color for the navigation bars
--selected-text-color: Defines the text color for selected navigation items and tab buttons
--selected-link-color: Defines the text color for links in selected navigation items and tab buttons
--title-color: Defines the text color for the page title
--link-color: Defines the text color for links
--link-color-active: Defines the text color for active links

Colors for specific features

The following custom properties define background and text colors for various specific elements in the page.

--snippet-background-color: Defines the background color for code snippets
--snippet-text-color: Defines the text color for code snippets
--snippet-highlight-color: Defines the text color for highlights in code snippets
--border-color: Defines the color for borders of section boxes
--table-border-color: Defines the color for border of tables
--search-input-background-color: Defines the background color for the search input
--search-input-text-color: Defines the text color for the search input
--search-input-placeholder-color: Defines the text color for the search input placeholder text
--search-tag-highlight-color: Defines the background color for highlighted search tags
--copy-icon-brightness: Defines the brightness for the copy-to-clipboard icon
--copy-button-background-color-active: Defines the background for the copy-to-clipboard button
--invalid-tag-background-color: Defines the background color for invalid-tag notifications
--invalid-tag-text-color: Defines the text color for invalid-tag notifications

Creating and Applying a Custom Theme

The following example shows how to create a custom stylesheet that overrides some of the custom properties used by the JavaDoc stylesheet in order to create a dark CSS theme.

Since we need to create some files it is a good idea to start with a new empty directory. In a Terminal window, create a directory called javadoc-style or something similar and enter it.

The first thing we need is some Java code to document, so we’ll create a simple test class. Create a file called Test.java in your new empty current working directory with the content below.

/**
 * A test class.
 */
public class Test {

    /** 
     * Constructor.
     */
    public Test() {}

    /** 
     * Constructor.
     * @param s a string
     */
    public Test(String s) {}
    
    /** 
     * A simple method.
     * @param s a string
     */
    public void hello(String s) {}

    /**
     * A method.
     */
    public void foo() {}

    /**
     * Another method.
     */
    public void bar() {}
}

The only other file we need is a CSS files containing our custom style. Create a file called dark-theme.css in your current working directory with the following content:

:root {
    --body-text-color: #e0e0e3;
    --block-text-color: #e6e7ef;
    --body-background-color: #404040;
    --section-background-color: #484848;
    --detail-background-color: #404040;
    --navbar-background-color: #505076;
    --navbar-text-color: #ffffff;
    --subnav-background-color: #303030;
    --selected-background-color: #f8981d;
    --selected-text-color: #253441;
    --selected-link-color: #1f389c;
    --even-row-color: #484848;
    --odd-row-color: #383838;
    --title-color: #ffffff;
    --link-color: #a0c0f8;
    --link-color-active: #ffb863;
    --snippet-background-color: #383838;
    --snippet-text-color: var(--block-text-color);
    --snippet-highlight-color: #f7c590;
    --border-color: #383838;
    --table-border-color: #000000;
    --search-input-background-color: #000000;
    --search-input-text-color: #ffffff;
    --search-input-placeholder-color: #909090;
    --search-tag-highlight-color: #ffff00;
    --copy-icon-brightness: 250%;
    --copy-button-background-color-active: rgba(168, 168, 176, 0.3);
    --invalid-tag-background-color: #ffe6e6;
    --invalid-tag-text-color: #000000;
}

Next we invoke the javadoc tool with our Java class as primary argument. Our style sheet is passed using the --add-stylesheet option option, and the -d option is used to place the generated documentation in a subdirectory called docs.

    javadoc -d docs --add-stylesheet dark-theme.css Test.java

Note:

The proper JDK binaries must be on your PATH for this to work. Alternatively, you can invoke the javadoc tool by specifying the complete path name.

If the invocation of javadoc terminates successfully it will create a directory called docs containing the generated API documentation. If you open file docs/Test.html in your browser it should look similar to the page shown below.

Figure 2-1 API documentation using a dark theme

Description of "Figure 2-1 API documentation using a dark theme"

It should be straightforward to adapt the invocation to your project and build system, and of course you can modify the theme to your taste or create a new theme from scratch. The custom theme will be used in every HTML file that is part of the generated documentation.