Building Jenkins.io with alternative tools

Project goal: Using alternative tooling (Antora or Hugo) to build the Jenkins static site and provide documentation per Jenkins version

Skills to study/improve: Web development, AsciiDoc, Static website tooling, Proof of concept, Documentation

NOTE: This idea is published as a draft under active discussion, but it is confirmed in principle. It is FINE to apply to it. The scope and the suggested implementation may change significantly before the final version is published. Sections like quickstart guide and newbie-friendly issues may be also missing. As a contributor, you are welcome to request additional information and to join the discussions using channels linked on this page.

Details

Background

Jenkins.io is generated as a static website from AsciiDoc sources stored in GitHub. One of the drawback 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 can be viewed. This can lead to unnecessary confusion.

Two tools are currently looked at whether they can solve the requirement, while keeping the existing functionalities and automation: Antora or Hugo.

The potential GSoC project would be to build a working tooling to generate the site in its existing form and to demonstrate the new documentation requirement. Based on these implementations (Antora or Hugo based), the Community would choose which path to go for the modernization of Jenkins.io.

Most likely we will lean towards an approach using Antora, as it is a site generator for producing websites in AsciiDoc that appears to offer exactly the kind of features we are looking for.

Skills to Study and Improve

  • Web development

  • Asciidoc

  • Static website tooling

  • Proof of concept

  • Documentation

Project Difficulty Level

Beginner to Intermediate

Project Size

175 hours

Expected outcomes

The deliverables of the project(s) would be:

  1. A fully automated (CI ready) build procedure, equivalent to the existing one

  2. Demonstration that all the existing pages are rendered in an equivalent way

    • Suggestions of improved page design(s)

    • A list of all automation that are difficult/impossible to port to the new tool

    • Suggestions and demos of alternative ways to solve this

  3. Demonstration of the versioned documentation automated tooling

    • Description of the publication process (how does one contribute to document a new or modified feature)

Newbie Friendly Issues

Basically any good-first-issue listed in the jenkins.io GitHub repo would do. These can be accessed at the GitHub repo issues tracker with the "good first issue" label.

Potential Mentors

Project Links

Organization Links

> Go back to other GSoC 2023 project ideas

On this page

Connect