Building Jenkins.io with alternative tools
|
This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc. |
Goal: Using alternative tooling (i.e., Antora) to build the Jenkins static site and provide documentation per Jenkins version
Status: Selected
Team
Students:
Vandit Singh
Mentor(s):
Kris Stern
Rajiv Ranjan Singh
Yiming Gong
Mark Waite
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.