diff --git a/docs/pages/contributing/documentation/reference.mdx b/docs/pages/contributing/documentation/reference.mdx
index e8e38788219fa..f0659ccc53819 100644
--- a/docs/pages/contributing/documentation/reference.mdx
+++ b/docs/pages/contributing/documentation/reference.mdx
@@ -6,6 +6,34 @@ Teleport uses Next.js to generate its static documentation site. Next.js uses Ma
This section briefly describes some of the features that are most relevant when writing documentation.
+## Admonitions
+
+
+ Admonition content.
+
+
+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.
+
+`scope` is an optional property that specifies the component's
+[scope](./reference.mdx#scopes). If the `scopeOnly` property is provided and the
+user-selected scope is not included in `scope`, the `Admonition` will be hidden.
+
+
## Code blocks
You will often need to illustrate documentation with examples of commands, code,
@@ -45,19 +73,222 @@ Here is the same block after rendering:
Output
```
-## Variables, templating, and interpolation
+## Details
-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.
+
+ Details content
+
-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.
+To insert a details block like the one above, use this syntax:
-Variables are stored in the `docs/config.json` file under the key `variables`.
+```
+
+ Details content
+
+```
-To insert a variable into a page, use the `(\= path.to.variable \=)` syntax (remove backslashes in the actual Markdown).
+`scope` is an optional property that specifies the component's [scope](./reference.mdx#scopes).
-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.
+If `scopeOnly` is assigned to `{true}`, the component will only be visible
+in the provided scope and invisible in all other scopes.
+
+## Figures
+
+{/* TODO: Document all props*/}
+
+The `Figure` component can help with using images, figures, and diagrams:
+
+
+ 
+
+
+```jsx
+
+ 
+
+```
+
+## 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.
+```
+
+Which renders as:
+
+In the main menu, click on **Desktops**
+to view desktops available to your Teleport user.
+
+
+
+(!docs/pages/includes/icons-table.mdx!)
+
+
+
+## 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 two `code`
+snippets below:
+
+````markdown
+
+Log in to your Teleport cluster using the following command:
+
+```code
+$ tsh login --user= --proxy=
+```
+
+Get information about your Teleport cluster:
+
+```code
+$ curl https:///webapi/ping
+```
+
+
+````
+
+Here is the result:
+
+
+Log in to your Teleport cluster using the following command:
+
+```code
+$ tsh login --user= --proxy=
+```
+
+Get information about your Teleport cluster:
+
+```code
+$ curl https:///webapi/ping
+```
+
+
+
+
+
+The `Var` component only works in [code blocks](#code-blocks) using the `code`
+syntax (e.g. ```code), and only for "command" lines (beginning
+with `$`). The component will work without caveats outside of code blocks.
+
+
+
+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.
+
+The `description` field is used in the `VarList` component, which we explain in
+the next section. You only need to specify the `description` once.
+
+
+
+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` tags must be self closing (ending in `/>`).
+
+### The VarList component
+
+To provide a key for all of the global and page-local variables the docs have
+defined, use the `VarList` component:
+
+```markdown
+
+
+
+```
+
+This results in the following:
+
+
+
+
+
+The description we added to the `proxy` variable appears here. Since the `user`
+variable does not have a description, the `VarList` shows its name instead.
+
+## MermaidJS diagrams
+
+You can declare a MermaidJS diagram by adding a code snippet to a docs page with
+the `mermaid` label. See the [MermaidJS
+documentation](https://mermaid.js.org/intro/) for an introduction to the diagram
+syntax.
+
+For example, you can declare a flowchart using this diagram definition:
+
+````markdown
+```mermaid
+flowchart LR
+ start --> e["end"]
+```
+````
+
+This will render as a diagram:
+
+```mermaid
+flowchart LR
+ start --> e["end"]
+```
+
+The advantage of MermaidJS diagrams over static images is that MermaidJS
+diagrams are easy to edit once they are added to the codebase, since there is no
+need to find an original image file. Docs authors can edit the information
+within a MermaidJS diagram without needing to worry about adjusting lines in a
+graphical editor. It's also possible to apply standard stylesheets to MermaidJS
+diagrams and perform static text analysis (e.g., spell checking and linting).
+
+The disadvantage of MermaidJS diagrams is that the Teleport documentation
+engine's implementation does not currently support images, so diagrams that
+require more than lines, coloring, and text must use another solution.
+
+## Notices
+
+Notice content.
+
+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.
+
+`scope` is an optional property that specifies the component's [scope](./reference.mdx#scopes).
## Partials
@@ -233,69 +464,55 @@ Here is an image:
When including the partial, the docs engine will rewrite the link path to load
the image in `docs/img/screenshot.png`.
-## 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.
-
-## Scopes
+## ScopedBlock
-There are three versions of Teleport: `oss`, `enterprise`, and `cloud`. Readers can switch the scope of the documentation using a dropdown menu at the top of the page.
+Use the `ScopedBlock` component if you want to render some Markdown only for
+users of open source Teleport, Teleport Cloud, or Teleport Enterprise.
-Based on the selector's value, some `.mdx` components can hide or show different content sections. Check the components' descriptions below to see which component can be affected by this selector. These components will include the `scope` property.
+`ScopedBlock` has a single property, `scope`, that works the same as it does for
+other components we use in the documentation. See our
+[explanation](./reference.mdx#scopes) of how to use the `scope` property.
-If `scope` is set, the component will be only shown if the scope is selected via
-the dropdown menu. `scope` can be either a single string or an array of strings.
-Possible values are `oss`, `enterprise`, and `cloud`. For an array of strings,
-use this syntax: `scope={["oss", "cloud"]}`.
+Use this instead of the `Tabs` component when:
-## Notices
+- You want to conceal details that aren't relevant to the reader's scope.
+- The components you use don't look presentable within a `TabItem`, e.g., you're
+ including a separate `Tabs` component for each scope.
-Notice content.
+
-If you want to add notice like the one above to the page, use this syntax:
+Readers may not notice that it is possible to adjust the scope of a docs page,
+so only use this component if there is no risk of a reader losing important
+information by not seeing a `ScopedBlock`. Otherwise, consider a `Details` block
+with `scope` set and `scopeOnly={false}`.
-```
-
- 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.
-
-`scope` is an optional property that specifies the component's [scope](./reference.mdx#scopes).
+Any Markdown and MDX components can be included within a `ScopedBlock`.
-## Admonitions
+```jsx
+
-
- Admonition content.
-
+ Here are some options for installing the Teleport Auth and Proxy Services on
+ your own infrastructure.
-Admonitions are similar to notices, but are intended for longer content that looks better against a white background. Use this syntax:
+
+ {/* TabItems that vary between scopes */}
+
-```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`.
+## Scopes
-If `title` is omitted, `type` will be used instead as the title value.
+There are three versions of Teleport: `oss`, `enterprise`, and `cloud`. Readers can switch the scope of the documentation using a dropdown menu at the top of the page.
-`scope` is an optional property that specifies the component's
-[scope](./reference.mdx#scopes). If the `scopeOnly` property is provided and the
-user-selected scope is not included in `scope`, the `Admonition` will be hidden.
+Based on the selector's value, some `.mdx` components can hide or show different content sections. Check the components' descriptions below to see which component can be affected by this selector. These components will include the `scope` property.
+
+If `scope` is set, the component will be only shown if the scope is selected via
+the dropdown menu. `scope` can be either a single string or an array of strings.
+Possible values are `oss`, `enterprise`, and `cloud`. For an array of strings,
+use this syntax: `scope={["oss", "cloud"]}`.
## Tabs
@@ -473,192 +690,19 @@ 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.
-## Details
-
-
- Details content
-
-
-To insert a details block like the one above, use this syntax:
-
-```
-
- Details content
-
-```
-
-`scope` is an optional property that specifies the component's [scope](./reference.mdx#scopes).
-
-If `scopeOnly` is assigned to `{true}`, the component will only be visible
-in the provided scope and invisible in all other scopes.
-
-## 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 two `code`
-snippets below:
-
-````markdown
-
-Log in to your Teleport cluster using the following command:
-
-```code
-$ tsh login --user= --proxy=
-```
-
-Get information about your Teleport cluster:
-
-```code
-$ curl https:///webapi/ping
-```
-
-
-````
-
-Here is the result:
-
-
-Log in to your Teleport cluster using the following command:
-
-```code
-$ tsh login --user= --proxy=
-```
-
-Get information about your Teleport cluster:
-
-```code
-$ curl https:///webapi/ping
-```
-
-
-
-
-
-The `Var` component only works in [code blocks](#code-blocks) using the `code`
-syntax (e.g. ```code), and only for "command" lines (beginning
-with `$`). The component will work without caveats outside of code blocks.
-
-
-
-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.
-
-The `description` field is used in the `VarList` component, which we explain in
-the next section. You only need to specify the `description` once.
-
-
-
-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` tags must be self closing (ending in `/>`).
-
-### The VarList component
-
-To provide a key for all of the global and page-local variables the docs have
-defined, use the `VarList` component:
-
-```markdown
-
-
-
-```
-
-This results in the following:
-
-
-
-
-
-The description we added to the `proxy` variable appears here. Since the `user`
-variable does not have a description, the `VarList` shows its name instead.
-
-## Figures
-
-{/* TODO: Document all props*/}
-
-The `Figure` component can help with using images, figures, and diagrams:
-
-
- 
-
-
-```jsx
-
- 
-
-```
-
-## 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.
-```
-
-Which renders as:
-
-In the main menu, click on **Desktops**
-to view desktops available to your Teleport user.
-
-
-
-(!docs/pages/includes/icons-table.mdx!)
-
-
-
-## ScopedBlock
-
-Use the `ScopedBlock` component if you want to render some Markdown only for
-users of open source Teleport, Teleport Cloud, or Teleport Enterprise.
-
-`ScopedBlock` has a single property, `scope`, that works the same as it does for
-other components we use in the documentation. See our
-[explanation](./reference.mdx#scopes) of how to use the `scope` property.
-
-Use this instead of the `Tabs` component when:
-
-- You want to conceal details that aren't relevant to the reader's scope.
-- The components you use don't look presentable within a `TabItem`, e.g., you're
- including a separate `Tabs` component for each scope.
+## Variables, templating, and interpolation
-Any Markdown and MDX components can be included within a `ScopedBlock`.
+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.
-```jsx
-
+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.
- Here are some options for installing the Teleport Auth and Proxy Services on
- your own infrastructure.
+Variables are stored in the `docs/config.json` file under the key `variables`.
-
- {/* TabItems that vary between scopes */}
-
+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