Post-Process Javadoc-Generated Documentation in GitHub Actions Before Deploying to the Web
Tags: java, github, showdev, webdev
Published: 2022-11-16 15:21:57

This post introduces [javadoc-cleanup](https://github.com/cicirello/javadoc-cleanup), a GitHub Action that I developed a while ago for post-processing javadoc documentation prior to deploying to a documentation website. I use it in several of my own Java projects to improve the output of javadoc in a few ways. The functionality of javadoc-cleanup includes the following:
* For pre-Java 16 projects, it inserts a [viewport meta tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag), `<meta name="viewport" content="width=device-width, initial-scale=1">`, into the head of each javadoc page to improve mobile browsing. Beginning with Java 16, this isn't necessary as javadoc began including the viewport meta tag beginning with Java 16.
* Option to generate and insert [canonical URLs](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls) into the head of each page.
* Option to insert a user-defined block into the head of each page. You can use this feature to insert anything that is valid in the head of an HTML page into the head of each javadoc page. I use this feature to set a [referrer policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy), to insert a link to my site's [favicon](https://en.wikipedia.org/wiki/Favicon), and to set my [web monetization pointer](https://dev.to/devteam/you-can-now-web-monetize-your-dev-posts-but-don-t-get-your-hopes-up-too-quickly-goc).
* A few other minor cleanup actions that vary based on version of javadoc in use and other project specific characteristics. For example, if the project is a Java library using [Java Platform Module System (JPMS)](https://en.wikipedia.org/wiki/Java_Platform_Module_System), javadoc-cleanup will insert a noindex directive in the root level `index.html`. This is because for JPMS projects that javadoc generated `index.html` page uses a simple redirect to the page documenting the module, and javadoc also sets the module page's url as canonical. Thus, the page documenting the module should ideally be indexed, but not the redirect. 

__Table of Contents:__ This post is organized as follows:
* [Usage](#usage)
* [Learn More](#learn-more)
* [Where You Can Find Me](#where-you-can-find-me)

## Usage

Here is an example GitHub workflow step:

```YAML
    - name: Tidy up the javadocs
      uses: cicirello/javadoc-cleanup@v1
      with:
        path-to-root: docs
        base-url-path: https://www.example.com/
        user-defined-block: |
          <meta name="referrer" content="strict-origin-when-cross-origin">
          <link rel="icon" href="/images/favicon.svg" sizes="any" type="image/svg+xml">
```

The above step demonstrates using all of the inputs to the action. 
* The `path-to-root` input is used to specify the path to the root of the documentation website relative to the root of the repository. This input is optional, and defaults to the root of the repository. Note that this input should specify the root of the documentation website, which may or may not be the root of the javadocs themselves. For example, if you have the javadocs in a subdirectory, you should specify the parent and not the subdirectory containing the javadocs, or else the canonical links to the javadoc pages will be incorrect. The javadoc-cleanup action itself will simply skip any HTML files that were not generated by javadoc (e.g., before making any modifications, it examines the head of an HTML page for the presence of the comment that javadoc inserts into pages it generates).
* The `base-url-path` input is used to enable the optional insertion of canonical links. Just leave this input out if you don't want to insert canonical links.
* The `user-defined-block` input is optional, and is used to insert whatever you want into the head of every javadoc page. In the example above, it demonstrates inserting a link to a favicon for the site, as well as inserting a referrer policy.

See javadoc-cleanup's GitHub repository for example workflows that utilize it.

## Learn More

You can find more information about this GitHub Action in its GitHub repository:

{% github cicirello/javadoc-cleanup %}

You can also find information about this GitHub Action, as well as others I've implemented and maintain at the following site:

{% embed https://actions.cicirello.org/ %}

## Where You Can Find Me

Follow me here on DEV:

{% user cicirello %}

Follow me on GitHub:

{% github cicirello/cicirello %}

Or visit my website:

{% embed https://www.cicirello.org/ %}