Jekyll setup getting out of date

Known issues:

• Ruby <3.2 is reaching end of life.
• sass 3.0.0 will break current import statements.

See also this note

From what I can tell, the site started as a fork of the just-the-docs repo, and a number of alterations to their files have been made over the years. The latest version of JTD is version 0.10, I think we're on version 0.4, which explains the outdated SCSS, etc.

We could:

1. Update the just-the-docs SCSS, maybe using a migration tool like sass-migrator. This might be the easiest short-term solution to get rid of those deprecation warnings, but would be a major long-term maintenance burden, as we'd have to manually update JTD's SCSS every time it gets outdated.
2. Merge the upstream JTD repo, hopefully fixing most outdated code. This might be better in theory, but leads to a ton of merge conflicts (I checked on my machine), and updating will continue to be a pain every time.
3. Migrate to a gem-based theme, which JTD supports, and use the latest version. In addition to updating a lot of outdated code, this would allow us to separate our code/docs from JTD's code, remove old/redundant files from the repo, and easily update to the next version when appropriate.

As you can probably tell, I have a strong preference for option 3. It would involve a fair bit of work, but so would option 2, and option 1 isn't really viable long-term in my opinion.

Any thoughts? I haven't been working on this site very long so there could be something I'm missing here.

Thanks Séamus, that's really good info. I fully agree that a stable long-term solution would be ideal (despite the up-front effort being higher) which means option 3 looks best.

Beyond fiddling with our current setup, I'm not too familiar with any of the underlying pieces (Jekyll, JTD, ruby, etc.), so not sure at the moment whether there are any other viable options.

Let's try to put together a plan over the coming months of what is needed and how best to approach a revamp of the site.

mentioned in merge request !27 (merged)

mentioned in commit a3b1d1ff

closed with merge request !27 (merged)

reopened

mentioned in merge request !28 (merged)

closed