Skip to content

docs: convert alerts to use GitHub Flavored Markdown (GFM) #16850

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Mar 10, 2025
Merged

docs: convert alerts to use GitHub Flavored Markdown (GFM) #16850

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
ba56dad
update md snippet for gfm alerts
EdwardAngert Mar 7, 2025
40159cf
remove extra linebreak
EdwardAngert Mar 7, 2025
50d4d50
caps
EdwardAngert Mar 7, 2025
dc9f67b
gfm alerts all around
EdwardAngert Mar 7, 2025
ced07b4
blockquote indentation
EdwardAngert Mar 7, 2025
1eaeab8
test premium badge in external-auth
EdwardAngert Mar 7, 2025
48cf62b
alert spacing
EdwardAngert Mar 7, 2025
ca70325
un-nest alert from OL
EdwardAngert Mar 7, 2025
0dab25c
more > Note
EdwardAngert Mar 7, 2025
af0fdd8
edit blockquotes
EdwardAngert Mar 7, 2025
6b4d36a
Update template-from-scratch.md document
EdwardAngert Mar 10, 2025
06c8b36
edit or remove non GFM blockquote alerts
EdwardAngert Mar 10, 2025
1735d16
Apply suggestions from code review
EdwardAngert Mar 10, 2025
e527a53
close codeblock
EdwardAngert Mar 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 8 additions & 9 deletions .vscode/markdown.code-snippets
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
{
// For info about snippets, visit https://code.visualstudio.com/docs/editor/userdefinedsnippets
// https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

"admonition": {
"prefix": "#callout",
"alert": {
"prefix": "#alert",
"body": [
"<blockquote class=\"admonition ${1|caution,important,note,tip,warning|}\">\n",
"${TM_SELECTED_TEXT:${2:add info here}}\n",
"</blockquote>\n"
"> [!${1|CAUTION,IMPORTANT,NOTE,TIP,WARNING|}]",
"> ${TM_SELECTED_TEXT:${2:add info here}}\n"
],
"description": "callout admonition caution info note tip warning"
"description": "callout admonition caution important note tip warning"
},
"fenced code block": {
"prefix": "#codeblock",
Expand All @@ -23,9 +23,8 @@
"premium-feature": {
"prefix": "#premium-feature",
"body": [
"<blockquote class=\"info\">\n",
"${1:feature} ${2|is,are|} an Enterprise and Premium feature. [Learn more](https://coder.com/pricing#compare-plans).\n",
"</blockquote>"
"> [!NOTE]\n",
"> ${1:feature} ${2|is,are|} an Enterprise and Premium feature. [Learn more](https://coder.com/pricing#compare-plans).\n"
]
},
"tabs": {
Expand Down
31 changes: 11 additions & 20 deletions docs/admin/external-auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,11 +120,8 @@ The Redirect URI for Gitea should be

### GitHub

<blockquote class="admonition tip">

If you don't require fine-grained access control, it's easier to [configure a GitHub OAuth app](#configure-a-github-oauth-app).

</blockquote>
> [!TIP]
> If you don't require fine-grained access control, it's easier to [configure a GitHub OAuth app](#configure-a-github-oauth-app).

```env
CODER_EXTERNAL_AUTH_0_ID="USER_DEFINED_ID"
Expand Down Expand Up @@ -224,24 +221,18 @@ CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"

## Multiple External Providers

<blockquote class="info">

Multiple providers is an Enterprise and Premium feature.
[Learn more](https://coder.com/pricing#compare-plans).

</blockquote>
> [!NOTE]
> Multiple providers is an Enterprise and Premium feature.
> [Learn more](https://coder.com/pricing#compare-plans).

Below is an example configuration with multiple providers:

<blockquote class="admonition warning">

**Note:** To support regex matching for paths like `github\.com/org`, add the following `git config` line to the [Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):

```shell
git config --global credential.useHttpPath true
```

</blockquote>
> [!IMPORTANT]
> To support regex matching for paths like `github\.com/org`, add the following `git config` line to the [Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
>
> ```shell
> git config --global credential.useHttpPath true
> ```

```env
# Provider 1) github.com
Expand Down
23 changes: 10 additions & 13 deletions docs/admin/infrastructure/scale-utility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,19 +36,16 @@ Since Coder's performance is highly dependent on the templates and workflows you
support, you may wish to use our internal scale testing utility against your own
environments.

<blockquote class="admonition important">

This utility is experimental.

It is not subject to any compatibility guarantees and may cause interruptions
for your users.
To avoid potential outages and orphaned resources, we recommend that you run
scale tests on a secondary "staging" environment or a dedicated
[Kubernetes playground cluster](https://github.com/coder/coder/tree/main/scaletest/terraform).

Run it against a production environment at your own risk.

</blockquote>
> [!IMPORTANT]
> This utility is experimental.
>
> It is not subject to any compatibility guarantees and may cause interruptions
> for your users.
> To avoid potential outages and orphaned resources, we recommend that you run
> scale tests on a secondary "staging" environment or a dedicated
> [Kubernetes playground cluster](https://github.com/coder/coder/tree/main/scaletest/terraform).
>
> Run it against a production environment at your own risk.

### Create workspaces

Expand Down
7 changes: 2 additions & 5 deletions docs/admin/integrations/jfrog-artifactory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,11 +131,8 @@ To set this up, follow these steps:
}
```

<blockquote class="info">

The admin-level access token is used to provision user tokens and is never exposed to developers or stored in workspaces.

</blockquote>
> [!NOTE]
> The admin-level access token is used to provision user tokens and is never exposed to developers or stored in workspaces.

If you don't want to use the official modules, you can read through the [example template](https://github.com/coder/coder/tree/main/examples/jfrog/docker), which uses Docker as the underlying compute. The
same concepts apply to all compute types.
Expand Down
13 changes: 5 additions & 8 deletions docs/admin/integrations/jfrog-xray.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,14 +56,11 @@ workspaces using Coder's [JFrog Xray Integration](https://github.com/coder/coder
--set artifactory.secretName="jfrog-token"
```

<blockquote class="admonition warning">

To authenticate with the Artifactory registry, you may need to
create a [Docker config](https://jfrog.com/help/r/jfrog-artifactory-documentation/docker-advanced-topics) and use it in the
`imagePullSecrets` field of the Kubernetes Pod. See the [Defining ImagePullSecrets for Coder workspaces](../../tutorials/image-pull-secret.md) guide for more
information.

</blockquote>
> [!IMPORTANT]
> To authenticate with the Artifactory registry, you may need to
> create a [Docker config](https://jfrog.com/help/r/jfrog-artifactory-documentation/docker-advanced-topics) and use it in the
> `imagePullSecrets` field of the Kubernetes Pod.
> See the [Defining ImagePullSecrets for Coder workspaces](../../tutorials/image-pull-secret.md) guide for more information.
Copy link
Member

@matifali matifali Mar 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❤️

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it doesn't like this one for some reason 🤷

I'm playing with the indentation locally

current state:

2025-03-07_14-43-18

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a hunch it's because this one is nested in an ordered list.

Was this fixed by ced07b4? If not, does it hurt the flow/semantics if we move the blockquote to be below the numbered list?


## Validate your installation

Expand Down
45 changes: 15 additions & 30 deletions docs/admin/monitoring/health-check.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,15 +117,12 @@ Coder's current activity and usage. It may be necessary to increase the
resources allocated to Coder's database. Alternatively, you can raise the
configured threshold to a higher value (this will not address the root cause).

<blockquote class="admonition tip">

You can enable
[detailed database metrics](../../reference/cli/server.md#--prometheus-collect-db-metrics)
in Coder's Prometheus endpoint. If you have
[tracing enabled](../../reference/cli/server.md#--trace), these traces may also
contain useful information regarding Coder's database activity.

</blockquote>
> [!TIP]
> You can enable
> [detailed database metrics](../../reference/cli/server.md#--prometheus-collect-db-metrics)
> in Coder's Prometheus endpoint. If you have
> [tracing enabled](../../reference/cli/server.md#--trace), these traces may also
> contain useful information regarding Coder's database activity.

## DERP

Expand All @@ -150,12 +147,9 @@ This is not necessarily a fatal error, but a possible indication of a
misconfigured reverse HTTP proxy. Additionally, while workspace users should
still be able to reach their workspaces, connection performance may be degraded.

<blockquote class="admonition note">

**Note:** This may also be shown if you have
[forced websocket connections for DERP](../../reference/cli/server.md#--derp-force-websockets).

</blockquote>
> [!NOTE]
> This may also be shown if you have
> [forced websocket connections for DERP](../../reference/cli/server.md#--derp-force-websockets).

**Solution:** ensure that any proxies you use allow connection upgrade with the
`Upgrade: derp` header.
Expand Down Expand Up @@ -305,13 +299,10 @@ that they are able to successfully connect to Coder. Otherwise, ensure
[`--provisioner-daemons`](../../reference/cli/server.md#--provisioner-daemons)
is set to a value greater than 0.

<blockquote class="admonition note">

**Note:** This may be a transient issue if you are currently in the process of
> [!NOTE]
> This may be a transient issue if you are currently in the process of
updating your deployment.

</blockquote>

### EPD02

#### Provisioner Daemon Version Mismatch
Expand All @@ -324,13 +315,10 @@ of API incompatibility.
**Solution:** Update the provisioner daemon to match the currently running
version of Coder.

<blockquote class="admonition note">

**Note:** This may be a transient issue if you are currently in the process of
> [!NOTE]
> This may be a transient issue if you are currently in the process of
updating your deployment.

</blockquote>

### EPD03

#### Provisioner Daemon API Version Mismatch
Expand All @@ -343,13 +331,10 @@ connect to Coder.
**Solution:** Update the provisioner daemon to match the currently running
version of Coder.

<blockquote class="admonition note">

**Note:** This may be a transient issue if you are currently in the process of
> [!NOTE]
> This may be a transient issue if you are currently in the process of
updating your deployment.

</blockquote>

### EUNKNOWN

#### Unknown Error
Expand Down
9 changes: 3 additions & 6 deletions docs/admin/monitoring/notifications/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,12 +242,9 @@ notification is indicated on the right hand side of this table.

## Delivery Preferences

<blockquote class="info">

Delivery preferences is an Enterprise and Premium feature.
[Learn more](https://coder.com/pricing#compare-plans).

</blockquote>
> [!NOTE]
> Delivery preferences is an Enterprise and Premium feature.
> [Learn more](https://coder.com/pricing#compare-plans).

Administrators can configure which delivery methods are used for each different
[event type](#event-types).
Expand Down
18 changes: 6 additions & 12 deletions docs/admin/networking/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,12 +172,9 @@ more.

## Browser-only connections

<blockquote class="info">

Browser-only connections is an Enterprise and Premium feature.
[Learn more](https://coder.com/pricing#compare-plans).

</blockquote>
> [!NOTE]
> Browser-only connections is an Enterprise and Premium feature.
> [Learn more](https://coder.com/pricing#compare-plans).

Some Coder deployments require that all access is through the browser to comply
with security policies. In these cases, pass the `--browser-only` flag to
Expand All @@ -189,12 +186,9 @@ via the web terminal and

### Workspace Proxies

<blockquote class="info">

Workspace proxies are an Enterprise and Premium feature.
[Learn more](https://coder.com/pricing#compare-plans).

</blockquote>
> [!NOTE]
> Workspace proxies are an Enterprise and Premium feature.
> [Learn more](https://coder.com/pricing#compare-plans).
Comment on lines +191 to +193
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> [!NOTE]
> Workspace proxies are an Enterprise and Premium feature.
> [Learn more](https://coder.com/pricing#compare-plans).

Instead use label on the heading.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

leaving out of this PR per #16850, slack discussion, and other comments - the way the site renders the anchor URL with $heading-enterpriselocal becomes another issue for search and heading redirects. If we can find a way for the site to scrub those from the URL when it generates pages, that's worth pursuing.

Alternatively, we can consider making the whole section something like "Everything from here down requires a license..."


Workspace proxies are a Coder Enterprise feature that allows you to provide
low-latency browser experiences for geo-distributed teams.
Expand Down
9 changes: 3 additions & 6 deletions docs/admin/networking/port-forwarding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,12 +131,9 @@ to the app.

### Configure maximum port sharing level

<blockquote class="info">

Configuring port sharing level is an Enterprise and Premium feature.
[Learn more](https://coder.com/pricing#compare-plans).

</blockquote>
> [!NOTE]
> Configuring port sharing level is an Enterprise and Premium feature.
> [Learn more](https://coder.com/pricing#compare-plans).

Premium-licensed template admins can control the maximum port sharing level for
workspaces under a given template in the template settings. By default, the
Expand Down
9 changes: 3 additions & 6 deletions docs/admin/setup/appearance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,8 @@
# Appearance

<blockquote class="info">

Customizing Coder's appearance is an Enterprise and Premium feature.
[Learn more](https://coder.com/pricing#compare-plans).

</blockquote>
> [!NOTE]
> Customizing Coder's appearance is an Enterprise and Premium feature.
> [Learn more](https://coder.com/pricing#compare-plans).

Customize the look of your Coder deployment to meet your enterprise
requirements.
Expand Down
5 changes: 2 additions & 3 deletions docs/admin/setup/telemetry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
# Telemetry

<blockquote class="info">
TL;DR: disable telemetry by setting <code>CODER_TELEMETRY_ENABLE=false</code>.
</blockquote>
> [!NOTE]
> TL;DR: disable telemetry by setting <code>CODER_TELEMETRY_ENABLE=false</code>.

Coder collects telemetry from all installations by default. We believe our users
should have the right to know what we collect, why we collect it, and how we use
Expand Down
7 changes: 2 additions & 5 deletions docs/admin/templates/extending-templates/external-auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,8 @@ you can require users authenticate via git prior to creating a workspace:

### Native git authentication will auto-refresh tokens

<blockquote class="info">
<p>
This is the preferred authentication method.
</p>
</blockquote>
> [!TIP]
> This is the preferred authentication method.

By default, the coder agent will configure native `git` authentication via the
`GIT_ASKPASS` environment variable. Meaning, with no additional configuration,
Expand Down
8 changes: 2 additions & 6 deletions docs/admin/templates/extending-templates/provider-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,7 @@
# Provider Authentication

<blockquote class="danger">
<p>
Do not store secrets in templates. Assume every user has cleartext access
to every template.
</p>
</blockquote>
> [!CAUTION]
> Do not store secrets in templates. Assume every user has cleartext access to every template.

The Coder server's
[provisioner](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/provisioner)
Expand Down
5 changes: 2 additions & 3 deletions docs/admin/templates/extending-templates/resource-metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,8 @@ You can use `coder_metadata` to show Terraform resource attributes like these:

![ui](../../../images/admin/templates/coder-metadata-ui.png)

<blockquote class="info">
Coder automatically generates the <code>type</code> metadata.
</blockquote>
> [!NOTE]
> Coder automatically generates the <code>type</code> metadata.

You can also present automatically updating, dynamic values with
[agent metadata](./agent-metadata.md).
Expand Down
9 changes: 3 additions & 6 deletions docs/admin/templates/managing-templates/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,12 +60,9 @@ infrastructure, software, or security patches. Learn more about

### Template update policies

<blockquote class="info">

Template update policies are an Enterprise and Premium feature.
[Learn more](https://coder.com/pricing#compare-plans).

</blockquote>
> [!NOTE]
> Template update policies are an Enterprise and Premium feature.
> [Learn more](https://coder.com/pricing#compare-plans).

Licensed template admins may want workspaces to always remain on the latest
version of their parent template. To do so, enable **Template Update Policies**
Expand Down
Loading
Loading