Continue Jenkins docs sites retooling

Project goal: Using alternative tooling with Vite and Antora to build the Jenkins static site and provide versioned Jenkins documentation

Skills to study/improve: Web development, AsciiDoc, Static website tooling, Documentation, Website retooling

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

The official jenkins.io and the Chinese version jenkins.io/zh/ websites are generated as a static website using Awestruct from AsciiDoc sources, YAML data files, and HAML templates stored in GitHub. 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 can be viewed. This can lead to unnecessary confusion and is a worse experience than many other documentation sites like the git site, FreeBSD, and others…​

The preferred tool to replace Awestruct for jenkins.io are Antora and Vite.js. In addition, the preferred tool to replace Awestruct for jenkins.io/zh/ is Docusaurus.

The potential GSoC project would be to complete the revamping of the jenkins.io site and to retool the jenkins.io/zh/ from scratch. The new Antora docs site to be migrated to is expected to provide versioned documentation for various Jenkins releases. The new Docusaurus site is expected to provide a modern look and feel for the Chinese version also with version control for various Jenkins releases.

The Antora part of the project is currently more than half-way completed, with the basic structure and the versioned documentation tooling mostly in place. The Docusaurus part of the project is still in its infancy, and will need to be started from scratch.

We have already begun work on this project in GSoC 2023 as "Building Jenkins.io with alternative tools" and in GSoC 2025 as "Complete build retooling of jenkins.io". However, some work is still left to be done to complete the transition.

This selected GSoC contributor is expected to work very diligently to play catch up with the transition from the current jenkins.io repo and the new jenkins-infra/docs.jenkins.io repo for the official site, and to start a new branch for the Chinese website migration at jenkins-infra/cn.jenkins.io repo.

Please note that for the UI/UX improvement portion we may need to deal with the jenkins-io-components repo, where the code for components shared by various Jenkins websites (jenkins.io, plugins.jenkins.io, etc.) is currently hosted.

Quick Start

Documentation quick start steps include:

  • Build the current documentation site locally

  • Become familiar with the current site, including:

    • Page types and how they are generated

      • Changelogs

      • Roadmap

      • User handbook

      • Developer handbook

      • Artwork

      • Security advisories

      • Version specific content in tutorials (like "Improve a plugin")

    • Page content sources

      • Asciidoc

      • HAML / Ruby

      • Web components

    • Build process

      • Makefile

      • Docker containers

      • Syntax and spelling checks

  • Fix several "good first issues"

  • Explore jenkins-io-components repo

  • Explore Antora

  • Review version specific documentation techniques (some of them are Antora sites)

Skills to Study and Improve

  • Web development

  • AsciiDoc

  • Static website tooling

    • HAML templates

    • YAML data files

  • Documentation

  • Antora

  • Vite.js

  • Docusaurus

  • React.js

Project Difficulty Level

Beginner

Project Size

175 hours

Expected Outcomes

The deliverables of the project would be:

  1. Iterative and incremental improvements to the site throughout the project

  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)

  4. Successful migration of revamped jenkins.io website to replace website using old tooling

Details to be clarified interactively, together with the mentors, during the Contributor Application drafting phase.

New Features

Improved layout of the existing site and its pages. New jenkins.io website.

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 2026 project ideas