Building Jenkins.io with alternative tools

Goal: Using alternative tooling (i.e., Antora) to build the Jenkins static site and provide documentation per Jenkins version

Status: Selected

Team

Details

Abstract

The goal of this project is to build the Jenkins.io static site with alternative tools such as Antora and Gatsby. We will divide the current site into the following broad sections:

  • Blogs

  • Documentation (both user and developer)

  • Changelogs and Roadmaps

The preferred tools for the blogs, changelogs and roadmaps is Gatsby while Antora is preferred for the rest of the site.

Rationale

One of the drawbacks of the current build method is that the technical documentation is not product version bound. It is thus not possible to view the documentation for a given Jenkins version. Only the latest version can be viewed. This can lead to unnecessary confusion and affects the overall user experience. Another reason is that Awestruct hasn’t released a newer version in more than two years. It doesn’t seem useful to rely on it continuously.

Implementation

The content will be restructured according to the Antora way. Antora makes use of component descriptors to distinguish versions. User documentation will be versioned, however developer documentation will not be. Blogs will be distinct from the site and generated using Gatsy, making it simple to submit blog posts. The most urgent milestone would be Jenkins-style versioned documentation. Following that, developer documentation that does not need to be versioned would be set up. At last Blogs using Gatsby will be set up.

Office hours

  • (General) Official weekly Jenkins office hours: Thursdays 15:00 UTC.

  • (Project-based) Weekly project based office hours: Saturdays 14:30 UTC.

Details regarding the weekly project-specific office hours can be found via the "Meetings" link below.

Links