Here is the static website that is hosted at community.hachyderm.io.

• Changes to the website should not (yet) delete Markdown files from where they used to live in the parent directory of this repository.
• We updated the site theme from Docsy v0.5.1 to v0.6.0 on 19 Jan 2023. If you have pending edits from before that time please make sure they work with the theme update.
• In order to submit PRs / make changes to this repo, you must sign the Nivenly Foundation Contributor License Agreement:
  https://cla.nivenly.org/

For the Contributor License Agreement:

• The Nivenly Foundation is the non-profit we're spinning up to house Hachyderm, Aurae, and other OSS Projects.
• Hachyderm and Aurae inherit their CLAs from Nivenly
• The CLA-bot will auto-reject PRs made by those who haven't signed the CLA

You must have Hugo and Go installed to build the site.

• Go Installation Instructions are here.
  • If you are using macOS you can install Go with brew.
• Hugo Installation Instructions are here.
  • If you are using macOS you can install Hugo with brew.

Optional: for local development we recommend using tmux. This will allow you to have the hugo server running in one window and whatever edits you need to make in another. By default, hugo serve outputs INFO, WARN, ERROR events, which are handy if a local change has unexpected build issues.

Once you have Go, Hugo, and optionally tmux installed you will be able to clone and build the site. The site uses the Docsy theme as a submodule.

Note: you will need to clone via SSH (not HTTPS) to build the submodule (more on the submodule in a moment).

git clone [email protected]:hachyderm/community.git
cd community/community.hachyderm.io

(GitHub documentation on cloing via SSH or HTTPS)

To try and make the build process easier, you can make use of the make commands provided in the Makefile. To list the commands and their descriptions, run:

make help

The make dev command in particular is useful, as it will build the submodule and run the Hugo server in order to see how the website is rendering (or not) locally. If you ever need to build the submodule separately, run:

make submodule

To start the development server, run the following command in the community/community.hachyderm.io directory:

make dev

The first time you run the command, since the submodule won't have been downloaded / built yet, it will take a little longer. Subsequent runs will be faster. Once ready, the local dev site can be viewed at:

localhost:1313

Note: You should not use Docker to locally work on the Community Docs, only Hugo. Docker is for the build pipeline only.

The Hachyderm Blog is only for when we post updates like post-mortems. When making changs as a member of the community, unless you are a making a PR for a typo fix or similar, you should be making PRs against the Community Docs.

Since the docs are documentation files rather than blog posts, the header information that is generated by hugo new needs to be edited. (More about the header in a moment.) Alternatively, if you are familiar with the Hugo directory and file structure, you can use Linux commands to make the directories and files that you need.

If you are looking to create a doc in a new category, you should enter the following where NEW_CATEGORY is the name of the category:

hugo new NEW_CATEGORY/_index.md

If you are loooking to create a new doc in an existing category:

hugo new EXISTING_CATEGORY/filename.md

If you are looking to create a new subcategory of a category (you must create the parent category if it doesn't yet exist):

hugo new EXISTING_CATEGORY/NEW_SUBCATEOGRY/_index.md

The above commands put everything in the parent directory: content/en/docs

All docs are in the content/en/docs as the parent directory. If you wish to create the directories and files via mkdir and touch or similar, you will need to do something similar to the following assuming you are in the community.hachyderm.io directory (this directory):

mkdir content/en/docs/NEW_PARENT_DIR/
touch content/en/docs/NEW_PARENT_DIR/_index.md

Or for a new file in an existing category:

touch content/en/docs/PARENT_DIR/newfile.md

If you need to create a few categories, make sure you use the -p flag so the parent and subdirectories are created if you need to nest them.

In order for the files to display on the nav menu both of the following must be true:

• All directories must have an _index.md file in them, at a minimum
• The _index.md file must have the correct header (next section)

As mentioned, since the docs pages are not a blog structure they have a slightly different header, which looks like so:

---
title: "Tab / Page Title"
linkTitle: "Title As Appears on Nav Menu"
weight: 40
description: >
  Your single or multiline description goes here.
---

Your content goes here.

The weight is somewhat important to know. Since there are no dates (in the blog sense) on documentation files the weight determines the order. By default, all files of the same weight are alphabetized.

By default, we use 40 as a weight value. For anything that needs to be put to the top or bottom of a category, we recommend using 10 (or less) or 100 respectively to force it to the top or bottom. This should only be done in specific circumstances though - in general, for user readability, the docs should be in alphabetical order and titled in ways that match what a user would be looking for.