This post introduces 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, <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 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, to insert a link to my site's favicon, and to set my web monetization pointer.
• 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), 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
• Learn More
• Where You Can Find Me

Usage

Here is an example GitHub workflow step:

    - 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:

cicirello / javadoc-cleanup

Create mobile-friendly documentation sites by post-processing javadocs in GitHub Actions

javadoc-cleanup

Check out all of our GitHub Actions: https://actions.cicirello.org/

About

GitHub Actions
Build Status
Source Info
Support

The javadoc-cleanup GitHub action is a utility to tidy up javadocs prior to deployment to an API documentation website, assumed hosted on GitHub Pages. It performs the following functions:

• Improves mobile browsing experience: It inserts <meta name="viewport" content="width=device-width, initial-scale=1"> within the <head> of each html file that was generated by javadoc, if not already present. Beginning with Java 16, javadoc properly defines the viewport, whereas prior to Java 16, it does not.
• Strips out any timestamps inserted by javadoc: The timestamps cause a variety of version control issues for documentation sites maintained in git repositories. Javadoc has an option -notimestamp to direct javadoc not to insert timestamps (which we recommend that you also use). However, at the present time there appears to be a bug (in OpenJDK 11's javadoc, and possibly other versions)…

View on GitHub

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

Vincent Cicirello - Open source GitHub Actions for workflow automation

Features information on several open source GitHub Actions for workflow automation that we have developed to automate parts of the CI/CD pipeline, and other repetitive tasks. The GitHub Actions featured include jacoco-badge-generator, generate-sitemap, user-statistician, and javadoc-cleanup.

actions.cicirello.org

Where You Can Find Me

Follow me here on DEV:

Vincent A. CicirelloFollow

Researcher and educator in A.I., algorithms, evolutionary computation, machine learning, and swarm intelligence

Follow me on GitHub:

cicirello / cicirello

My GitHub Profile

Vincent A Cicirello

Sites where you can find me or my work
Web and social media
Software development
Publications

View Bibliometrics for My Research Publications

View My Detailed GitHub Activity

If you want to generate the equivalent to the above for your own GitHub profile, check out the cicirello/user-statistician GitHub Action.

View on GitHub

Or visit my website:

Vincent A. Cicirello - Professor of Computer Science

Vincent A. Cicirello - Professor of Computer Science at Stockton University - is a researcher in artificial intelligence, evolutionary computation, swarm intelligence, and computational intelligence, with a Ph.D. in Robotics from Carnegie Mellon University. He is an ACM Senior Member, IEEE Senior Member, AAAI Life Member, EAI Distinguished Member, and SIAM Member.

cicirello.org