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 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 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 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.

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

PR=0000 TO=branch/v10 make backport

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

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.