GSoC 2026: Proposed Approach for Jenkins Docs Retooling (Antora + Vite + Versioned Documentation)

Contributing GSoC
1

Hello everyone, I have been exploring the “Continue Jenkins docs sites retooling” project and wanted to share my understanding, along with a proposed approach, before starting any contribution.

My understanding of the problem

From what I understand, the current Jenkins documentation site is built with Awestruct using AsciiDoc, YAML, and HAML, but it lacks versioned documentation, meaning users can only view the latest version of the docs. This creates confusion, especially when working with different Jenkins versions.

The goal of this project is to:

  • Complete migration of the main Jenkins documentation site to Antora + Vite.js

  • Enable versioned documentation for different Jenkins releases

  • Start building the Chinese documentation site using Docusaurus

  • Improve the overall documentation structure, maintainability, and UI/UX

  • Ensure compatibility with existing content and workflows

My proposed approach

I am planning to approach this project in structured phases:

1. Understanding Current System

  • Build the existing Awestruct-based site locally

  • Understand content sources (AsciiDoc, YAML, HAML)

  • Study page types (user handbook, developer docs, changelogs, etc.)

  • Analyse the current build pipeline and automation

2. Exploring New Tooling

  • Study Antora for versioned documentation

  • Understand how versioning, content sources, and navigation are handled

  • Explore Vite.js for frontend/build improvements

  • Review Docusaurus for the Chinese site setup

3. Migration Strategy (jenkins.io)

  • Compare the current Awestruct output with the Antora-generated output

  • Incrementally migrate content to Antora structure

  • Ensure rendering parity for all existing pages

  • Handle components from jenkins-io-components

4. Versioned Documentation Implementation

  • Set up version-based content organisation in Antora

  • Ensure users can switch between different Jenkins versions

  • Validate version-specific tutorials and documentation

5. Chinese Site (cn.jenkins.io)

  • Initialise Docusaurus-based site

  • Define structure and versioning strategy

  • Ensure consistency with the main Jenkins docs

6. UI/UX & Improvements

  • Improve the layout and readability of documentation pages

  • Suggest enhancements for navigation and discoverability

7. Automation & Contribution Workflow

  • Analyse existing automation that may not port easily

  • Propose alternatives where required

  • Document contribution workflow for future contributors

Tech stack I plan to work with

  • Antora (versioned documentation)

  • Vite.js + React (modern frontend tooling)

  • Docusaurus (Chinese docs site)

  • AsciiDoc, YAML, HAML (existing content sources)

  • Docker / Makefile (build system)

Clarification

I would like to confirm if I am going in the correct direction with this understanding and approach.
If there are specific areas of the migration (e.g., versioning, build pipeline, or UI components) that should be prioritised first, I would really appreciate your guidance.

Also, if there are recommended resources or examples of similar Antora-based versioned documentation systems that I should study, please share them so I can better understand the expected implementation.

I’m very interested in contributing to this project and would like to start working on relevant issues soon.

Thank you!