[SOLR-15556] Ref Guide Redesign Phase 3: Replace Jekyll

• Type: Improvement
• Status: Closed
• Priority: Blocker
• Resolution: Fixed
• Fix Version/s: 9.0
• Component/s: documentation
• Assignee: Cassandra Targett
• Reporter: Cassandra Targett
• Created: 21/Jul/21 18:59
• Updated: 09/Nov/24 17:05
• Resolved: 13/Feb/22 19:29

Description

The final step of my grand vision for redesigning the Ref Guide is to look at replacing Jekyll with a different static site generator.

The primary reason why is because Jekyll is designed for blog posts, not for sites with hundreds of static pages like ours. Back in 2017 when I chose it, it was relatively straightforward to implement, a lot of information was available in Jekyll docs and the internet in general to customize it, and it was one of the few that supported Asciidoc format.

However now there are a lot more options, including some which are specifically designed for large multi-version documentation sites like the Ref Guide.

Included with this will be reorganizing the on-disk organization of the ref guide files themselves.

Issue Links

• blocks: SOLR-15941 Wire Antora refGuide into the release scripts
• causes: SOLR-16231 Fix ref-guide links across the codebase
• depends upon: SOLR-14444 Ref Guide Redesign Phase 2: Page Organization Overhaul
• fixes: SOLR-10299 Provide search for online Ref Guide
• fixes: SOLR-12018 Ref Guide: Comment system is offline
• relates to: SOLR-15557 Figure out how to handle ref guide page renames/redirects
• supercedes: SOLR-15915 Move ref guide away from using jcenter repo
• links to: GitHub Pull Request #605