Fork me on GitHub
Teleport

How to Contribute to Teleport's Documentation

Improve

This guide describes the general workflow for making documentation changes

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:

git submodule update --init --recursive

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

cd content/9.0

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

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: https://goteleport.com/docs/faq/#which-version-of-teleport-is-supported

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.