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
gravitational/docs repository via
git clone https://github.com/gravitational/docs
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
Navigate to the root of your local clone of the
gravitational/docs repository and run the following command to populate the
Next, navigate to the directory under
content that corresponds to the latest version of Teleport.
Switch to the master branch (or versioned branch for updates specific to previous versions):
git switch master
Check out a new branch of
git switch -c my-branch
Run the following command to start the development server:
yarn installyarn 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 syntaxyarn markdown-lint
markdown-lint, but also checks that external links workyarn markdown-lint-external-links
Commit your changes and push your branch to
gravitational/teleport (if you
work at Teleport) or a fork of
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/teleportgit rebase origin/mastergit push -u fork my-branch
Visit https://github.com/gravitational/teleport and create a pull request (PR) against your branch. Our continuous integration (CI) pipeline will automatically assign reviewers to your PR.
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.
You can find our list of currently supported versions in the FAQ: https://goteleport.com/docs/faq/#which-version-of-teleport-is-supported
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
to backport your PR to different versioned branches of
For example, to backport a change to v10 of the documentation, you would add the
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
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
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.
make backport method will fail for forks of
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
git fetch origingit switch branch/v8git switch -c my-branch-backport-v8git cherry-pick <commit-hash>git push -u fork my-branch-backport-v8
Finally, create a PR for your backport.