runrig-coop/the-runrig-plan

The Runrig Plan is a living document that describes the main design principles of the social and ecological technologies we are building now and in the near future. Also, for now, it's our website.

Runrig: A Communal Platform for Food & Data Sovereignty

Locally. Regionally. Globally.

Runrig¹ is a communal farming platform, a libre software project and a method of socio-ecological design. It aims for collective sovereignty over not just our food, but also the labor that raises it, the land and living things that support it, and the data connecting connecting it all.

Footnotes

1. Wikipedia. "Run rig". ↩

the-runrig-plan's Issues

Update Vitepress

Judging from their CHANGELOG, Vitepress is nearing their 1.0.0 general release, currently at release candidate 24 as I'm writing. This is great news, but it would be good to prepare as much as possible in advance and be ready to upgrade when that happens.

I have 2 local branches with WIP commits for upgrading to 1.0.0-rc.4 and 1.0.0-rc.9, in turn, as they seem to be the releases with the biggest breaking changes that effects our site. I'll also be mentioning this issue in a few other related ones, regarding the Vitepress default theme, color variables, and whether to separate the website out from the Runrig Plan (ie, "draft proposal") itself.

Separate VitePress site from the Runrig Plan

I'd like to return this repo to only containing the markdown source files for the Runrig Plan itself, and create a separate repo for the VitePress site, so the main content here can live independently of the rest of the site logic and markup. Particularly as more pages are added to the site beyond the "Home", "Get Involved" and "Contact". This might also help with #3.

We use a similar pattern for farmos.org, and I really like it. That site is made with Gatsby, but the same principles could be applied here with VitePress. Basically there's a configuration file at the project root, site-data.js, which points to the source repositories it wants to pull content from, as well as which directories to include/exclude, what templates to use, etc. The source repo's remain agnostic to the how their docs are consumed and rendered, apart from a GitHub Action in their .github/workflows/ directory, which triggers the site to build when changes occur to the relevant directories. The consuming site repo uses a combination of its own logic and custom Gatsby plugins, plus the gatsby-source-git plugin. I've been wanting to extract a lot of that logic into its own library, independent of Gatsby and its plugins, which I think could simplify a lot of the implementation details and be useful for other open source communities that manage multiple projects spread across separate repos maintained by different individuals or teams. We could still lean on something like nodegit to make our job easier for fetching content from the remotes, branching, and so forth, but otherwise we don't have to make any assumptions about which SSG is being used, at least for the core logic. Separately we could provide wrapper libraries for Gatsby or VitePress plugins, etc, although that's definitely getting too far ahead of ourselves for now.

Establish consistent brand colors and theme

Related to #3, we'll need to explicitly define the brand colors we want when VitePress reaches 1.0.0 in order to upgrade without changing our theme. These links should provide all the relevant info for doing so:

• VitePress docs on "Customizing CSS" of the default theme
• Brand color CSS variables from VitePress Default Theme @ 1.0.0-beta.3, which was the last version of that color theme we used for runrig.org
• Current CSS variables from VitePress Default Theme @ main

In general, it would be good to overhaul our current theme customizations, organize things better, make them more reusable and less brittle. #4 might go some ways to help with that, too.