Adding Content #

Introduction#

This document will guide you through the process of adding a new page to the handbook.

Tip

The handbook is built using MkDocs and Material for MkDocs. These tools also have extensive documentation and guides for contributing to a Mkdocs project.

Please refer to their respective documentation first for any questions you might have.

Adding Content to the Documentation#

The documentation is written in Markdown and can be found in the docs directory.

Here are the steps to add new content to the documentation:

1. Create a branch for your changes#

Note: Naming your branch

A branch is a way to work on a new feature or bug fix without affecting the main branch. The standard for this project is to use the following format:

$ <author-ID>/<purpose-of-branch>
OR
$ <author-ID>/<issue-reference>

Where <author-ID> can be a GitHub username or an alias.

<purpose-of-branch> is a short description of the changes you are making. <issue-reference> is the number of the issue you are working on.

For example:

$ jjjermiah/adding-getting-started-page
OR
$ jjjermiah/13-docs-finish-tutorial-for-page-review

To create a new branch and switch to it, run the following command:

git checkout -b <branch-name>
$ git checkout -b jjjermiah/adding-getting-started-page

If you already have a named branch, you can switch to it with the following command:

git switch <branch-name>
$ git switch jjjermiah/adding-getting-started-page

2. Add your new content to the `docs` directory#

How do I know where to create my file?

The command below will create an empty Markdown file called my_new_page.md in the docs/onboarding directory. The relative path to the docs directory, will be the link to your new page.
i.e the link to your new page will be <website-url>/handbook/onboarding/my_new_page/

Let's say you want to add a new page to the Onboarding section. You would add a new file to the docs/onboarding directory.

$ touch docs/onboarding/my_new_page.md
You should now see a new file at `docs/onboarding/my_new_page.md`.

To learn more about how to actually write content, see the Handbook MkDocs Page and Handbook Markdown page.

3. Preview your changes#

The following is a pixi task that will start a local server and preview the documentation at http://localhost:8001 (aka http://127.0.0.1:8001).

$ pixi run serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
...
INFO    -  [08:55:05] Serving on http://127.0.0.1:8001/handbook/

You should see your changes appear at http://127.0.0.1:8001/handbook/onboarding/my_new_page/

Tip

You can set the handbook website to automatically open in your default browser by using the -o flag:

pixi run serve -o

About the port number

By default, we host the local site on port 8001 because it is more likely to be unused and available for the local server to use. In the case that you would like to manually specify a different port (e.g. if it's in use by something else), you can use the -a flag after pixi run serve.

For example, to run on port 1234:

pixi run serve -a localhost:1234

4. Commit and push your changes to your branch#

git add .
git commit -m "Add new getting started page"
git push --set-upstream origin jjjermiah/adding-getting-started-page

5. Create a PR#

Create a pull request (PR) to merge your changes into the main branch. Request a review from a maintainer.

See the section on Reviewing a Contribution for more information.

Adding Content#