2 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
Stucture of Generated Documentation
Custom Properties
Creating and Applying a Custom Theme
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.
Copy
: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 [Link] in your new empty current working directory with the content below.
Copy
/**
* 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-
[Link] in your current working directory with the following content:
Copy
: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.
Copy
javadoc -d docs --add-stylesheet [Link] [Link]
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/[Link] 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.