During the Winter 2026 sprint, I made an effort to create a fresh app ready-to-customize using Geoblacklight 5.1. Below are some observations regarding the documentation that could use some attention to make the process easier for other folks.
-
Quickstart
-
One of the first recommendations at the top of the page is to visit required dependencies on the Developers page. But the developers page only mentions Ruby and Docker. During the sprint I stumbled across a more extensive requirements page, that I feel should be referenced in the Quick Start.
-
Minimum version of Rails? Seems relevant to mention on quickstart.
-
Suggest inserting a link to this 2024 Geo4LibCamp workshop. Could be very useful.
-
Using Vite for assets.
- I understood that Vite is not the correct/best approach. This needs to be updated.
-
Using importmaps. I did the following based on advice from Nick. Instructions need to be updated.
BRANCH=release-5.x ASSET_PIPELINE=importmap rails new appname -m https://raw.githubusercontent.com/geoblacklight/geoblacklight/refs/heads/release-5.x/template.rb -a propshaft --css bootstrap --js importmap
-
For Developers
- Suggest moving the architecture diagram to Quick Start. It's very useful for folks looking to stand up their own application based on Geoblacklight.
- Regarding Docker: if developing on a Linux machine, seems Docker Engine is the appropriate choice. Suggest clarification... unless I'm completely mistaken!
-
Other
- The tutorials seem rather old. Remove? Unclear to me if they are all still relevant, or cause more confusion than good.
- Customization guidelines - Nick indicates not all guidelines are still relevant. Needs revision.
- Mirador, data relations one, and leaflet customizations are not applicable in v5
- Framework recommendations - PostgreSQL is recommend. Seems like it was MySQL in the past. Explanation of PostgreSQL vs MySQL?
- Running in production - documents are 2+ years old. Updates needed?
During the Winter 2026 sprint, I made an effort to create a fresh app ready-to-customize using Geoblacklight 5.1. Below are some observations regarding the documentation that could use some attention to make the process easier for other folks.
Quickstart
One of the first recommendations at the top of the page is to visit required dependencies on the Developers page. But the developers page only mentions Ruby and Docker. During the sprint I stumbled across a more extensive requirements page, that I feel should be referenced in the Quick Start.
Minimum version of Rails? Seems relevant to mention on quickstart.
Suggest inserting a link to this 2024 Geo4LibCamp workshop. Could be very useful.
Using Vite for assets.
Using importmaps. I did the following based on advice from Nick. Instructions need to be updated.
BRANCH=release-5.x ASSET_PIPELINE=importmap rails new appname -m https://raw.githubusercontent.com/geoblacklight/geoblacklight/refs/heads/release-5.x/template.rb -a propshaft --css bootstrap --js importmapFor Developers
Other