Not sure yet! But some ideas are starting to crystalize… curious to hear what folks think!

My main focus with what I did last night was to a) copy and update all the “hosting” related documentation into the farmOS 2.x branch, and b) review and outline what other pages/sections are currently on that will need a new home…

There are a few different goals/interests here… all very interrelated, and I’m trying to think about them with an eye towards incremental rollout. They are:

  1. Making it easy to “start fresh” on a redesigned “community portal”.
  2. Ensuring that 1.x and 2.x docs are available/accessible to those who need them.
  3. Preserving history.

The path to achieving all of these (incrementally) is starting to fall together in my mind… and hopefully it compliments the ideas you have for the redesign (and makes it easier)!

Regarding #1 (“making it easy to start fresh”) - wouldn’t it be nice to start a brand new main branch for the new site from scratch, without any shared history or baggage from the existing 7.x-1.x branch? We could start fresh with a nice homepage, and pick and choose which pages/sections from the old branch make sense to keep (and would have some liberty to adapt them). This would mainly include the general community pages/sections, I think (eg: docs/community/*, docs/, etc). But we could leave behind anything that is really specific to 1.x or 2.x of farmOS…

… which leads into #2 (“ensuring that 1.x and 2.x docs are available”).

As a first step, 2.x docs are going to be available at (previously This is built directly from the /docs directory of the farmOS 2.x branch, so it can be maintained and updated alongside farmOS itself as it changes. So that covers “making 2.x docs accessible”… (as an incremental step, at least)

As for 1.x docs, I think that’s still an open question in my mind… do we create a new as a “snapshot” of the current repo’s 7.x-1.x branch? Maybe we remove a bunch of the misc content, so it’s just the user guide and hosting info (assuming everything else gets recreated in the new portal or ported to farmOS 2.x)? And add a message to the effect of “this is for the OLD version of farmOS, click here for latest docs”? That could be an easy way to have an “archival” 1.x docs site, when 2.x becomes the officially recommended version. And this could be done incrementally if the redesign comes together before 2.x as well, I think. Open to ideas on this!

In either case, one thing I would like to do (which shouldn’t really affect any of the above decisions), is merge the existing history of the 7.x-1.x branch into the farmOS 2.x branch, in the same way that I will be doing with the 7.x-1.x branch of farmOS itself. And to be clear, by “merge” I mean the following:

# Perform final merge of 7.x-1.x into the current branch using the "ours"
# strategy to discard all changes from 7.x-1.x. This serves to indicate
# that 7.x-1.x has been incorporated into the new main line, thus preserving
# its full history, commit counts, contributor/author info, etc.
git merge -s ours --allow-unrelated-histories origin/7.x-1.x

That’s what these two issues are for, specifically:

The reason to do this is to achieve #3 (“preservation of history”). I see these two 7.x-1.x branches as legacies of farmOS’s past, and are valuable to preserve in their own right, even though they will no longer be maintained. By merging them both into the 2.x branch of farmOS itself, we preserve them in the core Git tree, and we also get the benefit of including all the contributors to in the farmOS GitHub contribution summaries - which is good for a lot of reasons, IMO. It serves to celebrate everyone that has contributed to farmOS and during the 1.x life-cycle, while at the same time creating a nice clean break and redefining’s new role moving forward (the new “community portal”!)

I made a quick whiteboard sketch to try to convey how this looks from a high level in my mind:

  • The RED “farmOS 2.x” represents the 2.x branch of farmOS - It will become the new default branch.
  • The GREEN “farmOS 7.x-1.x” represents the 7.x-1.x branch of farmOS - When it comes time to make 2.x the default branch, it will be merged into 2.x. But notice that I did leave a little green line coming off of it, which represents some minimal support for dependency/security updates for folks still on 1.x (TBD how long we support that).
  • The MAGENTA “ 7.x-1.x” represents the 7.x-1.x branch of - This can be merged into 2.x at the same time as the GREEN merge. We could potentially DELETE this branch from the repository at that point. But perhaps we have another little magenta line coming off of that that represents the “archival 1.x docs” that I described above (or we create a new repo for that in the legacy GitHub organization).
  • The MAGENTA “ main” represents a proposed NEW branch of the repository, which is a clean start (notice how it does not branch off of the 7.x-1.x line, but starts as a new branch with a unique history and initial commit).

What do y’all think?

1 Like

I’ve gotta check myself out for the weekend shortly and don’t have time to read through everything in your last comment carefully, @mstenta; however, if I get the gist of what you’re saying, I’d like to point you to the last comment in this issue:

That’s the git strategy I’m imagining for how to start fresh (#1) while also preserving history (#3). And I think the strategy is also compatible with #2, but I need to learn more what you have in mind for that. If you have a moment, take a look, discuss with others, and I’ll pop back in to see where you’re at come next week.

1 Like

Awesome! Yes! I think these are all compatible and complimentary pathways! I’ll try to get a few more ideas into words … have a great weekend! :slight_smile:

I still favor the strategy of making the user guide portion of the documentation self-hosted. i.e. Making it part of farmOS itself… If we do that as part of a final 7.x-1.x release, that documentation could live as long as there are any 7.x-1.x installations online.

Another advantage of self-hosted documentation is that it works in offline/air-gapped/limited-connectivity scenarios. I’m imagining a farm/homestead which has off-grid power and a sketchy internet connection but runs farmOS on a local network.

Obviously the current version of the user guide should also be available online at

GitLab does an excellent job of this sort of thing. If you host a local instance all the “help” links and stuff reference self-hosted copies of the documentation - which besides working “offline” also is nice because you can tell you’re looking at the documentation for the version you’re actually running.


+1 to this!

Drupal 9 has a core concept of Help Topics. It’s an experimental module right now - but will soon be stable! These are fairly targeted towards general Drupal administration, but I think it would be possible to create dedicated sections for farmOS topics and “hide” what isn’t needed for normal users. They should be theme-able as well.

A nice feature is that they can be translated with the existing Drupal localization service. But perhaps a downside of this is the topics need to be written in twig files. Markdown would probably be best… but maybe a script could auto-generate the twig files from markdown??


Perhaps we should open a separate topic for this?


Funny you should mention!! Nowhere near complete or even “figured out” - but I started a branch to start thinking about this in 2.x:

Also, I’m realizing my use of the word “merge” in my ideas above is confusing at best, and misleading at worst. I’ll try to clarify soon… occupied with family stuff right now. :slight_smile:

1 Like

Ok, here’s a bit more context to my thinking… hope this helps!

The content on right now can be divided into two categories:

  1. General community stuff
  2. farmOS 1.x specific stuff

I’d like to consider the 1.x documentation “deprecated” as soon possible, and be ready to make 2.x docs “canonical”. I’ve been working on bringing the 2.x docs up to parity with the 1.x docs, and as of right now it’s almost there! The “User guide” and “API docs” are the only two pieces that aren’t covered yet - and there may be opportunities to rethink our approach to those now, too (per @symbioquine and @paul121’s comments above).

Setting those aside, and stepping back, I think one of the basic questions here (in this forum topic) is: “how does a visitor get to both 1.x and 2.x docs from”

@jgaehring’s idea to pull everything together into via Gatsby is a good one!

I feel like it makes more sense to bring these all under one umbrella with Gatsby.

it provides consistency across the board, which might be more of a cosmetic concern, yea, but I think branding is important in the documentation, too

I agree having everything under one umbrella would have a lot of benefits. And so I’m mainly thinking through: “how do we do that incrementally?”

The reason I always try to think incrementally is because I know that these kind of community based efforts can take time, and this one in particular has a lot of aspects to it, so it helps to break it down into bite sized chunks. Not only does this decouple the different aspects/goals, it also makes it easier for others to jump in and help in smaller ways.

So, I’m wondering if we can make that the end goal, but actually start by going in the other direction first: separate things. Then each step in the process becomes simpler.

Going back to my first point above (“the content on can be divided into two categories”), if we were to start by moving all the 1.x-specific docs out to a separate hostname (eg:, then we would be starting with three distinct and very well-delineated sites:

Alongside that “split”, @jgaehring could start a brand new repository for, with an initial focus on:

  • Looking great!
  • Emphasizing upcoming 2.x.
  • Hosting general community stuff.
  • Linking to 1.x and 2.x docs (as well as Field Kit, Aggregator, farmOS.js,, and farmOS-map docs)

At the end of this first pass, we have a beautiful new, with links to the other docs (for now).

All of that could be achieved pretty quickly, I think, and would leave us in a great spot. So in the off chance that things get delayed, or the next stage takes longer, at least we have a beautiful new site, and everyone can find the docs they need. It’s not the “one umbrella” with a unified brand yet - but it checks all the critical boxes.

Then, @jgaehring can proceed foreward with the Gatsby aggregation initiative, and this can happen at whatever pace it needs to. All the little details can be figured out, with no pressure or rush to get the new design out - because that part is already done! It’s just a matter of aggregating/organizing the content.

So, I think we end up at the same end-goal. The only difference is we do it in two steps. :slight_smile:

And maybe both of these things happen in rapid succession! But knowing how community driven project like these go, there’s a good chance things will take longer than expected. So my thought is: why not decouple those two pieces, so we can get the “redesign” (eg: make it look pretty) done first. So first impressions are :fire:!

One related idea I feel is important to share, which is informing some of this thinking, is that in my ideal future, would not include 1.x docs at all! I want to say goodbye to 1.x - and get to a point where we don’t even need to talk about “1.x vs 2.x” anymore. So one of my hopes is that the “Gatsby aggregation” only pulls in the 2.x docs (and docs for Field Kit, Aggregator, etc etc). So that’s also part of my reasoning behind splitting 1.x out to entirely. If we plan for that future, then we can just “retire” the old repository altogether! Perhaps even move it to as part of the first pass…


In some ways I see this as an opportunity to “close the chapter on 1.x”. If you look at my whiteboard sketch above with that in mind it might make more sense. :slight_smile:

Done! Inline user guides

Love all these ideas, @mstenta! With one small “but”:


Ummmm… Could it? :face_with_monocle:

I guess this is where we differ in how we estimate the work being portioned out. I see the design aspect being the lionshare of the custom work, whereas I see the technical work as being the more plug-n-play aspect. Gatsby offers a lot of superpowers, with it’s plugins for using multiple git repos as sources, etc, and that adds a certain irreducible complexity, for sure, but on the whole I’m not too worried about how that will work.

I think you’re idea of incremental development is spot-on though!

Perhaps we could go back to the roadmap I proposed above, with 4 major milestones:

  • Migrate from MkDocs to Gatsby
  • Community features & content
  • Rebranding
  • Documentation

I think we could certainly tease this apart further and think about the ordering. I guess implicit in the original concept is that we would migrate the old docs from MkDocs to Gatsby, and the bulk of that work would be in just reproducing the markup. I guess if we were ready to scrap the old docs sooner rather than later, we could, but I guess I’m not so sure that’s so feasible in, say, the next year. So let me come back to that. I think we can definitely put the community features on pause, unless someone wants to take ownership of that portion. Then the next question is, really, do we want to prioritize the rebranding, or the documentation first? Like I said, I think the documentation part is the easy stuff, just plugging together the different repos and figuring out a structure (subdomains vs subdirectories, etc). Then the rebranding should be considered the big chunk, imo.

So really I guess our major decision right now is, do we want to just roll out the documentation using an off-the-shelf Gatsby theme, of which there are plenty? We could keep them on a separate site, not worry about migrating any of the markup for the old site, work on the long and slow process of rebranding, and by the time that’s done, we can move the 1.x stuff over easily (w/o porting the markup), or ditch it, if that’s the preferred path. Or something along those lines?

Lemme know what you think.

1 Like

So based on my questions above, I’m wondering about this as revised milestones going forward:

  • Scaffold Gatsby site
  • Aggregate documentation for 2.x
  • Rebranding
  • Community features & content
  • Migrate User Guide
  • Migrate documentation for 1.x
1 Like


1 Like

One last thought that came up in our team call…

Perhaps we should start thinking about this in 2 parts/repos:

  • Frontend repo: Gatsby site only, sans content
  • Backend repos: content from multiple repos that the frontend can use as sources
    • Docs
      • farmOS 2.x
      • farmOS Aggregator
      • Field Kit
    • Official User Guide
    • Community content
      • Blog
      • Tutorials

This creates a nice separation, allowing for additional implementations, easy migration, and the opportunity for separate maintainers to take ownership of separate content.

Edit: One more benefit could be making it easy for the inline documents as a part of a self-hosted farmOS instance, like @Symbioquine is advocating for.

1 Like

Haha I’m glad you emphasized that. I totally agree - didn’t mean to downplay/underestimate the effort there. :slight_smile:

  • Aggregate documentation for 2.x
  • Rebranding

I wonder if we could consider swapping these two? farmOS 2.x is coming fast! It would be awesome if we could launch it with a rebrand at the same time.

1 Like

I love this idea! Especially the idea of having a repo specifically for “blog” content, which we could assign maintainership to, to others in the community who want to help! Having all these pieces in separate repos is really nice in that way.

1 Like

Seems wise just to keep the effort low on the 1.x side… leave the stuff that’s 1.x-specific in its current mkdocs format - just copy it into a new repo, hack up the branding so it’s clear that it’s for the “old 1.x farmOS”, and publish under


@Symbioquine Yea I like that approach… I want to put 1.x behind us (maybe before we’re ready to haha), and it simplifies the requirements for a redesign if we don’t need to consider it.

Ok, so I think I’m going to chunk out these first two milestones listed above as a work proposal in a separate topic (per the process I outlined in Community Governance).

I will try to limit the scope of that proposal to the MVP of the Gatsby site and pulling in the 2.x docs (using the farmOS/farmOS#2.x branch as source) as a proof-of-concept that the gatsby-source-git plugin works as intended.

Meanwhile, should we continue the discussion here of how to migrate hosting, arrange repos, move project documentation into those projects’ corresponding repos, etc?

Some specific questions to ponder:

  • Should we aim to point at the proposed Gatsby site once its stable, so we can start using that for all 2.x docs prior to the rebranding?
  • Do we want to keep using the subdomain once the rebranding is complete, or use a a more centralized subdirectory structure, since we’ll no longer be limited by what we can do with GH Pages? (I think I favor the latter option)
  • How do we want to orchestrate moving docs for the Aggregator and Field Kit into their respective repos, similar to how @mstenta has done for the farmOS docs?
  • At what point do we want to move the User Guide into a separate repo? (plus lots of other related considerations around the maintenance of that repo)

Those seem like the most pressing concerns, assuming we’d still like to coordinate the redesign with the launch of 2.x-beta or 2.0 proper. We can also discuss the blog and other community content if someone wants to take ownership of that.

1 Like

I think we can cross some of these bridges when we get to them… we have some nice automation set up to auto-publish right now via GitHub Actions, so I’d want to make sure we have the same level of ease in a Gatsby-aggregated approach.

How do we want to orchestrate moving docs for the Aggregator and Field Kit into their respective repos, similar to how @mstenta has done for the farmOS docs?

The Aggregator docs are already in their own repo (just in a now):

We do need to figure out the User Guide… which currently has both farmOS and Field Kit info in it.

At what point do we want to move the User Guide into a separate repo? (plus lots of other related considerations around the maintenance of that repo)

This needs more dedicated thought. We will have a 1.x User Guide, which I think we can just set up as a legacy site on or something… and we will have a 2.x User Guide, which we are talking about building directly into farmOS itself: Inline user guides

That doesn’t include “contrib module” user guides, though, nor does it include Field Kit. So perhaps we should think about ways in which we can pull a “master” user guide together from multiple sources. This could include user guides from ALL modules (and other repos), whereas the “inline” guide would only have content for the modules that are enabled.