Announcement: sunsetting Dogwood

[jake-low]

TL;DR: OpenStreetMap US has decided to sunset the Dogwood theme. We've merged Dogwood's code directly into our main website repository and will no longer maintain Dogwood as a standalone project. If you're using Dogwood for your site, read below for more info and advice on how to migrate.

---

Dogwood is the Jekyll theme that powered the openstreetmap.us website. We announced it publicly at State of the Map US 2023, with the hope that other organizations might find it useful for building complex Jekyll sites with interconnected content like people profiles, posts, and events.

Maintaining Dogwood as a separate project created a lot of unanticipated overhead. Most non-trivial functional changes to our website required modifying both repositories, which added significant friction to development. Improvements to Dogwood were often put off because it wasn't clear whether those changes would be breaking for other users. Ultimately, few organizations adopted Dogwood, as its design choices are fairly specific to OpenStreetMap US's needs.

For these reasons, we've decided to end support for Dogwood. Internally, we've "ejected" from Dogwood by merging its code directly into our main website repository. The Dogwood repository will remain available but will no longer receive updates or bug fixes. If you're currently using Dogwood for your site, you have a few options:

Option 1: Vendor Dogwood into your project

If you currently use Dogwood as a Git submodule, you can replace the submodule with a copy of Dogwood's codebase and commit that to your repository (this is sometimes called "vendoring" a dependency). Your site will continue to work just like it did before, and you edit your copy of Dogwood's code in order to fix bugs or add features.

Option 2: Eject from the theme (recommended)

Instead of using Dogwood as an external 'theme' dependency, you can merge its code directly into your site repository:

1. Copy Dogwood's code directly into your site at the top level, specifically these files and directories:
   • _layouts/ - HTML templates
   • _includes/ - Template 'partials' (small reusable snippets)
   • _sass/ - stylesheet code
   • assets/ - icons and image assets (also style.scss entrypoint)
   • _plugins/ - Ruby plugins (run as part of jekyll build)
   • _tools/ - JS scripts for automating various maintenance tasks
   • package.json - specifies dependencies for tool scripts
2. Remove the theme: osmus-dogwood line from _config.yml and remove any Dogwood-related gems from your Gemfile.
3. Remove the Dogwood git submodule from your repository (if you are using one).

Now that Dogwood's code lives in your repository, you can modify it however you like without worrying about maintaining compatibility with the theme (much like with vendoring, see above). Additionally, by flattening Dogwood's code into your site, it'll be easier to reorganize the code, delete what you don't need, etc.

Option 3: Migrate to a different theme

There are many other open-source Jekyll themes; see https://jekyllrb.com/docs/themes/ for some places to find them. Every theme provides different features, so migrating from Dogwood to another theme may require editing or reorganizing your site's content.

---

If you're using Dogwood and have questions about migrating, feel free to open an issue in this repository. While we won't be adding new features or fixing bugs in Dogwood itself, we're happy to provide guidance on how to migrate.

Thank you to everyone who showed interest in Dogwood, and especially to Quincy Morgan (@quincylvania) for the original design and development work.

[jake-low]

The maprva.org website has opted to eject from the Dogwood theme (option 2). If you are currently using Dogwood and considering the same path, you might be interested to look at this pull request on the MapRVA website repo as a point of reference.