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.

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.

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

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

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.