Migrate from Awestruct to a modern static site generator

[basil]

At the time of this writing, Awestruct hasn't been released in 2 years, 3 months, and 27 days. It is effectively a dead project upstream. Continuing to rely on it does not seem sustainable.

I recommend considering Antora as a replacement. It is focused on AsciiDoc, which would be a natural fit for us. In addition, it supports stitching together multiple Git repositories and/or Git branches into a single web site and supports versioning. This would allow us to, for example, have a version selector that could be used to switch from viewing documentation for the weekly release (generated from one Git branch) to viewing documentation for the LTS release (generated from a different, stable, Git branch). This would eliminate the long-standing pain point of documentation having to choose between describing weeklies, LTS, or both (none of which are great options).

[basil]

Antora doesn't support blogs and is specifically for documentation sites, so it likely only makes sense to move the /doc/ URL-space to Antora. The /doc/ URL-space would be a good fit for Antora and would benefit from versioning, currently not provided by Awestruct. The rest of the site, including the blog and the other static pages that don't document a particular Jenkins release, could be rendered with some other modern static blog/site generator: Hugo, Jekyll, Gatsby, or what have you.

[zbynek]

FWIW @halkeye has a proof-of-concept migration to Gatsby.

[halkeye]

yea, https://github.com/halkeye/gatsby-jenkins-io but i've learned a lot since then.

[halkeye]

I'm eyeing trying to make news.jenkins.io (blog) seperate from the main site next. That way we can use MDX and netlify-cms to make it easy for people to submit posts.

But first i've been playing around with making some common react components, though also debating trying web components again.

[basil]

@halkeye wants to split out the blog to a different tool, and I want to split out the /doc/ space (primarily the User Handbook and Developer Reference) to Antora, which would also solve the long-standing pain point of versioning the documentation for LTS and weeklies.

I spent about two hours prototyping the latter for the User Handbook. Here is a very crude conversion to Antora:

• https://basilcrow.com/docs/user-handbook/index.html
• https://github.com/basil/docs-site
• https://github.com/basil/user-handbook
• https://github.com/basil/user-handbook/tree/stable-2.361

Productizing this would be a significant project requiring a number of different skill sets:

• Need an editor to go through each page, one by one, and tidy up/smooth out the very rough automated conversion I did. For example in two hours I had no time to deal with links, partials, images, and many other details. It would take several weeks to comb through everything and do a lossless conversion.
• Need a designer to apply a header, footer, and other styling to make the site "fit in" to the Jenkins web properties so that links from the main Awestruct site to and from the Antora site operate seamlessly in a coherent visual design.
• Staging infrastructure: Need a developer to set up a CI build and preview site.
• Production infrastructure: Need an operator to set up hosting of the production site.

While I believe that our project has people with all of the necessary skills to complete a large-scale project like this, I am not sure how many of them are interested in working on such a project (or able to commit the time, if interested). While I have specific people in mind for each of the above roles, I am intentionally not naming them because I do not know how interested they are, if at all.

If we find people interested and able to commit to each of the above roles, I am happy to help drive the project forward, using the Documentation SIG meeting as the communication touch point. My traditional role in large projects is not to have a specific role but rather to do all the difficult or annoying stuff that falls between the cracks to make the project actually happen.

[halkeye]

• Need a designer to apply a header, footer, and other styling to make the site "fit in" to the Jenkins web properties so that links from the main Awestruct site to and from the Antora site operate seamlessly in a coherent visual design.

https://halkeye.github.io/jenkins-io-components/?path=/docs/example-introduction--docs

should be really easy to get the header and footer. As layout. I hae a script that converts all the html and css to react, but otherwise no standardness, I'm sure bootstrap 5 would be close enough (@zbynek your PR is first on my list to review after work)

• Staging infrastructure: Need a developer to set up a CI build and preview site.

• Production infrastructure: Need an operator to set up hosting of the production site.

the infra setup is changing this week, but I can set it up pretty quickly.

[basil]

should be really easy to get the header and footer

Right, I think the next step from a design perspective would be for someone to apply those building blocks onto the Antora default theme visible in https://basilcrow.com/docs/user-handbook/index.html to "Jenkinsify" the prototype. We will probably understand the nature of the design work that is needed a bit more clearly once we can see how that looks.

[basil]

Status on this proposed project is that we are still looking for someone to volunteer to do the design work and frontend implementation of a Jenkins version of the Antora theme. If anyone is interested in working together on this, please let me know!

[Vandit1604]

Hey I would like to work on this.Can you tell me what are the things i should know before i can start ? For Start, I'll be reading Antora Docs

[krisstern]

This is currently one of the GSoC 2023 project ideas, we intend to use Antora to replace Awestruck, as it makes the most (technical) sense.

[MitAbhay]

Status on this proposed project is that we are still looking for someone to volunteer to do the design work and frontend implementation of a Jenkins version of the Antora theme. If anyone is interested in working together on this, please let me know!

Hey basil, I have looked out this project as GSOC 2023 project of this year, and I am interested in knowing about this project more and want to work on this, can you help ?

[krisstern]

@MitAbhay Please use the proper GSoC (2023) channels to ask questions about this "Building jenkins.io with alternative tools" project. For the relevant project ideas page please see https://www.jenkins.io/projects/gsoc/2023/project-ideas/alternative-jenkinsio-build-tool/. You will need to apply formally to be considered to work on this project idea via Google's GSoC application form which will be open on March 20th UTC.

[MitAbhay]

Sure @krisstern, Sorry for the inconvenience.

[rishustudent2001]

Heyy!! Mentors, I want to change Webpage looks like header(Search Bar more be easily and more attractive for user and change background if user on search bar can i do that??

[zbynek]

@rishustudent2001 changing design for sake of changing design is pointless. Also there are channels for GSoC discussion and there is the UX sig gitter for general UX discussion (see https://www.jenkins.io/sigs/ux/), please don't ask questions in unrelated issues.