Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 2 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -844,9 +844,9 @@ lint/emdash:
# Fails when docs Markdown contains invalid inline HTML the docs site drops or
# mangles: swallowed angle-bracket placeholders (e.g. <region>), void-element
# end tags (</br>), capitalized or unregistered component tags (e.g. <Image>),
# and unclosed container tags.
# and unclosed container tags. Also fails on table header cells with no text.
lint/docs-html:
echo "--- check for invalid inline HTML in docs"
echo "--- check for invalid inline HTML and empty table headers in docs"
go run ./scripts/docshtmlcheck
.PHONY: lint/docs-html

Expand Down
13 changes: 7 additions & 6 deletions docs/.style/style-guide/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@ The doctrine for adding Vale rules lives in the [Vale doctrine README](../README

A clean `make lint/prose` run is not evidence that a page follows this guide.
The guide documents 88 rules.
Automated tooling checks 10 of them, and 1 of those 10 doesn't run on published pages.
The other 78 are yours to apply by reading, 79 on published pages, where the one-sentence-per-line rule is off.
Automated tooling checks 11 of them, and 1 of those 11 doesn't run on published pages.
The other 77 are yours to apply by reading, 78 on published pages, where the one-sentence-per-line rule is off.

Open the section that matches what you're writing and work through it.
The linters catch a narrow band of mechanical errors; they can't tell you that a page serves 2 audiences, buries a required step in a `NOTE`, or wraps every paragraph at 80 columns.
Expand All @@ -40,6 +40,7 @@ The linters catch a narrow band of mechanical errors; they can't tell you that a
| `Coder.UnitSpacing` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` and `docs/admin/integrations/prometheus.md` and `docs/admin/setup/configuration-reference.md` and `docs/reference/{api,cli}/*.md` | A regular space, or no space, between a number and its unit |
| `MD001`, `MD025`, `MD040`, `MD045` | markdownlint | `error` | All Markdown | Heading increments, single H1, fence language, missing alt text |
| `scripts/check_emdash.sh` | `make lint/emdash` | `error` | Repository | Em-dash, en-dash, and ` -- ` as punctuation |
| `empty-table-header` | `make lint/docs-html` | `error` | `docs/**`, including generated pages | Table header cells with no text, in Markdown and HTML tables |
| `scripts/docsmanifestgen` | `make lint/docs-manifest` | `error` | Descriptions in `docs/manifest/**` and in the front matter of every page they list | A page description that doesn't end with a period |

The markdownlint row lists only the rules that map to a rule in this guide.
Expand All @@ -48,7 +49,7 @@ markdownlint runs its full default set minus the rules `.markdownlint.jsonc` dis
Vale runs advisory.
`make lint/prose` passes `--no-exit`, and the CI step is advisory by design, so no Vale finding fails a build at any severity.
Findings accumulate instead of blocking: rules that shipped against a clean corpus have since collected a backlog of warnings in `docs/`.
The markdownlint, emdash, and docs-manifest checks do fail the build.
The markdownlint, emdash, docs HTML, and docs-manifest checks do fail the build.

### Coverage by section

Expand All @@ -60,9 +61,9 @@ The markdownlint, emdash, and docs-manifest checks do fail the build.
| [Word choice](./word-choice.md) | 20 | 2 | 12 | 6 |
| [Accessibility and inclusion](./accessibility-and-inclusion.md) | 14 | 3 | 5 | 6 |
| [Capitalization and punctuation](./capitalization-and-punctuation.md) | 12 | 2 | 8 | 2 |
| [Formatting](./formatting.md) | 13 | 2 | 0 | 11 |
| [Formatting](./formatting.md) | 13 | 3 | 0 | 10 |
| [Numbers, units, and dates](./numbers-units-and-dates.md) | 5 | 1 | 4 | 0 |
| **Total** | 88 | 10 | 34 | 44 |
| **Total** | 88 | 11 | 34 | 43 |

Every column counts rule sections, not linter rule names.
A rule section is a heading that carries an enforcement footer, the italic line that names the section's enforcement status.
Expand All @@ -89,7 +90,7 @@ Classify a counted section from its footer, in this order:
A section that names several checks still counts once.
3. Anything else: the section is planned.

So the 8 rows in the table above name 11 checks, because the markdownlint row bundles 4, and those 11 checks cover 10 sections: each check counts under the section that owns it rather than under every section that mentions it.
So the 9 rows in the table above name 12 checks, because the markdownlint row bundles 4, and those 12 checks cover 11 sections: each check counts under the section that owns it rather than under every section that mentions it.

A rule marked `(planned)` in a section footer names the rule that would enforce it if it existed.
It isn't running today.
Expand Down
8 changes: 6 additions & 2 deletions docs/.style/style-guide/formatting.md
Original file line number Diff line number Diff line change
Expand Up @@ -429,8 +429,12 @@ A table that forces columns so narrow that words split across lines reads worse
If a table needs many columns to capture the data, reconsider whether a table is the right structure.
A definition list or a sequence of subsections may serve the reader better.

*Documentation-only.
No Vale rule.*
Give every header cell text that names its column or row, including the top-left corner cell of a matrix.
A screen reader announces an empty header cell as a column or row with no name, and a cell holding only `&nbsp;` or `<br>` is still empty.
For a matrix corner, name what the row headers hold, such as `Permission`.

*Enforced by `scripts/docshtmlcheck` (`empty-table-header`) for header cells with no text.
The rest of the section is documentation-only.*

### Links

Expand Down
51 changes: 28 additions & 23 deletions docs/admin/networking/port-forwarding.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,57 +205,62 @@ In other words, CORS behavior through the dashboard is not currently configurabl
#### Allowed by default

<table class="tg">
<caption>
Which requests between forwarded apps the dashboard allows by default.
Columns are the origin: the user, workspace, and app that sends the request.
Rows are the destination: the user, workspace, and app that receives it.
</caption>
<thead>
<tr>
<th class="tg-0pky" rowspan="2"></th>
<th class="tg-0pky" rowspan="3"></th>
<th class="tg-0pky">From</th>
<th class="tg-0pky" colspan="3">Alice</th>
<th class="tg-0pky">Bob</th>
<th class="tg-0pky" scope="row" colspan="3">From user</th>
<th class="tg-0pky" scope="col" colspan="3">Alice</th>
<th class="tg-0pky" scope="col">Bob</th>
</tr>
<tr>
<th class="tg-0pky" rowspan="2"></th>
<th class="tg-0pky">Workspace 1</th>
<th class="tg-0pky" colspan="2">Workspace 2</th>
<th class="tg-0pky">Workspace 3</th>
<th class="tg-0pky" scope="row" colspan="3">From workspace</th>
<th class="tg-0pky" scope="col">Workspace 1</th>
<th class="tg-0pky" scope="col" colspan="2">Workspace 2</th>
<th class="tg-0pky" scope="col">Workspace 3</th>
</tr>
<tr>
<th class="tg-0pky">To</th>
<th class="tg-0pky">App A</th>
<th class="tg-0pky">App B</th>
<th class="tg-0pky">App C</th>
<th class="tg-0pky">App D</th>
<th class="tg-0pky" scope="col">To user</th>
<th class="tg-0pky" scope="col">To workspace</th>
<th class="tg-0pky" scope="col">To app</th>
<th class="tg-0pky" scope="col">App A</th>
<th class="tg-0pky" scope="col">App B</th>
<th class="tg-0pky" scope="col">App C</th>
<th class="tg-0pky" scope="col">App D</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tg-0pky" rowspan="3">Alice</td>
<td class="tg-0pky" rowspan="2">Workspace 1</td>
<td class="tg-0pky">App A</td>
<th class="tg-0pky" scope="row" rowspan="3">Alice</th>
<th class="tg-0pky" scope="row" rowspan="2">Workspace 1</th>
<th class="tg-0pky" scope="row">App A</th>
<td class="tg-0pky">✅</td>
<td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
<td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
<td class="tg-0pky">❌</td>
</tr>
<tr>
<td class="tg-0pky">App B</td>
<th class="tg-0pky" scope="row">App B</th>
<td class="tg-0pky">✅*</td>
<td class="tg-0pky">✅</td>
<td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
<td class="tg-0pky">❌</td>
</tr>
<tr>
<td class="tg-0pky">Workspace 2</td>
<td class="tg-0pky">App C</td>
<th class="tg-0pky" scope="row">Workspace 2</th>
<th class="tg-0pky" scope="row">App C</th>
<td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
<td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
<td class="tg-0pky">✅</td>
<td class="tg-0pky">❌</td>
</tr>
<tr>
<td class="tg-0pky">Bob</td>
<td class="tg-0pky">Workspace 3</td>
<td class="tg-0pky">App D</td>
<th class="tg-0pky" scope="row">Bob</th>
<th class="tg-0pky" scope="row">Workspace 3</th>
<th class="tg-0pky" scope="row">App D</th>
<td class="tg-0pky">❌</td>
<td class="tg-0pky">❌</td>
<td class="tg-0pky">❌</td>
Expand Down
2 changes: 1 addition & 1 deletion docs/admin/templates/extending-templates/workspace-tags.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ In most cases, `coder_parameter`s backing `coder_workspace_tags` should be marke

You may only specify the following as inputs for `coder_workspace_tags`:

| | Example |
| Input | Example |
|:-------------------|:----------------------------------------------|
| Static values | `"developers"` |
| Template variables | `var.az` |
Expand Down
2 changes: 1 addition & 1 deletion docs/admin/users/groups-roles.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ The roles in the following table apply across the whole deployment.
Organizations have their own roles.
Refer to [Organization roles](#organization-roles) for more information.

| | Auditor | User Admin | Template Admin | Owner |
| Permission | Auditor | User Admin | Template Admin | Owner |
|--------------------------------------------------------------------------|---------|------------|----------------|-------|
| Add and remove Users | | ✅ | | ✅ |
| Manage groups (premium) | | ✅ | | ✅ |
Expand Down
2 changes: 1 addition & 1 deletion docs/install/prepare/airgap.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ All Coder features are supported in air-gapped / behind firewalls / disconnected
This is a general comparison.
Keep reading for a full tutorial running Coder air-gapped with Kubernetes or Docker.

| | Public deployments | Air-gapped deployments |
| Component | Public deployments | Air-gapped deployments |
|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Terraform binary | By default, Coder downloads Terraform binary from [releases.hashicorp.com](https://releases.hashicorp.com) | Terraform binary must be included in `PATH` for the VM or container image. [Supported versions](../../../provisioner/terraform/install.go#L27-L28) |
| Terraform registry | Coder templates will attempt to download providers from [registry.terraform.io](https://registry.terraform.io) or [custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) specified in each template | [Custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) can be specified in each Coder template, or a custom registry/mirror can be used. More details below |
Expand Down
2 changes: 1 addition & 1 deletion docs/install/validate/scale-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Our scale tests include the following stages:

The scale tests runner can distribute the workload to overlap single scenarios based on the workflow configuration:

| | T0 | T1 | T2 | T3 | T4 | T5 | T6 |
| Scenario | T0 | T1 | T2 | T3 | T4 | T5 | T6 |
|----------------------|----|----|----|----|----|----|----|
| SSH connections | X | X | X | X | | | |
| Web Terminal (PTY) | | X | X | X | X | | |
Expand Down
Loading
Loading