Contribute to the website: documentation, handbook, and blog

Last updated:

You can contribute to the PostHog documentation, handbook, and blog in two ways:

  1. You can create a Pull Request in GitHub for any page that has an Edit this page link on it. In this situation you must edit the page using the GitHub web editor interface. This method is suitable for text-only edits and basic file manipulation, such as renaming.
  2. You can run the posthog.com website locally and make changes there by creating a branch of the master codebase, committing changes to that branch and raising a Pull Request to merge those changes. This is the recommended method as it allows you to quickly preview your changes, as well as perform more complex changes easily.

Below, we'll explain how to set up option two.

Should I use the terminal or GitHub desktop?
This guide explains how to make changes either in the terminal, or via Github Desktop. If you're unfamiliar with the terminal or GitHub, we recommend using GitHub Desktop to make changes. You may also find GitHub's glossary of terms to be a helpful reference if you're entirely new to GitHub.

Editing posthog.com locally

Before you begin

In order to run the PostHog website locally, you need the following installed:

Optionally, if you are unfamiliar with using Git from the command line, you will need the following installed:

You may also want to familiarize yourself with these resources:

Cloning the posthog.com repository

The codebase for posthog.com is on GitHub.

Via the terminal

You can clone the codebase from the terminal using the following command:

git clone git@github.com:PostHog/posthog.com.git

Via GitHub Desktop

You can also clone the repository with GitHub desktop installed, from the posthog.com repository page, click the Code button and select Open with GitHub Desktop from the dropdown that appears.

Open in GitHub Desktop

You will then be prompted by the browser to confirm if you want to open the GitHub Desktop application. Select the affirmative action that has text such as Open GitHub Desktop.

Once GitHub Desktop has opened you will be prompted to confirm the repository that is being cloned and the location on disk where you wish the code to be stored.

GitHub Desktop clone to dialog

Click Clone to clone the posthog.com repostory to your local disk.

GitHub Desktop cloning to disk

Once the clone has completed the GitHub Desktop interface will change to the following:

GitHub Desktop cloned successfully

To view the code for the website click Open in Visual Studio Code. Dialogs may appear around permissions and trust as you open Visual Studio Code.

Once you have Visual Studio Code open, select the Terminal menu option. Within the dropdown select New Terminal. This will open a new terminal window within Visual Studio Code:

Visual Studio Code terminal

Don't worry! We only need to run a few commands in the terminal.

Running posthog.com locally

Type the following into the terminal and press return:

yarn

This runs the Yarn tool. Run standlone like this, it installs the dependency packages used by posthog.com. This may take a few minutes.

Once this command has finished executing, run the following:

yarn start

The runs the local clone of the website, which you can use to preview changes you make before pushing them live. It takes a bit of time for some file processing and compilation to take place, but once it's completed you can access the locally running version of posthog.com via by visiting http://localhost:8080 in your web browser.

Any time you want to preview changes you are making to the local version of the website, all you have to do is run the yarn start again, wait for the command to finish running and then open http://localhost:8080 in your web browser.

If you have something else running on port 8080 you'll be asked if you are okay in running on port 8081, in which case the website will be accessible on http://localhost:8081.

Finding the content to edit

Once you have cloned the repo, the contents/ directory contains a few key areas:

  • docs/ = all of the documentation for PostHog's platform
  • handbook/ = the PostHog company handbook
  • blog/ = our blog posts

Inside each of these are a series of markdown files for you to edit.

Making edits

Creating a new Git branch

When editing locally, changes should be made on a new Git branch. Branches should be given an "at a glance" informative name. For example, posthog-website-contribution.

Via the terminal

You can create a new Git branch from the terminal by running:

git checkout -b [new-branch-name]

For example:

git checkout -b posthog-website-contribution

Via GitHub Desktop

You can also create a new branch in GitHub Desktop by selecting the dropdown next to the Current Branch name and clicking New Branch.

GitHub Desktop - new branch dropdown

Then, in the dialog that follows, entering the new branch name.

GitHub Desktop - new branch dialog

Once you have a new branch, you can make changes.

Markdown details

Frontmatter

At the top of most posthog.com docs and handbook pages, it is necessary to have the following for the page to appear:

---
title: Example Title
sidebarTitle: Example title shown in sidebar
sidebar: Example Sidebar
showTitle: true
---
  • title: the page title
  • sidebar: the sidebar menu that the page will attach to. You can see a list of available sidebars in /src/sidebars/sidebars.json. You can choose not to have a sidebar by setting this to null.
  • sidebarTitle: the title shown in the sidebar. If this value isn't provided the title property is used.
  • showTitle should always be set to true.

Some pages, such as blogposts, may have additional fields. You can often refer to the source of existing pages for examples, but if in doubt you can always ask for help in the PostHog Community Slack.

Images/GIFs

For our Markdown, we use gatsby-remark-copy-linked-files.

This copies local files linked to/from Markdown files to the root directory.

If you need to upload images, you can place them in contents/images/. We recommend creating or using existing subfolders to keep images organized.

To include an image in a markdown file, you can use nice local references, like so:

![Twin Peaks](../images/02/IMG_4294-scaled.jpg)

In this case, Twin Peaks is the alt-text applied to the image.

Note that it may be necessary to change the folder depending on your file structure. For example, if you needed to go up two directories, this could be:

![Twin Peaks](../../images/02/IMG_4294-scaled.jpg)

Notice the extra ../.

For most images, this plugin will automatically generate a range of sizes to optimize for the device and they'll even have a blurry low filesize loading image created to hold the place. Pretty cool.

Once you've made a new markdown file, you should link to it from the sidebar where appropriate.

The sidebar is generated from /src/sidebars/sidebars.json.

Committing changes

It's best to create commits that are focused on one specific area. For example, create one commit for textual changes and another for functional ones. Another example is creating a commit for changes to a section of the handbook and a different commit for updates to the documenatation. This helps the Pull Request review process and also means specific commits can be cherry picked.

Via the terminal

First, stage your changes:

git add [path-to-file]

For example:

git add contents/docs/contribute/updating-documentation.md

Once all the files that have been changed are staged, you can perform the commit:

git commit -m '[short commit message]'

For example:

git commit -m 'Adding details on how to commit'

Via the GitHub Desktop

Files that have been changed can be viewed within GitHub Desktop along with a diff of the specific change.

Viewing changes in GitHub Desktop

Select the files that you want to be part of the commit by ensuring the checkbox to the left of the file is checked within GitHub Desktop. Then, write a short descriptive commit message and click the Commit to... button.

Making a commit in GitHub Desktop

Push changes to GitHub

In order to request that the changes you have made are merged into the main website branch you must first push them to GitHub.

Via the terminal

git push origin [branch-name]

For example:

git push origin posthog-website-contribution

When this is done, the terminal will show output similar to the following:

posthog-website-contribution $ git push origin posthog-website-contribution
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: Create a pull request for 'posthog-website-contribution' on GitHub by visiting:
remote: https://github.com/PostHog/posthog.com/pull/new/posthog-website-contribution
remote:
To github.com:PostHog/posthog.com.git
* [new branch] posthog-website-contribution -> posthog-website-contribution

This output tells you that you can create a pull request by visiting a link. In the case above, the link is https://github.com/PostHog/posthog.com/pull/new/posthog-website-contribution. Follow the link to complete your pull request.

Via GitHub Desktop

Once you have committed the changes you want to push to GitHub, click the Push origin button.

Push to origin from GitHub Desktop

Create a Pull Request

Create a Pull Request to request that your changes be merged into the main branch of the repository.

Via the terminal

Navigate to the link shown when you push your branch to GitHub. For example, https://github.com/PostHog/posthog.com/pull/new/posthog-website-contribution shown below:

posthog-website-contribution $ git push origin posthog-website-contribution
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: Create a pull request for 'posthog-website-contribution' on GitHub by visiting:
remote: https://github.com/PostHog/posthog.com/pull/new/posthog-website-contribution
remote:
To github.com:PostHog/posthog.com.git
* [new branch] posthog-website-contribution -> posthog-website-contribution

Via GitHub Desktop

With the branch published, click the Create Pull Request button.

Pull Request from GitHub Desktop

This will open up a page on github.com in your default web browser.

If you are pushing to an existing branch, navigate to the posthog.com repo and switch to the new branch using the dropdown:

GitHub branch switcher

Then, open the Contribute dropdown and click the Open pull request button.

Make the Pull Request title descriptive name and complete the detail requested in the body.

If you know who you would like to review the Pull Request, select them in the Reviewers dropdown.

Deployment

To get changes into production, the website deploys automatically from master. The build takes 5-10 minutes.

Acknowledgements

This website is based on Gatsby and is hosted with Netlify.