GSoC 2023 Building jenkins.io with alternative tools project feedback solicitation

Contributing GSoC
1

RE: Seeking Community Input on Jenkins.io Tooling: Antora vs. Gatsby

Hi everyone,

We hope this email finds you well. We are reaching out to the Jenkins community to discuss the approach we should take to improve the tooling for jenkins.io moving forward as a part of the Google Summer of Code (GSoC) 2023 “Building jenkins.io with alternative tools” project. For more information regarding this project, please see Building Jenkins.io with alternative tools. We are considering two options as the alternative tools to Awestruct, which are Antora and Gatsby, and would greatly appreciate your engagement and feedback on this matter.

The proposed tooling enhancements aim to streamline the documentation management process, improve user experience, and enhance the overall functionality of jenkins.io. We have identified Antora and Gatsby as potential frameworks to achieve these goals. Before finalizing a decision of the exact tooling to be used, it is important to consider the pros and cons of each option for different parts of the website.

Antora, a documentation site generator, has gained popularity due to its simplicity and flexibility. It uses AsciiDoc as its primary markup language and supports modular documentation structures. Some advantages of Antora include:

  • Easy integration with existing systems.
  • Strong support for versioning and multi-repository setups.
  • Highly customizable output formats.
  • Extensive community support.

On the other hand, Gatsby, a modern static site generator, offers advanced performance optimizations and a wide range of plugins. It uses React.js as its underlying framework and offers benefits such as:

  • Superior performance and optimized loading times.
  • Extensive plugin ecosystem for customization and extensibility.
  • Rich theming options for enhanced visual appeal.
  • Active and growing developer community.

While both Antora and Gatsby have their strengths, we would like to express our preference for Antora for most of the parts based on our initial evaluation. However, we believe it is vital to gather insights and feedback from the community at large to ensure we will be making the best decision for the project as a whole. Your expertise and perspectives are invaluable in determining the most suitable tooling approach for jenkins.io.

To facilitate this discussion, please share your thoughts, concerns, and any relevant experiences with either Antora or Gatsby via this thread. Your input will help us make an informed decision that aligns with the needs and expectations of the Jenkins community.

We greatly appreciate your time and contributions to the project. Thank you for being an integral part of the Jenkins community, and we look forward to receiving your invaluable feedback.

Best,
Kris Stern on behalf of Vandit Singh our GSoC contributor working on this project and the mentors’ team

2

I prefer Antora due to versioning support. I think it’s common to support documentation with versioning. Versioning support will help users to understand the features in the specific version.

However, I’m wondering how the strategy is when moving to alternative tools.

1 Like
3

Thanks @berviantoleo for your feedback! We are definitely working towards building jenkins.io with alternative tools including Antora for the docs and Gatsby for the rest. Antora does offer versioning out-of-the-box so that is some new feature we expect to come out of this project.