Exercise 1.4: Linking Javadoc Documentation in Github

Author

Chuck Nelson

Published

September 8, 2025

1 Linking Javadoc to Your Project README

In this exercise, you will learn how to make the API documentation for your project accessible directly from your GitHub repository’s README file. This is a common practice that helps other developers understand and use your code.

1.1 Prerequisites

You have a Java project with a pom.xml file.
You have run mvn javadoc:javadoc and successfully generated the Javadoc site. You should see a target/site/apidocs directory in your project folder.
You have Git initialized for your project and are using VS Code.

1.2 Prepare the Local Environment

First, we need to create a simple index.html file in your project’s root directory that will redirect to the Javadoc. This is a common workaround for linking to documentation hosted on GitHub Pages.

Open your project in VS Code.
In the Explorer sidebar, click the “New File” icon in the root of your project.
Name the new file index.html.
Copy and paste the following HTML code into the new file:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta http-equiv="refresh" content="0; url=./target/site/apidocs/index.html">
  <title>Project Documentation</title>
</head>
<body>
  <p>Redirecting to <a href="./target/site/apidocs/index.html">documentation</a>...</p>
</body>
</html>

Save the index.html file. This file will be the entry point for your documentation link.

1.3 Update the .gitignore File

We need to make sure that the generated Javadoc files are tracked by Git, but we should not track the target/ directory itself, as it contains build artifacts.

Open or create the .gitignore file in your project’s root.
Find the line target/ and comment it out or remove it temporarily.

# target/
.idea/
.vscode/

Instead, add a specific line to ignore everything inside the target/ directory except the site/apidocs folder. Add the following lines to your .gitignore:

/target/*
!/target/site/
!/target/site/apidocs/

The ! operator tells Git to negate a previously ignored file, so !/target/site/apidocs/ tells Git to track that directory even though target/ is ignored.

1.4 Create the Javadoc Link in README.md

Now, you will add the actual link to your README.md file so that others can easily navigate to your documentation.

Open your README.md file.
Add a new section, for example, “Documentation,” and create a link to your index.html file.

# My Java Project

A brief description of your project.

## Documentation

[**View API Documentation**](index.html)

Save the README.md file.