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 generatedindex.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
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
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)…
You can also find information about this GitHub Action, as well as others I've implemented and maintain at the following site:
Where You Can Find Me
Follow me here on DEV:
Follow me on GitHub:
Vincent A Cicirello
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.
Or visit my website:
Top comments (3)
I use this GitHub Action in several Java libraries that I maintain. If you'd like to see an example of actual output, you can visit the documentation of one of these libraries, and view the source of any of the javadoc pages. Here is a link direct to the module page for one of my Java libraries: chips-n-salsa.cicirello.org/api/or...
If you want to head straight to the source of that library's documentation site, see the gh-pages branch of its repository: github.com/cicirello/Chips-n-Salsa.... The javadoc generated documentation is then within the subdirectory
api
.Great post!
Thank you