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
Step 1/4 Set up your local environment
gravitational/docs repository via
git clone https://github.com/gravitational/docs
Different versions of the documentation are organized into the
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
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
Step 2/4 Test your changes
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
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
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. 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.
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
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.
- 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.