You can contribute to the PostHog documentation, handbook, and blog in two ways:
- 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.
- 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.
Running posthog.com locally
Type the following into the terminal and press return:
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:
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
8080you'll be asked if you are okay in running on port
8081, in which case the website will be accessible on
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.
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,
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 TitlesidebarTitle: Example title shown in sidebarsidebar: Example SidebarshowTitle: 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
sidebarTitle: the title shown in the sidebar. If this value isn't provided the
titleproperty is used.
showTitleshould always be set to
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.
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:
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:
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.
Links to/from the navigation
Once you've made a new markdown file, you should link to it from the sidebar where appropriate.
The sidebar is generated from
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.
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.
Create a Pull Request
Create a Pull Request to request that your changes be merged into the main branch of the repository.
If you are pushing to an existing branch, navigate to the posthog.com repo and switch to the new branch using the dropdown:
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.
To get changes into production, the website deploys automatically from
master. The build takes 5-10 minutes.