# farmOS blog/tutorials

**URL:** <https://farmos.discourse.group/t/farmos-blog-tutorials/976>\
**Category:** Community\
**Created:** [November 11, 2021, 2:42pm UTC](https://farmos.discourse.group/t/farmos-blog-tutorials/976 "2021-11-11T14:42:35Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![jgaehring](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/jgaehring/32/927_2.png) [@jgaehring](https://farmos.discourse.group/u/jgaehring)\
**Post date:** [November 11, 2021, 2:42pm UTC](https://farmos.discourse.group/t/farmos-blog-tutorials/976/1 "2021-11-11T14:42:35Z")

</div>

On [yesterday’s monthly call](https://farmos.discourse.group/t/farmos-monthly-call-10-november-2021/971/3), we talked about starting a repository to host a farmOS “blog”, primarily for posting tutorials, workflows and “recipes” etc as a supplement to the user guide.

For 2.x, I think the consensus is to limit the user guide to the most essential functionality of farmOS, without too much elaboration, so it is less susceptible to breaking changes with newer versions. Then the tutorials, which can be timestamped and also indicate the version they were written for, can augment that with greater details, but aren’t required to be maintained as rigorously as the user guide.

With the [new farmos.org I’m building with Gatsby](https://farmos.discourse.group/t/farmos-org-redesign/505), which can pull from multiple source repositories, it makes sense to me to have a separate repository for this content, which can be managed independently by the community, separate from the project repositories, like farmOS and farmOS.py, but also separate from the Gatsby repo itself, so the content could be ported to other sites, if and when the need arose. I think it would be nice, too, if other community members wanted to take ownership of it and maintain it, so it’s not all on me or whoever else maintains [farmos.org](http://farmos.org) to also shoulder responsibility for the content as well.

So would it make sense to start a repository now, so we can add it as a source repo to the new Gatsby site, and open up the potential to start taking contributions? Perhaps we could even shoot to get this up and running by the time farmOS 2.0.0-beta is ready for release, since that will mark a point when we start bringing on beta testers, who might want to use and/or contribute to that content?

CC’ing @mikefarms who seemed interested in this possibility when we discussed it yesterday.

---

<div class="post-metadata">

**Author:** ![jgaehring](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/jgaehring/32/927_2.png) [@jgaehring](https://farmos.discourse.group/u/jgaehring)\
**Post date:** [November 11, 2021, 2:43pm UTC](https://farmos.discourse.group/t/farmos-blog-tutorials/976/2 "2021-11-11T14:43:28Z")

</div>

Oh, and a nice thought I had just now too… For the tutorials we can use branches or tags that correspond to different versions of farmOS and pull those in as separate sources… then we can have a toggle on each tutorial page if it has examples for older versions, kind of how Digital Ocean does:

> **[How to Set Up SSH Keys on Ubuntu 20.04 | DigitalOcean](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys-on-ubuntu-20-04)**
>
> In this guide, we'll focus on setting up SSH keys for an Ubuntu 20.04 installation. SSH keys provide an easy, secure way of logging into your server and are recommended for all users.

Anyways, just a thought, perhaps for a stretch goal.

---

<div class="post-metadata">

**Author:** ![mikefarms](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/mikefarms/32/477_2.png) [@mikefarms](https://farmos.discourse.group/u/mikefarms)\
**Post date:** [November 12, 2021, 4:00pm UTC](https://farmos.discourse.group/t/farmos-blog-tutorials/976/3 "2021-11-12T16:00:38Z")

</div>

> [@jgaehring](#):
>
> So would it make sense to start a repository now, so we can add it as a source repo to the new Gatsby site, and open up the potential to start taking contributions?

@jgaehring, thanks so much for following up. I would love to help with this, maybe with a quick test tutorial on a topic that’s come up while I’ve been coming up to speed (mail server!). Some questions:

- Any good tutorial has the ability to embed pics/screenshots - should those go in the same directory as the md file or a subdirectory with a name convention? If possible, I’d recommend each tutorial just be in a flat directory on its own in the repository.
- What tag structure do you want? Should I use [this Gatsby explanation](https://www.gatsbyjs.com/docs/adding-tags-and-categories-to-blog-posts/) as a basis for our convention? What would you like to see?
- How would you like me to check this test tutorial into Github? Which repository should I add to and create a pull request for? Or do you want me to create a test repository of my own and send you the link first?

---

<div class="post-metadata">

**Author:** ![jgaehring](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/jgaehring/32/927_2.png) [@jgaehring](https://farmos.discourse.group/u/jgaehring)\
**Post date:** [November 12, 2021, 8:24pm UTC](https://farmos.discourse.group/t/farmos-blog-tutorials/976/4 "2021-11-12T20:24:25Z")

</div>

> [@mikefarms](#):
>
> Any good tutorial has the ability to embed pics/screenshots - should those go in the same directory as the md file or a subdirectory with a name convention? If possible, I’d recommend each tutorial just be in a flat directory on its own in the repository.

💯

Yea, I like having a directory for each tutorial, and keeping those all in a `content` or `tutorials` directory. That’s how I do it for [my own blog](https://github.com/jgaehring/jgaehring.com/tree/main/src/blog/farm-data-as-value-added), basically a structure like this:

```plaintext
content/
├─ how_to_create_a_log/
│ ├─ index.md
│ ├─ screenshot1.jpg
└─ how_to_create_an_asset/
   ├─ index.md
   └─ assetpage.jpg

```

Then from within `content/how_to_create_a_log/index.md` you would just reference the image like this:

```md
![Title text](screenshot1.jpg)

```

For that to work, all I need to do is install the plugins [gatsby-plugin-sharp](https://www.gatsbyjs.com/plugins/gatsby-plugin-sharp) and [gatsby-remark-images](https://www.gatsbyjs.com/plugins/gatsby-remark-images/) and add them to `gatsby-config.js` with the proper settings. I was planning to do that eventually and it should be pretty straightforward.

> [@mikefarms](#):
>
> What tag structure do you want?

We’ve already got support for [Front Matter](https://jekyllrb.com/docs/front-matter/), which is the type of header you see in that Gatsby tutorial on tags. I think `title`, `date` and `path` (or `slug`) are good variables to start with. I would probably hold off implementing anything to display or use a `tags` variable, at least while we’re still prototyping this, but you could still add `tags` to the Front Matter of any post for the time being and it wouldn’t hurt anything (basically they’ll just be ignored). Other useful variables could be something like `post-type` to indicate if it’s a tutorial, blog post, news item, etc; a `thumbnail` var that can be set to the filename of an image in the post’s subdirectory; a `projects` var that could look something like this:

```yaml
projects:
  - name: farmOS
    versions:
      - 2.0.0
      - 2.1.0
  - name: Field Kit
    versions:
      - 0.8.2
      - 2.0.0-alpha.1

```

Really no limit to the custom vars we could use, but it will be important to settle on some kind of conventions.

> [@mikefarms](#):
>
> How would you like me to check this test tutorial into Github? Which repository should I add to and create a pull request for? Or do you want me to create a test repository of my own and send you the link first?

We don’t have a repository set up for this yet, but if you want to start playing around with it, feel free to start your own! If other folks are on-board with it, we can discuss making it an official repo, or figure out where else we want it to live long-term. Once you have some content to test out, I can create a branch in the Gatsby repo, add your repo as a source, and set up a preview deployment for testing it out.

---

<div class="post-metadata">

**Author:** ![jgaehring](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/jgaehring/32/927_2.png) [@jgaehring](https://farmos.discourse.group/u/jgaehring)\
**Post date:** [December 7, 2021, 11:27pm UTC](https://farmos.discourse.group/t/farmos-blog-tutorials/976/5 "2021-12-07T23:27:10Z")

</div>

An update on my part:

I’ve made some progress in the last couple days adding a second source repository to the new website I’m working on for [farmos.org](http://farmos.org). Still a work in progress, but [the preview is live](https://gracious-brattain-bdd606.netlify.app/).

Obviously there’s plenty more work to be done. It’s still just a skeleton around the documentation pages, without a real home page. There are lots of little technical issues to resolve, but imo, the biggest issues are all a matter of design decisions, like how to structure navigation between the different sources etc.

Most pertinent to this topic, I still need to integrate Front Matter into how the site map, page layouts and navigation are built. That capability’s there, the plugin’s already installed, now I just need to put it to use. That will have to go hand in hand with decisions about what the Front Matter should contain, which is really a blank slate, but should be consistent. As I said above:

> [@jgaehring](#):
>
> I think `title` , `date` and `path` (or `slug` ) are good variables to start with.

So yea, I noticed @mikefarms and @Farmer-Ed have brought this up in [Sensor Graph OK, but Sensor Data field empty](https://farmos.discourse.group/t/sensor-graph-ok-but-sensor-data-field-empty/993), which is great to see!

If folks have other feedback to provide, please don’t hesitate to drop your comments below.

---

<div class="post-metadata">

**Author:** ![Farmer-Ed](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/farmer-ed/32/662_2.png) [@Farmer-Ed](https://farmos.discourse.group/u/Farmer-Ed)\
**Post date:** [December 8, 2021, 8:34pm UTC](https://farmos.discourse.group/t/farmos-blog-tutorials/976/6 "2021-12-08T20:34:06Z")

</div>

@jgaehring It was good to listen in on the call today. As you have seen I tend to document the farm tech projects I’m working on to my Blog, its for my own future reference as much as anything else. I’d be happy to copy some across when your Repo is ready. I’ll have a few more to do anyway as I’ll soon need to migrate to 2.0.

---

<div class="post-metadata">

**Author:** ![jgaehring](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/jgaehring/32/927_2.png) [@jgaehring](https://farmos.discourse.group/u/jgaehring)\
**Post date:** [December 9, 2021, 6:09pm UTC](https://farmos.discourse.group/t/farmos-blog-tutorials/976/7 "2021-12-09T18:09:03Z")

</div>

Awesome, and thanks for offering to share that content, @Farmer-Ed. I’ll keep you posted when we’re ready for that.

I’ll also make sure to include some sort of `canonical` property for Front Matter, too, and provide a link back to your blog for any material you share.

---

<div class="post-metadata">

**Author:** ![jgaehring](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/jgaehring/32/927_2.png) [@jgaehring](https://farmos.discourse.group/u/jgaehring)\
**Post date:** [December 22, 2021, 6:25pm UTC](https://farmos.discourse.group/t/farmos-blog-tutorials/976/8 "2021-12-22T18:25:13Z")

</div>

Ok, so a big step towards making it a reality, today we just launcehd the new [farmOS.org](http://farmOS.org)!

> **[farmOS](https://farmos.org)**
>
> farmOS is a free and open source web-based application for farm management, planning, and record keeping.

It’s not a whole lot different, but the significant aspect of this is that we now have the ability to feed content to the site from separate source repositories, as I mentioned at the top of this thread. No such blog/tutorials repository exists yet, but it we should certainly move forward with creating one in the new year, perhaps during the next [monthly call](https://farmos.org/community/monthly-call), or perhaps through a separate discussion in the [farmOS community Jitsi room](https://meet.jit.si/farmos-community).

---

<div class="post-metadata">

**Author:** ![jgaehring](https://yyz2.discourse-cdn.com/free1/user_avatar/farmos.discourse.group/jgaehring/32/927_2.png) [@jgaehring](https://farmos.discourse.group/u/jgaehring)\
**Post date:** [January 8, 2022, 9:52pm UTC](https://farmos.discourse.group/t/farmos-blog-tutorials/976/9 "2022-01-08T21:52:02Z")

</div>

Just want to let folks on this thread know we’ll be discussing these ideas on Wed’s community call:

> [@Call for Content!](https://farmos.discourse.group/t/call-for-content/1042):
>
> For a while now we’ve been developing the idea of creating a section of the farmOS website for community contributed content, specifically [blog posts and tutorials](https://farmos.discourse.group/t/farmos-blog-tutorials/976) about how people are using farmOS in their daily workflow. Now that we’re moving ahead with the [redesign of farmos.org](https://farmos.discourse.group/t/farmos-org-redesign/505), having completed the initial [scaffolding](https://farmos.discourse.group/t/work-proposal-scaffold-a-new-gatsby-site-for-farmos-org-2-x-docs/699) phase, there are no more technical barriers to adding this content to the site, beyond starting a GitHub repository for that content. Such content would benefit the entire co…