diff --git a/README.md b/README.md index 422524c308..d732f15227 100644 --- a/README.md +++ b/README.md @@ -22,12 +22,3 @@ following guides: available to documentation authors. - [Documentation style guide](docs-contributors/style-guide.md): Rules for maintaining consistent Teleport docs. - -## Docs engine development - -Read the following guides to learn how to work on the Teleport docs engine: - -- [Yarn command reference](docs-contributors/yarn-commands.md): `yarn` commands - available for development-related tasks. -- [Docs configuration guide](docs-contributors/config-guide.md): Options for - configuring the Teleport docs site. diff --git a/docs-contributors/config-guide.md b/docs-contributors/config-guide.md deleted file mode 100644 index d7a169ed87..0000000000 --- a/docs-contributors/config-guide.md +++ /dev/null @@ -1,64 +0,0 @@ -# Configuring the Teleport docs site - -This guide explains the options and configuration files available for the -Teleport docs site. - -## `config.json` - -File that configures build options: - -- `versions` - array of the available options, should match the names of the folders inside `content` dir. Will be shown in the version select in inverted order. -- `redirects` - optional array of redirects. Uses [Next.js syntax](https://nextjs.org/docs/api-reference/next.config.js/redirects) inside. - -Format of version entry: - -- `name` - required. Name of the folder in `content` and name of branch in version's dropdown on the site. -- `branch` - required. Name of branch for this version. Will be used for `edit` links on the docs pages. -- `latest` - not required. First entry with this field will be current version. If no entries have this field, then the last version in array will be considered the latest. - -## Adding a new docs version - -- Add new submodule: `git submodule add -b branch/*.* https://github.com/gravitational/teleport/ content/*.*` where `branch/*.*` is the name of the branch in the main Teleport repo and `content/*.*` is the name of the subfolder in the `content` folder where the docs will be stored. Name of the folder inside `content` should match the name of the version in the config. Folder name itself can contain any characters allowed in the URL. E.g. `6.0-rc`. -- Add new entry to the `versions` array in `config.json` with name and branch field. -- Change `latest` field to the new value if you want to make it the default. - -### Changing the branch that the docs version is pointing to - -- Open `.gitmodules` file. -- Find corresponding record. For example, for version `4.4` it will look like this: - ```bash - [submodule "content/4.4"] - path = content/4.4 - url = https://github.com/gravitational/teleport/ - branch = branch/4.4 - ``` -- Change `branch` field to the new branch name. -- Run `yarn git-update` – this will update all submodules to the HEAD commits - of the corresponding branches. - -### Removing existing docs version - -Correct way to remove submodule: - -```bash -# Remove the submodule entry from .git/config -git submodule deinit -f path/to/submodule - -# Remove the submodule directory from the superproject's .git/modules directory -rm -rf .git/modules/path/to/submodule - -# Remove the entry in .gitmodules and remove the submodule directory located at path/to/submodule -git rm -f path/to/submodule -``` - -[Source](https://stackoverflow.com/a/36593218/1008291). - -### Adding a YouTube API Key - -At the root of the project, create an `.env.local` file. Inside this file, add the `YOUTUBE_API_KEY` variable with the API key's value: - -``` -YOUTUBE_API_KEY=[key-for-google-api] -``` - -Get the API key via these [instructions](https://developers.google.com/youtube/v3/getting-started#intro). diff --git a/docs-contributors/how-to-contribute.md b/docs-contributors/how-to-contribute.md deleted file mode 100644 index cde30211bf..0000000000 --- a/docs-contributors/how-to-contribute.md +++ /dev/null @@ -1,382 +0,0 @@ -# How to contribute to the Teleport documentation - -We encourage everyone with an interest in improving Teleport documentation -to contribute content, submit issues, and suggest changes. -This guide describes the process for making changes to the documentation whether -you are an internal or external contributor. - -## Prerequisites - -Before you begin, verify that your environment meets the following prerequisites: - -- You have a code editor, a GitHub account, and experience using command-line - programs, including `git` commands and command line options. -- You have Node.js, version 18.x or newer, installed. - Run `node --version` to check whether Node is installed. - If you need to install or update Node, see - [Installing Node.js](https://nodejs.org/en/download/package-manager) - for instructions to download and install Node.js using a package manager. -- You have the `yarn` package manager installed. - Run `yarn --version` to check whether `yarn` is installed. - If you need to install `yarn`, run the command `brew install yarn` or - `npm install --global yarn` to add it to your local system. - -## Step 1/5. Set up your local environment - -To set up a local environment for contributing to Teleport documentation: - -1. Open a terminal shell on your computer. - -1. Clone the `gravitational/docs` repository by running the following command: - - ```bash - $ git clone https://github.com/gravitational/docs --recurse-submodules - ``` - - This command clones the documentation submodules that correspond to the - different major release versions of the Teleport code. For example, there - are currently documentation submodules for the 11.x, 12.x, 13.x, and 14.x versions - of Teleport. - -1. Change to the root of the `docs` directory: - - ```bash - $ cd docs - ``` - -1. Update the documentation to the latest version from the master branch: - - ```bash - $ yarn git-update - ``` - -1. Install dependencies: - - ```bash - $ yarn - ``` - -## Step 2/5. Navigate to a specific version - -Different versions of the documentation are organized into the `content` directory of the -`gravitational/docs` repository. Each subdirectory of the `content` directory includes -a `git` submodule for a different branch of `gravitational/teleport`. - -To navigate to a specific version of the documentation: - -1. View the versions of the documentation listed in the `content` directory by running the following command: - - ```bash - $ ls -l content - ``` - -1. Change to the directory under `content` that contains the version of documentation you want to update. - For example, navigate to the directory that corresponds to latest version of Teleport: - - ```bash - # Set this to a major version number - $ TELEPORT_VERSION="" - $ cd content/${TELEPORT_VERSION?}.x - ``` - -1. Switch to the master branch by running the following command: - - ```bash - $ git switch master - ``` - - You can use a versioned branch if you want to update documentation for a specific previous version of Teleport. - However, it most cases, you should use the `master` branch. - -1. Create a new branch of `gravitational/teleport` for your changes by running a command similar to the following: - - ```bash - $ git switch -c my-branch - ``` - - You now have a branch for a specific version of the documentation content. - Before making any changes, note how the content is organized so you know where to find the files - to update. - - Within the `content/*.*` directory in your branch, there's a `docs` subdirectory. - The `content/*.*/docs` subdirectory contains the files and folders used to produce a specific version - of the documentation. - - The subdirectory includes the following: - - - The `img/` folder for images used inside the pages. - - The `pages/` folder for the Markdown files that contain documentation content. - Every file in this folder is rendered as a page. - - The `pages/includes` folder for content that's only rendered when it's included in the body of a page. - - The `config.json` file for configuring version information. - - You're now ready to make changes in your own branch using the code editor of your choice. - -## Step 3/5. Test changes locally - -As you make changes to the content in your local branch, it's helpful to see how the changes will be -rendered when the documentation is published. - -You can use `yarn` to run a development server that detects changes to the documentation and displays -them whenever you manually refresh the page in the browser. -You can also use `yarn` commands to check for errors and fix common issues. - -To test changes in your local environment: - -1. Change to the top-level `docs` directory in your local copy of the https://github.com/gravitational/docs repository. - -1. Start the development server by running the following commands: - - ```bash - $ yarn dev - ``` - -1. Open a web browser and navigate to the documentation using the URL `localhost:3000/docs`. - -1. Validate the Markdown syntax by running the following commends: - - ```bash - # Check your Markdown syntax - $ yarn markdown-lint - # markdown-lint, but also checks that external links work - $ yarn markdown-lint-external-links - ``` - - For more information about using `yarn` commands to work with Teleport documentation, - see the [README](https://github.com/gravitational/docs). - -## Step 4/5. Create a pull request - -If you're an internal contributor with permission to access the -[Teleport repository](https://github.com/gravitational/teleport), you can commit -changes and push branches directly to the repository. -If you're an external contributor, you can commit changes to your private branch -and push private branches to a fork of the Teleport repository. - -### Internal contributors - -If you work at Teleport: - -1. Add files and commit changes to your local branch periodically with commands similar to the following: - - ```bash - $ git add # Add a specific new file to be committed - $ git add -A # Add all changed files to the list of files to be committed - $ git commit -am "Fix or feature description" # Add and commit changes with a comment - $ git commit -m "Fix or feature description" # Commit changes already added - ``` - -1. Push your branch to `gravitational/teleport` with a command similar to the following: - - ```bash - $ git push origin my-branch - ``` - -1. Open the [Teleport repository](https://github.com/gravitational/teleport), select your branch as the branch to -merge into main, then click **New pull request**. - - The continuous integration (CI) pipeline automatically assigns reviewers to your pull request. - -1. Wait for the minimum required approvals, then merge your pull request as soon as possible. - -### External contributors - -If you are an external contributor, you must commit your changes to your branch and push your branch to a -fork of the `gravitational/teleport` repository. - -To push changes as an external contributor: - -1. Verify that you have an SSH key pair and have stored your public key in GitHub. - -1. Open the [Teleport repository](https://github.com/gravitational/teleport), click **Fork**, then select **Create a new fork**. - -1. Verify the owner and repository name. - -1. Click **Create fork**. - - Alternatively, you can create a fork from the command-line by running a command similar to the following: - - ```bash - $ git remote add fork ssh://git@github.com/my-user/teleport - ``` - - In this command, `my-user` represents your GitHub user name and `teleport` is the name of your Teleport repository fork. - -1. Pull all of the changes from the remote repository into your local fork by running the following command: - - ```bash - $ git fetch origin - ``` - -1. Push changes from your local branch to the remote fork of the [Teleport repository](https://github.com/gravitational/teleport) -by running a command similar to the following: - - ```bash - $ git push --set-upstream fork my-branch - ``` - -1. Open the [Teleport repository](https://github.com/gravitational/teleport), select your branch as the branch to merge into main, -then click **New pull request**. - - The continuous integration (CI) pipeline automatically assigns reviewers to your pull request. - To ensure that your pull request is merged, you should respond to reviewer feedback in a timely manner. - After you incorporate reviewer feedback, your pull request might require a companion—or *buddy*—pull request - to ensure that your changes conform to certain conventions and pass automated checks. - The companion pull request includes all of your commits to verify they pass CI/CD validation and continues - to identify you as the author of the changes committed. - - If you don't respond to reviewer feedback, your pull request is likely to be deemed inactive and closed. - -1. Wait for the minimum required approvals, then merge your pull request as soon as possible. - -## Step 5/5. Backport changes to earlier versions - -Because the docs site is versioned, we want to ensure that any changes you make to -the most recent version of the documentation are reflected in all of the appropriate versions of -Teleport we currently support. - -You can find our list of currently-supported versions in the [FAQ](../../faq.mdx#which-version-of-teleport-is-supported). - -There are many ways to create a backport. -The following methods represent the most common ways to backport changes for Teleport documentation: - -- By using GitHub labels (internal contributors) -- By using the make program (internal contributors) -- By selecting commit hashes manually (internal or external contributors) - -### Using GitHub labels - -You must be an internal contributor to use the GitHub label process to backport changes. -This method fails for forks of the `gravitational/teleport` repository. - -When you open a pull request, add labels of the format `backport/branch/v[0-9]+` -to backport your pull request to different versioned branches of the `gravitational/teleport` repository. - -For example, to backport a change to v13 of the documentation, add the label `backport/branch/v13` to the pull request. - -After you merge your pull request, the continuous integration pipeline creates a table -of links in the comments for the pull request. -You can then create an additional pull request for your each backport version you specified as a label. - -### Using `make` - -You must be an internal contributor and have Go installed in your environment to use the -`make backport` script to backport changes. This method fails for forks of the -`gravitational/teleport` repository. - -To use make: - -1. Navigate to the root of your `gravitational/teleport` clone. - -1. Run the following command to assign the `PR` variable to the ID of your original GitHub pull request and -the `TO` variable to a comma-separated list of versioned branch names: - - ```bash - $ PR=0000 TO=branch/v10 make backport - ``` - - This `make backport` script automatically generates backport branches and opens pull requests for them. - -### Select commits (internal) - -If the automatic backport methods fail and you're an internal contributor, you -must backport changes manually by selecting specific commits. - -The following example illustrates how to backport a change into Teleport, version -11.x.x. -In this example: - -- Changes were made in the `my-branch` working branch, then committed and pushed to -the remote branch. -- A pull request was created to merge the change from `my-branch` into `master`. -- A merge conflict prevented automatic backporting of the change. - -To commit a change manually: - -1. Open the closed pull request for the `my-branch` change that was successfully -merged. - -1. Click **Commits**, then copy the hash of the commit made to `my-branch`. - -1. Run the following commands to create a branch for the commit being backported: - - ```bash - $ git switch branch/v11 - $ git pull - $ git switch -c my-branch-backport-v11 - $ git cherry-pick - ``` - -1. Open the files that indicate there are merge conflicts and resolve all of the -conflicts. - -1. Add the updated and saved files to the staged list of changes. For example: - - ```bash - $ git add docs/pages/core-concepts.mdx - ``` - - You can use `git status` to check whether there are additional merge conflicts. - -1. Finish the cherry-pick operation by running the following command: - - ```bash - git cherry-pick --continue - ``` - -1. Push the changes for the backport to the fork. - - ```bash - $ git push origin my-branch-backport-v11 - ``` - - If you see a warning that prevents you from pushing the backport, retry using the - following command: - - ```bash - $ git push --set-upstream origin my-branch-backport-v11 - ``` - -1. Create a pull request in the [Teleport repository](https://github.com/gravitational/teleport) to -merge your backport in the branch you are backporting the fix into. - - For example, select `branch/v11` as the base branch to backport your change into Teleport version 11.x. - Include a reference to the original pull release identifier in the title for the backport. - For example, create the pull request for a backport with a title similar to the following with the - backport version number 11.x and the original pull request identifier 29210: - - [v11] Fix lint warning, make these unordered lists #29210 - -### Select commits (external) - -If you're an external contributor, you must backport changes manually. - -The following example illustrates how to backport a change into Teleport version 11.x.x. -In this example: - -- Changes were made in the `my-branch` branch and committed to a fork of the Teleport repository. -- A pull request was created to merge the change from `my-branch` into `origin/master` from the fork. - -1. Copy the hash of the commit made to `my-branch`. - -1. Run the following commands to create a branch for the commit being backported: - - ```bash - $ git switch branch/v11 - $ git pull - $ git switch -c my-branch-backport-v11 - $ git cherry-pick - ``` - -1. Push the changes for the backport to the fork. - - ```bash - $ git push --set-upstream fork my-branch-backport-v11 - ``` - -1. Create a pull request in the [Teleport repository](https://github.com/gravitational/teleport) for your backport. - -## Next steps - -- Consult the [style guide](./style-guide.md) to ensure your docs page is consistent with the rest of the documentation. -- Use the [documentation UI components](./ui-reference.md) reference guide to find the right UI components for your needs. diff --git a/docs-contributors/img/doc-submodules.png b/docs-contributors/img/doc-submodules.png deleted file mode 100644 index 06e09c0173..0000000000 Binary files a/docs-contributors/img/doc-submodules.png and /dev/null differ diff --git a/docs-contributors/img/quicktime.webp b/docs-contributors/img/quicktime.webp deleted file mode 100644 index dd0fabca1e..0000000000 Binary files a/docs-contributors/img/quicktime.webp and /dev/null differ diff --git a/docs-contributors/reviewing-docs.md b/docs-contributors/reviewing-docs.md deleted file mode 100644 index 5d8b68f8d7..0000000000 --- a/docs-contributors/reviewing-docs.md +++ /dev/null @@ -1,78 +0,0 @@ -# How to review Teleport documentation changes - -Teleport uses GitHub pull requests to manage documentation changes. You can set -up your environment to preview docs changes on a local development server, then -leave a review on the pull request. - -## Step 1/2 Set up a docs site clone - -The Teleport documentation site is based on the GitHub repository -`gravitational/docs`, and includes documentation for all supported versions of -Teleport. To achieve this, the `gravitational/docs` repo includes git submodules -for different branches of the Teleport source repository, -`gravitational/teleport`, which also includes the documentation for a particular -version of Teleport: - -![The structure of the gravitational/docs repo](img/doc-submodules.png) - -Clone the `gravitational/docs` repository: - -```bash -$ git clone https://github.com/gravitational/docs -``` - -Navigate to the root of your local clone of the `gravitational/docs` repository -and run the following command to populate the `content` directory: - -```bash -$ yarn git-update -``` - -## Step 2/2 Visit preview pages on the development server - -Navigate to the directory under `content` that corresponds to the latest -released version of Teleport. - -```bash -# Assign this to a number. -$ TELEPORT_VERSION="00" -$ cd content/${TELEPORT_VERSION?}.x -``` - -Docs PRs fall within `gravitational/teleport`. Check out the branch associated -with the PR: - -```bash -$ BRANCH_NAME="" -$ git switch ${BRANCH_NAME?} -``` - -Navigate to the root of your `gravitational/docs` clone and run the following -command to start the development server: - -```bash -$ yarn dev -``` - -The development server listens on port `3000` by default. (It increments the -port if you have other development server instances running.) - -On GitHub, see which docs pages the pull request has changed and navigate to -them within the development server. - -On the docs site, files within `docs/pages` of `gravitational/teleport` -correspond to pages within `localhost:3000/docs`. - -When assigning URL paths to docs pages, the docs site strips the `/pages/` -segment and the `.mdx` extension. For example, `docs/pages/get-started.mdx` -corresponds to `docs/get-started/`. `docs/pages/index.mdx` corresponds to the -root of `localhost:3000/docs`. - -## Next steps - -- While reviewing documentation changes, you will often run into partials, - admonitions, and other elements in the docs engine's library of UI components. - Read about these in the [UI Reference](./reference.md). -- To make sure that docs pages make consistent use of language and structure, - you should get familiar with the Teleport documentation [style - guide](./style-guide.md). diff --git a/docs-contributors/style-guide.md b/docs-contributors/style-guide.md deleted file mode 100644 index f3407d5d4c..0000000000 --- a/docs-contributors/style-guide.md +++ /dev/null @@ -1,301 +0,0 @@ -# Style guide - -This guide describes our approach to building effective documentation, the -conventions we follow, and the recommended practices for organizing, crafting, -and evolving our information architecture with a clear and consistent voice. - -Many style rules have equally justifiable alternatives. Following a common style -guide is intended to prevent debates over style questions from getting in the -way of documenting Teleport. If you don't see an answer to a style question in -this guide, follow your best judgement and keep the style you choose consistent -within the page you're working on. - -## Organizing information into purpose-driven documents - -For software documentation, you can structure information using the -following information model: - -- Tutorials are learning oriented and designed to give a newcomer a positive, successful - experience. Tutorials should be tested regularly to ensure they don't get stale and that - they always provide a successful result. -- How-to guides are task oriented with practical steps to achieve a specific goal. - These guides assume that readers are familiar enough with Teleport that they know the task - they want to complete for a specific scenario but not necessarily how to complete it. -- References are information oriented technical descriptions of a system or its components. -- Explanations are the conceptual framework for understanding how or why a system works. - Explanation provide the context that surrounds what people learn in a tutorial, do in a - how-to guide, or look up in reference material. - -For more detailed information and examples of how to structure documentation using this -information model, see [The Grand Unified Theory of Documentation](https://documentation.divio.com/). - -## Structuring content into pages - -In general, every page of documentation should have a purpose and be self-contained. -It's okay for information to be in multiple places and similar content can exist in -pages that serve different purposes. For example, you might have conceptual information -about trusted clusters in one page and have similar content as context in a how-to topic. -When possible, you should reuse content rather than duplicate content, but it's perfectly -fine to cover the same information in more than one place to serve different purposes. - -## How-to guides - -A how-to guide describes how to achieve a goal or complete a task. -Only the information that is pertinent to achieving that goal or completing the task is included. -With how-to guides, readers have enough information to know what they want to do—for example, -open a bank account—but not necessarily enough information to know how to do it. -For example, the how-to guide for opening a bank account wouldn't explain what a bank account -is or why you might want to open one, but would focus on specific steps such as: - -1. Select an institution. -1. Fill out an application. -1. Deposit a minimum amount of currency. - -How-to guides often include links to additional information, but should not include -explanations that take the focus away from what the reader wants to accomplish. - -### What's in a how-to guide? - -In most cases, how-to guides contain the following sections: - -- Frontmatter with a guide title, description, and other information. - The title should be short and identify the subject of the how-to topic in the fewest words possible. - The description should be a sentence that starts with a verb, summarizes the content of the topic, and ends with a period. - Additional information might include a video banner link, a list of keywords, or an alternate - first-level heading. - -- One or more introductory paragraphs that explain what the task-at-hand is, the use case or - scenario driving the reader to complete the task, and the expected outcome. - -- List of prerequisites. - Actions that are common to multiple topics that must be taken before starting the procedure - in how-to topics are generally documented in partial files and referenced in the - list of prerequisites. - -- Task step sections that break down the how-to procedure into manageable chunks or subtasks - with clearly-defined goals. - Currently, task step sections use headings that convey the current and total number of steps - involved to complete the procedure, for example, **Step 1/3. Add a local user**. - - In most cases, task step sections include code examples, configuration settings, and - screenshots to illustrate the actions the read should perform. Whenever possible, readers - should be able to copy and paste the example code and configurations with minimal changes - to complete the procedure being documenting. - -- Next steps section can be used to add links to logically related topics, if applicable, or - to recommend related topics for further reading, such as reference topics related to the - procedure completed. - -### Using links, admonishments, and details in how-to guides - -You should avoid breaking the reader's focus in how-to guides. -For example, avoid adding links to other pages or to other sections in the same topic. -Avoid inserting notices, tips, admonishments, or collapsed details sections unless -absolutely necessary. - -If you do include a link in a how-to guide to external documentation, -be sure to tell the reader why to follow the link and what information to glean from it. -For example, use explicit information like "Follow the installation instructions in the -AWS documentation" instead of "Read the AWS documentation for more information". - -## Tutorials - -Tutorials are designed to give first-time Teleport users hands-on experience completing -a set of explicit instructions. Tutorials should be as simple and straightforward as -possible. Tutorials must provide a positive learning experience and a successful outcome -with no unexpected behavior or unexplained errors. It's okay for a tutorial to include a -red herring to illustrate a common misstep but the author must provide a sufficient -explanation of the error and how to correct it. - -### What's in a tutorial? - -Tutorial or getting started guides contain much of the same content as how-to guides -but are focused on achieving learning objectives: - -- Frontmatter with a demo video to reach readers who prefer video. -- One or more introductory paragraphs that explain what the tutorial demonstrates. -- Before you begin list of the tools required to complete the tutorial. -- Learning objectives that summarize what the reader will accomplish by completing the tutorial. -- Task steps that the reader must follow in sequence to successfully complete the lesson. -- Next steps section can be used to add links to logically related topics, if applicable, or - to recommend related topics for further reading, such as reference topics related to the - procedure completed. - -## Conceptual guides - -**Conceptual guides** and **Architecture guides** explain core concepts and how Teleport works -at system, component, and operational levels. -Guide for conceptual and architectural information can include the following types of topics: - -- **Networking** for audiences interested in networking concepts, components, and protocols. -- **Security** for audiences interested in security protocols, cryptographic primitives, and - reducing attack vectors. -- **Deployment** for audiences interested in deployment architecture. - -### What's in a conceptual guide? - -Conceptual guides typically contain the following sections: - -- Frontmatter with a guide title, description, and other information. - The title should be short and identify the subject of the how-to topic in the fewest words possible. - The description should be a sentence that starts with a verb, summarizes the content of the topic, and ends with a period. - Additional information might include a list of keywords, or an alternate first-level heading. -- Body paragraphs that explain that explain concepts, components, system operations, and context to - help the reader understand what something is, why it's important, and how it works. -- Diagrams to illustrate component relationships or flow of operations. -- Links to related topics, where applicable. - -## Reference manuals - -**Reference manuals** provide an exhaustive list of configuration options, API methods, -and other possible fields and values for the various ways in which users can interact with -Teleport. - -- Should be comprehensive. If listing configuration options, API paths, and so on, list - all of them, rather than a few examples. -- HTML or Markdown tables are often the best formats for this kind of article. -- Should be easy to navigate with a browser's search functionality. List all content on - the same page. -- Should avoid prose and be expressed with brevity. - -### What's in a reference manual? - -Reference manuals typically contain the following sections: - -- Frontmatter with a guide title, description, and other information. - The title should be short and identify the subject of the how-to topic in the fewest words possible. - The description should be a sentence that starts with a verb, summarizes the content of the topic, and ends with a period. - Additional information might include a list of keywords. -- One or more introductory paragraphs that explain what information the covers. -- Formatted reference information. The format might resemble a `man` page or API description with a - common set of sections (name, description, syntax, options, examples, and so on) or the format - might use lists or tables to present information. -- Links to related topics, where applicable. - -## General style rules - -Please refer to this style guide when determining how address questions about -English grammar, usage, and so on. Since many of these rules have equally -justifiable alternatives, a style guide prevents debates over these questions -from getting in the way of documenting Teleport. - -If a commonly debated style question does not have a resolution in this guide -(e.g., the Oxford comma), all we ask is that you keep your style consistent -within a particular page to maintain a professional polish. - -### Use of frontend components - -In general, we want pages in the documentation to emphasize text and provide an -uncluttered experience to readers. Before adding a component besides a -paragraph, heading, or example code snippet, ask what benefit the component adds -to a page, and if it is possible to achieve a similar result with only -paragraphs, headings, and code snippets. - -For example, when adding a `Tabs` component, ask if it would make sense to add a -subheading instead of each `TabItem`. `TabItems` would be useful if only one -variation of the instructions you are adding is relevant to a reader, and the -other two would only add distraction. If all variations of the instructions are -useful, subheadings would make more sense. - -### Voice - -The documentation should be technically precise and directed toward a technical -audience, e.g., application developers, site reliability engineers, and security -engineering team leads. - -Even when describing Teleport generally, we should emphasize specific technical -capabilities over broad statements of benefit. The aim is not to pique the -audience's interest, but to provide information. - -For example, rather than: - -```markdown -Teleport replaces insecure secrets with true identity. -``` - -Use: - -```markdown -Teleport replaces shared secrets with short-lived X.509 and SSH certificates. -``` - -Some guides are intended for end users seeking to access resources in their -cluster. For certain use cases, it may be necessary to adjust our usual voice -for the audience of a specific guide. - -### Body text - -- Write sparser one to two-sentence groupings rather than lengthier blocks of text. -- Use periods at the end of a line even in a list unless the ending item is a command. - -### Code, commands, and configuration - -- `tsh`, `tctl`, and other core commands should be placed in backticks. - -- All ports or values should be enclosed in backticks, e.g., `443`. - -- Prefer putting commands into full-line code snippets. These will render with a handy copy button. - -### Diagrams - -- Use [Teleport's Lucidchart library](https://app.lucidchart.com/lucidchart/dfcf1f4a-5cf0-4758-8ebb-f6ea86900aba/edit) to create diagrams with a consistent design language. -- Diagram multistep sections using sequence diagrams that depict steps linearly. -- Several great examples are available here: https://gravitational.slab.com/posts/diagrams-ix9nzhpd. - -### Footnotes - -- Footnotes should be ordered by appearance (chronological precedence). `2` should not come before `1`. - -### Headings - -- Headings should be in sentence case. For example, "Next steps" is preferred over "Next Steps." We want to clarify proper nouns and products in headings by using sentence casing. - -### Lists - -- We prefer short paragraph blocks over bulleted or numbered lists. This leads to a preference for completeness and brevity rather than enumeration. - -- When you do include a list, we prefer bullet points over numbered lists. - -- Use numbered lists for any sequence of steps, but use these sparingly. - - Each number should mention the total number of steps, e.g., "Step 1/5," so the reader knows how far along they are in the sequence. - -### Names of products, services, and features - -- Product proper nouns should be capitalized. Say "Trusted Cluster," not "trusted cluster." -- Avoid using quotes to refer to product names, since they often have negative connotations. E.g, do not say, "Trusted Cluster." -- Product proper nouns should be bolded on first use. "Trusted Cluster" should be **Trusted Cluster**. - -### Names of technical concepts - -- Within a single page, use consistent acronyms and concept keywords. For example, pick one of "2-factor," "two-factor", "2fa," or "tfa" within a given page. -- Acronyms should always be introduced following a concept keyword and then consistently used thereafter. - -### Page titles - -- Should have all words capitalized except for determiners (`a`, `the`, etc.). -- Should follow a `Title Name | Teleport Docs` format. The `| Teleport Docs` suffix will be added automatically by our static site generator. -- The total character count should not exceed 70 for the entire title since this can impact SEO. Including the suffix `| Teleport Docs`, that leaves 55 characters for the article's title. - -### SEO - -- Make sure to have a good, well-worded description that uses common keywords around the subject. Also, liberally sprinkle said keywords throughout the article. - -### Videos - -- Mac users should use Quicktime's `Cmd-Shift-5` to record a small part of the screen: - - ![quicktime](img/quicktime.webp) - -- Convert `.mov` videos to `.mp4` and `webm`. - - Quicktime outputs large `.mov` files. Use `ffmpeg` to convert them into `mp4` and `webm` - web-friendly formats: - - ```bash - # create MP4 - $ ffmpeg -i input.mov -b:v 0 -crf 25 output.mp4 - # create WebM - $ ffmpeg -i input.mov -c vp9 -b:v 0 -crf 41 output.webm - ``` - diff --git a/docs-contributors/ui-reference.md b/docs-contributors/ui-reference.md deleted file mode 100644 index 5a942e610b..0000000000 --- a/docs-contributors/ui-reference.md +++ /dev/null @@ -1,485 +0,0 @@ -# UI reference - -Teleport uses Next.js to generate its static documentation site. Next.js uses -Markdown with React, hence the `.mdx` filename suffix. - -This section briefly describes some of the features that are most relevant when -writing documentation. - -## Admonitions - -Admonitions are similar to notices, but are intended for longer content that -looks better against a white background. Use this syntax: - -```jsx - - Admonition content. - -``` - -`type` can be one of the following values: `warning`, `tip`, `note`, `danger`. -Different types will result in different colors for the header. Omitting the type -or using some other value will result in resetting it to the `tip`. - -If `title` is omitted, `type` will be used instead as the title value. - -## Code blocks - -You will often need to illustrate documentation with examples of commands, code, -or configuration files. You can do this by adding a code block. Code blocks -begin and end with three backticks. A label after the first row of backticks -configures the way the block will be rendered: - - ````md - ```yaml - key: value - array: - - val1 - - val2 - - val3 - ``` - ```` - -If a code block's label is `code` or `bash`, the block will be optimized for -example commands. Readers will be able to copy individual lines that begin with -`$`. Comments and output will be highlighted differently than commands. - -Here is an example of a `code` block: - - ````md - ```bash - # Comment - $ tsh login - Output - ``` - ```` - -## Details - -To insert a details block like the one above, use this syntax: - -``` -
- Details content -
-``` - -## Figures - -The `Figure` component can help with using images, figures, and diagrams: - -```jsx -
- ![Example](../../../img/overview.png) -
-``` - -## Icons - -The `Icon` component lets you insert icons into documentation text. This is -useful when referencing a UI element with an icon. For example: - -```md -In the main menu, click on **Desktops** -to view desktops available to your Teleport user. -``` - -## Image pixel density markers - -Browsers can't distinguish between images that are suitable for Apple's Retina display and images that are not. Because of this, screenshots taken on Retina screens may look large on the page. - -To hint to browsers that an image is meant for a Retina display, we can add the -suffix `@Nx` to the image's file name. For example, screenshots made on MacOS -should have the suffix `filename@2x.png`. This will tell the browser to scale -images down twice to show them in their actual size. - -## In-page edits - -Teleport deeply integrates with a user's infrastructure, so configuration -options, URLs, and other values often vary from setup to setup. Docs pages can -define variables that users can edit, allowing them to tailor their -documentation experience to their own environment. - -### The Var component - -To declare a variable, use the `Var` component, as shown in the following `code` -snippets. This example includes an extra space before the tag names of the `Var` -components to prevent these components from rendering: - -````markdown -
-Log in to your Teleport cluster using the following command: - -```bash -$ tsh login --user=< Var name="user"/> --proxy=< Var name="proxy" description="Domain name of your Teleport Web UI" /> -``` - -Get information about your Teleport cluster: - -```bash -$ curl https://< Var name="proxy"/>/webapi/ping -``` - -
-```` - -#### Where to use the Var component - -You can use the `Var` component inside as well as outside code snippets. It is -possible to use this component in code snippets with any language label, such as -`yaml` or `go`. - -`Var` tags must be self closing (ending in `/>`). - -#### How the Var component works - -When a user updates the value of an in-page variable, the values of any `Var` -components with the same `name` property update automatically. When you copy a -`code` snippet using the copy button, the values of any in-page variables within -the `code` snippet are added to the clipboard. - -Variables are scoped to a single page by default. You can make a variable -preserve its value across all of the pages a user visits by adding the -`isGlobal` property to the `` tag. Variable values are not preserved -between browser sessions. - -#### Var component properties - -By default, the `Var` component displays its `name` until the user assigns a -value to it. To configure the component to display an initial value beside its -name, set the `initial` field: - -``` -< Var name="proxy" initial="teleport.example.com" /> -``` - -You should only set an `initial` field for a single occurrence of a `Var` with a -particular name. Otherwise, `Var`s will overwrite one another's initial values. - -## Notices - -If you want to add notice like the one above to the page, use this syntax: - -``` - - Notice content. - -``` - -`type` can be one of the following values: `warning`, `tip`, `note`, `danger`. The default is `tip`. -Different types will result in different background colors and icons. - -## Partials - -To prevent content duplication, it's useful to include code examples or Markdown -content from a partial file into the current page. This allows our documentation -to reduce maintenance overhead so we can focus on writing new articles. - -### Including partials - -To include a partial, use the following syntax, removing the `\` character -before each `!`: - -```markdown -(!path-to-file.mdx!) -``` - -When a page includes a partial, our docs engine resolves the partial's path from -the root of the `gravitational/teleport` repository. - -Partials will be linted when a PR is created as part of our CI/CD process. If a -partial does not exist in the repository, our system will throw an error. -Incorrect placement of include statements will also throw errors. - -Partials will only be included in these two cases: - -#### Surrounded by newlines - - ```md - Some text. - - (! include.mdx !) - - Some other text. - ``` - -If the partial is an `.mdx` file, it will be parsed and rendered as Markdown. In -other cases it will be included as-is. - -#### Inside code blocks - - ````md - ```bash - # Code example below - - (!include.sh!) - - ``` - ```` - -These will be inserted as-is, even in the case of `.mdx` files. - -### Partial parameters - -A partial can define parameters, which allow multiple docs pages to include the -same partial but with slightly different content. - -Inside a partial, a parameter uses the `{{ }}` syntax. For example, the partial -`mypartial.mdx` below uses the `{{ action }}` parameter. - -```markdown -This is an example of a partial. - -A partial makes it possible to {{ action }}. -``` - -To provide a value for a partial, the page that includes it can use the -following syntax: - -```text -(!mypartial.mdx param1="val" param2="val"!) -``` - -For example, a page could supply a value to the `action` parameter in the -`mypartial.mdx` partial above using this expression: - -```text -(!mypartial.mdx action="reuse content in docs pages."!) -``` - -This partial would render as: - -```markdown -This is an example of a partial. - -A partial makes it possible to reuse content in docs pages. -``` - -When including a partial, parameter definitions must be separated by single -spaces. Values must be enclosed in double quotes. Parameter names and values -must be separated by a `=` character, and the `=` character must not be -surrounded by spaces. - -If a partial defines parameters but a page does not assign them when including -the partial, the docs engine will render the literal `{{ }}` expressions for -those parameters within the content of the included partial. The exception to -this is when the partial defines default parameter values, as described in the -next section. - -### Default parameter values - -When defining parameters in a partial, you can instruct the docs engine to -supply a value for those parameters if a page that includes the partial does -not. - -To define default parameter values, add an expression with the following format -to the top line of a partial: - -```markdown -{{ param1="val1" param2="val2" param3="val3" }} -``` - -For example, let's say the `mypartial.mdx` partial we introduced earlier begins -with the following expression: - -```markdown -{{ action="write docs pages more easily." }} -This is an example of a partial. - -A partial makes it possible to {{ action }}. -``` - -If a page includes the partial with this expression... - -```markdown -(!mypartial.mdx!) -``` - -...then the partial will render as follows: - -```markdown -This is an example of a partial. - -A partial makes it possible to write docs pages more easily. -``` - -Default parameter assignments follow the same rules as parameter value -assignments. Default parameter assignments must be separated by single spaces. -Values must be enclosed in double quotes. Parameter names and values must be -separated by a `=` character, and the `=` character must not be surrounded by -spaces. - -### Relative link paths in partials - -When a partial contains a link with a relative path, the docs engine -evaluates the path relative to the partial, not the including file. - -For example, let's say you have a file called `docs/pages/page.mdx` with the -following content: - -```markdown -This is a page. - -(!docs/pages/includes/include.mdx!) -``` - -The partial in `docs/pages/includes/include.mdx` looks like this: - -```markdown -Here is an image: - -![Screenshot](../../img/screenshot.png) -``` - -When including the partial, the docs engine will rewrite the link path to load -the image in `docs/img/screenshot.png`. - -## Tables of Contents - -You can add a list of links to pages in the current directory by adding the -following line to a docs page: - -``` -(!toc!) -``` - -The docs engine replaces this line with a list of links to pages in the current -directory, using the title and description of each page to populate the link: - -``` -- [Page 1](page1.mdx): This is a description of Page 1. -- [Page 2](page2.mdx): This is a description of Page 2. -``` - -## Tabs - -To insert a tabs block like the one above, use this syntax: - -```jsx - - - First tab. - - - Second tab. - - -``` - -### Tabs scopes - -For example, a page will display the "Teleport Cloud" label in this `Tabs` -component if the user selects the appropriate scope: - -```jsx - - - - Here are instructions for users of Teleport Community Edition and Teleport - Enterprise. - - - - - Here are instructions for Teleport Cloud users. - - - -``` - -### Two-dimensional Tabs components - -You can add a second dimension of categories to a `Tabs` component by including -the `dropdownCaption` and `dropdownSelected` options, as shown below: - -```jsx - - - Instructions for building from source using a Helm chart. - - - Instructions for building from source using shell commands. - - - Instructions for installing the latest release using a Helm chart. - - - Instructions for installing the latest release using shell commands. - - -``` - -The `options` attribute indicates which dropdown menu option will render a -`TabItem` visible. - -### Dropdown-only Tabs components - -For `Tabs` components with long lists of tabs, it often makes sense to display -all tabs via a single dropdown menu. You can do this using the `dropdownView` -option of the `Tabs` component: - -```jsx - - - More information about the Database Service. - - - More information about the Application Service. - - - More information about the Desktop Service. - - - More information about the SSH Service. - - - More information about the Kubernetes Service. - - - More information about the Machine ID. - - - More information about the Auth Service. - - - More information about the Proxy Service. - - -``` - -Here is the result: - -When defining a `Tabs` component with the `dropdownView` option enabled, you -must declare dropdown options using the `label` attribute of `TabItem`, not the -`options` attribute. - -## Variables, templating, and interpolation - -Many documentation teams struggle with maintaining the vast number of articles -and resources that are eventually created and consumed. Links and images have to -be rechecked for accuracy and relevance. - -To ease this burden, we can replace links and code examples with *variables* so we don't have to constantly update everything after each release. - -Variables are stored in the `docs/config.json` file under the key `variables`. - -To insert a variable into a page, use the `(\= path.to.variable \=)` syntax (remove backslashes in the actual Markdown). - -Variables will be linted when a PR is created as part of our CI/CD process. If a variable does not exist in the config, you will see an error that you must remedy in order to merge your PR. - -## Videos - -To embed a video in a docs page, use the `video` tag: - -```html - -``` - diff --git a/docs-contributors/yarn-commands.md b/docs-contributors/yarn-commands.md deleted file mode 100644 index 53cd016de4..0000000000 --- a/docs-contributors/yarn-commands.md +++ /dev/null @@ -1,48 +0,0 @@ -# Yarn command reference - -You can run the following `yarn` commands to execute scripts in the -`gravitational/docs` repo. - -Yarn in an alternative package manager for Node.js. It needs to be installed -separately. If you already have Node.js installed, run the following command to -add Yarn: - -```bash -npm install --global yarn -``` - -**Node.js 18+ must be installed on your system for these to work as expected.** -Read the [Node.js -documentation](https://nodejs.org/en/download/package-manager/) to install it. - -## Running the docs site - -|Command|Description| -|---|---| -| `yarn build` | Build a static production site.| -| `yarn dev` | Run a development server for docs at `localhost:3000/docs`. Reload the page to show the latest changes. Depends on `yarn git-update`. | -| `yarn git-update` | Shortcut for `submodule update`, also used as part of `yarn update-and-build`.| -| `yarn start` | Display documentation built with `npm run build` at `localhost:3000`.| -| `yarn update-and-build` | Command to build the site for production. Do not use for local previews since it switches the git branches of content submodules.| - -## Development-related commands - -|Command|Description| -|---|---| -| `yarn` | Install dependencies.| -| `yarn add-symlinks` | Create symlinks from different versions of docs to `pages` directory.| -| `yarn build-node` | Build configs and plugins for MDX.| -| `yarn build-storybook` | Builds static version of Storybook. | -| `yarn lint` | Check JS and TS files for errors and automatically fix them.| -| `yarn lint-check` | Check JS and TS files for errors, but do not fix them. Checked in CI and on commit.| -| `yarn markdown-fix` | Fix syntax automatically in `*.mdx` files inside `content/**/docs/pages/`.| -| `yarn markdown-lint-external-links` | Same as `yarn markdown-lint` but checks that external links work. Separate command because of slowness.| -| `yarn markdown-lint` | Lint `*.mdx` files inside `content/**/docs/pages/` folders for syntax errors.| -| `yarn storybook:test-ci` | Runs Storybook components tests in CI. Unlike `storybook:test-local`, it additionally includes `wait-on` command to ensure proper synchronization between the services and tests during the CI process. | -| `yarn storybook:test-local` | Runs Storybook components locally without opening Storybook instance.| -| `yarn storybook` | Run a [Storybook](https://storybook.js.org/) instance at the `6006` port. You can check existing components here and try different options.| -| `yarn test-storybook` | Run Storybook component tests via [Test Runner](https://storybook.js.org/docs/react/writing-tests/test-runner) when a Storybook instance is started at the `6006` port.| -| `yarn test` | Run tests. Used on CI.| -| `yarn typecheck` | Validate TypeScript type-related errors. Used in CI.| - -