Gatsby Version of

It should come as no surprise that I’m a big fan of gatsbyjs. It works really well and produces pretty modern setups.

Over the weekend I started working on a version of that is entirely powered by nodejs + gatsby, instead of nodejs+ruby+awestruct. I’m not sure its a great plan, but I had fun starting it.

Current Version: Jenkins Community Blog
My Version: Jenkins
Code: GitHub - halkeye/gatsby-jenkins-io: Prototype version of using gatsby

I’m in general not a great organized writer, but I wanted to get everything out.

Random notes so far.

  • gatsby uses preloading and doesn’t need to fully download the page (just the json that rendered the page), so transitions are faaaaaaaaaast

  • No HAML. Awestruct uses haml everywhere. I personally find it very frustrating to read, though I’m sure people will say the same about react/javascript

  • the current awestruct stuff is all over the place. There GitHub - jenkins-infra/asciidoctor-jenkins-extensions: Extensions to asciidoctor syntax for Jenkins-related materials and then lots of custom ruby code in the various templates. Lots of re-implementation, then side scripts

  • current awestruct doesn’t seem to work with built in version of mac ruby, so docker is required

  • Docker for ruby and node seem to be a large barrier for a lot of new comers

  • I fought for days trying to get the existing deploy to github pages to deploy properly (Turns out i had a broken old gh-pages branch, but no error messages). but was able to use the gh-pages npm module super quickly. So much easier to deploy copies to demo behavior. Especially once we eventually get support for deploying PRs via jenkins infra

  • Data is pretty inconsistent. thanks @timja for all the reviewing and merging of all the fixes I had for

  • Can move a lot of the hard coded things, like events on the main page, into seperate yaml or adoc files and have graphql manage the logic of what to show and not have to manually update (There’s currently a comment that says update this after oct 2nd)

  • No tests. React is pretty testable these days. (I was going to say plugin-site has lots of tests, but I only found one,

  • Even without gatsby, is pretty slick option for managing static content. You give it a config file, define the schema of the files and directories, and it’ll build you a simple javascript UI that is tied to github and PRs. Its super easy to add for gatsby, but probably easy to add for existing setups.


  • Have to re-implement everything (I’m having fun so far, learning tons about gatsby and graphql, so no complaints yet)

At the moment I’m having fun. If nobody thinks its a good idea, i’ll probably poke around till I get bored and stop. If docs team is happy with it, i’ll push hard to get it all done.

(We should probably get a docs sig category in discourse)


I think that sounds like a great idea. Please continue on it!

Looks good and is snappy.

Have your tried hugo before? What I like about hugo is it can be even easier for people to update the page then gatsbyjs, since its just yaml.

Though it depends on what the goals were behind the change? If it’s ease of use for the non-frontend community then some kinda wiki might be easier.

If supporting lots of languages is a part of the goal, I hear GitHub - facebook/docusaurus: Easy to maintain open source documentation websites. is nice.

I haven’t specifically, but none of the existing content is in yaml, until this weekend it was all in .html, .md and .adoc (there’s still quite a few .md, but i migrated the rest to .adoc).

The reason I did gatsby is because a) I know it pretty well and b) its already used very successfully for the plugin-site

The main purposes for the port

  1. I like playing with gatsby
  2. I find and all its moving parts frustrating. Especially to deploy demo versions
  3. timja pointed out last week how fast the plugin site was to transition pages. Like him I mostly just go directly to the right page, so hadn’t noticed.

Yeah I think I miss spoke, hugo is mardown ;), but if gatsby is also markdown then there are probably even in terms of user friendliness.

I am not against it though we will have to rework a lot of HAML content if we take this approach instead of Hugo/Jekyll that also support HAML to some extent.

awestruct is definitely an old technology which is no longer popular. Switching to another engine would be fine, just not sure Gatsby is the best destination taking the amount of HAML content we will have to migrate. We are already stuck in the middle with Wiki migration, not sure it wort switching to another engine until we consolidate content. Would love to see more inputs.

I don’t intend to migrate content. My thinking is I’ll work in parallel splitting up presentation from content. Eventually we can drop in a new presentation layer to replace awestruct

So i got curious and looked. There’s only 55 custom html files (the layout and partials will be either asciidoc macros, or layouts/templates)

Of those 55, the majority could be made to asciidoc really easily (I say without looking at them).

$ find -name '*.haml' | grep -v _layout | grep -v _partials | grep content

I think this is totally doable, but i’ll keep updating progress, i don’t ever expect to have both running, it’ll be a complete cutover when the time comes.

1 Like is a lot different to wiki migration, there’s only one place to change and content doesn’t get re-written as part of it.

Awestruct seems to require particular ruby versions, is not under development as far as I know, and doesn’t have a lot of docs. +1 to migrating to something maintained

1 Like

I share @oleg-nenashev concerns that we already have to finish the wiki migration but at the same time if @halkeye is motivated to work on a new version of, I totally support that. This is something that we’ll have to work on at some point