Fork me on GitHub


How to Contribute to Teleport's Documentation


This guide describes the general workflow for making documentation changes. It assumes you already have Node >=14 and yarn installed.

Step 1/4 Set up your local environment

Clone the gravitational/docs repository via git clone:

git clone

Different versions of the documentation are organized into the content directory of gravitational/docs. Each subdirectory of content includes a git submodule for a different branch of gravitational/teleport.

Navigate to the root of your local clone of the gravitational/docs repository and run the following command to populate the content directory:

yarn git-update

Next, navigate to the directory under content that corresponds to the latest version of Teleport.

cd content/13.x

Switch to the master branch (or versioned branch for updates specific to previous versions):

git switch master

Check out a new branch of gravitational/teleport.

git switch -c my-branch

Step 2/4 Test your changes

Run the following command to start the development server:

yarn install
yarn dev

You can visit the docs site at localhost:3000/docs. The development server will detect changes to the documentation automatically as you make them and refresh the page within the browser.

Validate your changes locally using the provided linters:

Check your Markdown syntax

yarn markdown-lint

markdown-lint, but also checks that external links work

yarn markdown-lint-external-links

Step 3/4 Create a pull request

Commit your changes and push your branch to gravitational/teleport (if you work at Teleport) or a fork of gravitational/teleport.

If you are an external contributor, create a fork and push to it.

This command assumes that you have created an SSH key pair and stored

your public key in GitHub.

git remote add fork ssh://[email protected]/my-user/teleport
git rebase origin/master
git push -u fork my-branch

Visit and create a pull request (PR) against your branch. Our continuous integration (CI) pipeline will automatically assign reviewers to your PR. The best way to ensure that your PR is merged is to respond to reviewer feedback in a timely manner. If feedback goes unaddressed your PR may be closed due to inactivity. Please merge your PR as soon as possible once you have received all required approvals.

Step 4/4 Backport your changes

Since our docs site is versioned, we want to ensure that any changes you make to the most recent version of our documentation are reflected for the versions of Teleport we currently support.

Supported Versions

You can find our list of currently supported versions in the FAQ.

There are many ways to create a backport, and we will illustrate three common methods for backporting Teleport documentation PRs.

When you open a pull request, add labels of the format backport/branch/v[0-9]+ to backport your PR to different versioned branches of gravitational/teleport.

For example, to backport a change to v10 of the documentation, you would add the label, backport/branch/v10.

When you merge your PR, our continuous integration pipeline will create a table of links in the comments of the PR that let you create additional PRs for your backports.

The label method will fail for forks of gravitational/teleport.

Navigate to the root of your gravitational/teleport clone and run the following command, assigning the PR variable to the ID of your GitHub PR and the TO variable to a comma-separated list of versioned branch names:

PR=0000 TO=branch/v10 make backport

This script will automatically generate backport branches and open PRs for them.

The make backport method will fail for forks of gravitational/teleport.

If automatic backport methods have failed, you will need to backport manually.

We will illustrate a backport for Teleport version 8.x.x. In this example, we have created a PR against origin/master from the branch my-branch, which has been committed to our fork.

Copy the hash of the commit we made to my-branch, then run the following commands:

git fetch origin
git switch branch/v8
git switch -c my-branch-backport-v8
git cherry-pick <commit-hash>
git push -u fork my-branch-backport-v8

Finally, create a PR for your backport.

Next steps

  • Consult our style guide to ensure your docs page is consistent with the rest of our docs.
  • Use our UI reference to find the right UI components for your needs.