JDK 23+ Javadoc Embeds 4MB Fonts, Developers Push Back

Unexpected Bloat in Java Documentation

Developers publishing small Java packages to Maven Central are encountering a surprising increase in artifact size, discovering that recent Java Development Kit (JDK) versions are embedding substantial font files into the generated API documentation. Starting with JDK 23, the standard javadoc tool now includes default DejaVu web font files, totaling approximately 4MB. This addition significantly bloats documentation artifacts that were previously measured in kilobytes, leading to unexpected build times and larger distribution sizes for even the smallest projects.

The issue surfaced as developers noticed their documentation artifacts ballooning to 8MB or more, a stark contrast to the expected kilobyte-scale sizes for two tiny packages. This unexpected bloat is directly attributable to the new default behavior of the javadoc tool. While web fonts can enhance the visual appeal and readability of documentation for end-users accessing it via a browser, their inclusion in API documentation packages is often unnecessary and undesirable for developers who typically consume this documentation locally or through package manager sources.

The Java ecosystem relies heavily on Javadoc for API documentation. Developers use it to understand how to integrate with libraries and frameworks. A sudden, unannounced increase in the size of these documentation artifacts can have downstream effects on build pipelines, artifact repositories, and developer workflows. For projects with strict size constraints or those operating in environments with limited bandwidth, this 4MB addition represents a non-trivial overhead.

Mitigation Strategies for Developers

Fortunately, the javadoc tool provides a mechanism to disable this font embedding. The --no-fonts flag, when passed to the tool, prevents the copying of these large font files. For developers using the maven-javadoc-plugin, this can be configured directly within their pom.xml file. The plugin offers a specific configuration option to manage this behavior. By setting <disableNoFonts>false</disableNoFonts>, developers can ensure that the --no-fonts flag is passed to the underlying javadoc tool, thereby excluding the web fonts from the generated documentation.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.6.0</version> <!-- Or later -->
    <configuration>
        <disableNoFonts>false</disableNoFonts>
    </configuration>
</plugin>

For users of older versions of the maven-javadoc-plugin or those employing different build tools, the approach involves passing additional arguments directly to the javadoc command. This might require consulting the specific documentation for their build system or plugin to ensure the --no-fonts argument is correctly appended. The core objective remains the same: to instruct the javadoc tool not to include the web font assets.

It is crucial for developers to verify their build configurations. The decision to include these fonts by default in JDK 23+ may be intended to improve the browser-based viewing experience, but it comes at a significant cost for packaged documentation. The availability of the --no-fonts option, and its straightforward integration into common build tools like Maven, offers a practical solution to mitigate this unexpected increase in artifact size.

Broader Implications and Future Considerations

The embedding of large font files into Javadoc without a clear opt-out mechanism initially caused confusion and frustration among developers. This incident highlights a recurring tension in software development: the trade-off between enhanced user experience for documentation consumers and increased overhead for developers and build systems. While visually appealing documentation is beneficial, it should not come at the expense of practical build concerns.

What remains to be seen is whether future JDK releases will continue this default behavior or offer more granular control over documentation asset inclusion. Developers are accustomed to managing the size and content of their build artifacts, and any change that significantly impacts this without clear justification or easy opt-out can disrupt established workflows. The community's rapid identification and dissemination of the mitigation strategy underscore the importance of developer feedback and the agility of open-source communities in addressing such issues.

For teams managing large codebases or operating in CI/CD environments where build times and artifact sizes are critical metrics, applying this configuration change proactively is essential. Failing to do so could lead to gradual increases in build times and storage requirements, which might only be noticed much later. The ~4MB of fonts, while seemingly small in the context of modern software, represents a significant percentage increase for small documentation packages and a tangible overhead for larger projects.

This situation serves as a reminder for toolchain maintainers and JDK developers to consider the impact of default settings on the broader developer ecosystem. While aesthetic improvements are welcome, they should ideally be opt-in or easily configurable, especially when they introduce substantial, non-obvious overhead. The swift response from the Maven community in providing a clear configuration option demonstrates the effectiveness of collaborative problem-solving in the Java world.