## Summary axe reports `empty-table-header` on 116 generated CLI reference pages and several hand-written pages: a header cell with no text is announced by screen readers as an unnamed column. This PR gives every table header cell in `docs/` text, and adds a lint check so empty header cells can't come back. ## How to review this PR - `docs/reference/cli/`: 116 files, these all generate identically, so I would only spot check 2-3 of them and skip the rest - `docs/*` outside of `docs/reference/cli/`: 6 files, normal review of these - `scripts`: 5 files, code review of the Bash and Go files to make sure we're properly inserting headers into each table ## What changed **Generator.** `scripts/clidocgen` wrote an empty header row (`| | |`) over each option's metadata table (Type, Environment, YAML, Default). It now writes `| Property | Value |`. Subcommand tables already had `Name | Purpose` and are unchanged. Regenerated with `make docs/reference/cli/index.md`: 116 files under `docs/reference/cli/` change. The header rows change, and the body rows of each option table are re-padded to the wider first column; the content is otherwise identical. Every option on those 116 pages now shows a visible `Property | Value` header row above Type, Environment, YAML, and Default, so this is a visual change on the docs site as well as a screen reader one. The CLI's own `--help` output doesn't use this template, so it's unchanged. **Audit logs.** `docs/admin/security/audit-logs.md` already has `Field | Tracked` headers on `main` (the generator writes them), so there was nothing to change there; the live-site finding predates that. **Hand-written tables.** - `docs/admin/networking/port-forwarding.md`: the CORS matrix had three empty spanning corner cells. The corner now reads `From user` and `From workspace` (spanning the three row-header columns, beside the Alice/Bob and Workspace rows) and `To user`, `To workspace`, `To app` (over the three row-header columns). The grid is still 3 header rows by 7 columns. The From cells have `scope="row"` and the other header-row cells `scope="col"`, so the From labels don't become column headers for the body's label columns; the body's user, workspace, and app labels are `<th scope="row">`; and a `<caption>` says columns are the origin and rows the destination. - `groups-roles.md`, `airgap.md`, `scale-testing.md`, `workspace-tags.md`: these four corner cells are already filled by #30873. The new check would fail CI without them, so this PR carries the same four lines, byte-identical to #30873 (`Permission`, `Component`, `Scenario`, `Input`), so whichever PR merges second rebases without conflict. If #30873 merges first, these hunks drop out. **New check.** `scripts/docshtmlcheck` (`make lint/docs-html`, part of `make lint`) now also reports `empty-table-header`. I put it there because that checker already parses every Markdown file under `docs/`, generated pages included, with goldmark and tokenizes raw HTML with `golang.org/x/net/html`, and it already runs in CI. A markdownlint custom rule would have needed a new JS rule and HTML parsing there. - Markdown pipe tables: the header row, via goldmark's GFM table extension. - Raw HTML tables: every `<th>`, tracked across HTML blocks, with entities decoded and whitespace trimmed, so `<th></th>`, `<th> </th>`, and `<th><br></th>` are all reported. Markdown between the HTML blocks of an open `<th>` counts as its text. Tables in code blocks are ignored. - Output: `docs/x.md:29: empty-table-header: header cell 1 has no text (table's first header "Auditor")`, plus a summary footer. - The tokenizer loop moved out of `scanNode` into a shared `tokenizeSegments` helper so both checks use it; `scanNode`'s behavior is unchanged. - The style guide's checks table gets one row; the README for the checker describes the rule. ## Testing - Tests first: `TestCheckTables` (now 22 cases) and `TestRunEmptyTableHeader` failed against a stub, then pass. The existing `docshtmlcheck` tests pass unchanged. - `go run ./scripts/docshtmlcheck` on `main` reports 1,561 empty header cells (116 CLI pages, port-forwarding, and the four #30873 tables); on this branch it reports none. - `go test ./scripts/docshtmlcheck/ ./scripts/clidocgen/ ./scripts/docgenenv/`, golangci-lint on the changed packages, `make lint/docs-html lint/docs-manifest lint/docs-gen-filter lint/emdash`, `pnpm run check-docs`, and Vale on the changed hand-written pages all pass. - `make gen` couldn't run to completion locally (no `protoc-gen-go`); CI's gen check covers it. The CLI pages were regenerated with the repo's own target. Review feedback applied incfd29a2160(entities decoded in Markdown text, image alt text and autolinks count as text),709a58f603(per-kind counts, finding order, CLI generator note),8e61ff3afa(CORS matrix scopes and caption), andb807bcbbc7and2871f89bdf(style guide rule section, `make lint/docs-html` in the checks table, coverage counts). Linear: DOCS-1308 --- 🤖 Built with AI assistance.
174 lines
6.1 KiB
Markdown
Generated
174 lines
6.1 KiB
Markdown
Generated
---
|
|
# Code generated by make gen. DO NOT EDIT.
|
|
title: "`coder ssh`"
|
|
description: Start a shell into a workspace or run a command.
|
|
---
|
|
|
|
<!-- DO NOT EDIT | GENERATED CONTENT -->
|
|
|
|
Start a shell into a workspace or run a command
|
|
|
|
## Usage
|
|
|
|
```console
|
|
coder ssh [flags] <workspace> [command]
|
|
```
|
|
|
|
## Description
|
|
|
|
```console
|
|
This command does not have full parity with the standard SSH command. For users who need the full functionality of SSH, create an ssh configuration with `coder config-ssh`.
|
|
|
|
- Use `--` to separate and pass flags directly to the command executed via SSH.:
|
|
|
|
$ coder ssh <workspace> -- ls -la
|
|
```
|
|
|
|
## Options
|
|
|
|
### --stdio
|
|
|
|
| Property | Value |
|
|
|-------------|-------------------------------|
|
|
| Type | <code>bool</code> |
|
|
| Environment | <code>$CODER_SSH_STDIO</code> |
|
|
|
|
Specifies whether to emit SSH output over stdin/stdout.
|
|
|
|
### -t, --tty
|
|
|
|
| Property | Value |
|
|
|-------------|-----------------------------|
|
|
| Type | <code>bool</code> |
|
|
| Environment | <code>$CODER_SSH_TTY</code> |
|
|
|
|
Request a pseudo-terminal for the SSH session. Interactive shell sessions request one by default; command sessions do not unless this flag is set.
|
|
|
|
### --ssh-host-prefix
|
|
|
|
| Property | Value |
|
|
|-------------|-----------------------------------------|
|
|
| Type | <code>string</code> |
|
|
| Environment | <code>$CODER_SSH_SSH_HOST_PREFIX</code> |
|
|
|
|
Strip this prefix from the provided hostname to determine the workspace name. This is useful when used as part of an OpenSSH proxy command.
|
|
|
|
### --hostname-suffix
|
|
|
|
| Property | Value |
|
|
|-------------|-----------------------------------------|
|
|
| Type | <code>string</code> |
|
|
| Environment | <code>$CODER_SSH_HOSTNAME_SUFFIX</code> |
|
|
|
|
Strip this suffix from the provided hostname to determine the workspace name. This is useful when used as part of an OpenSSH proxy command. The suffix must be specified without a leading . character.
|
|
|
|
### -A, --forward-agent
|
|
|
|
| Property | Value |
|
|
|-------------|---------------------------------------|
|
|
| Type | <code>bool</code> |
|
|
| Environment | <code>$CODER_SSH_FORWARD_AGENT</code> |
|
|
|
|
Specifies whether to forward the SSH agent specified in $SSH_AUTH_SOCK.
|
|
|
|
### -G, --forward-gpg
|
|
|
|
| Property | Value |
|
|
|-------------|-------------------------------------|
|
|
| Type | <code>bool</code> |
|
|
| Environment | <code>$CODER_SSH_FORWARD_GPG</code> |
|
|
|
|
Specifies whether to forward the GPG agent. Unsupported on Windows workspaces, but supports all clients. Requires gnupg (gpg, gpgconf) on both the client and workspace. The GPG agent must already be running locally and will not be started for you. If a GPG agent is already running in the workspace, it will be attempted to be killed.
|
|
|
|
### --identity-agent
|
|
|
|
| Property | Value |
|
|
|-------------|----------------------------------------|
|
|
| Type | <code>string</code> |
|
|
| Environment | <code>$CODER_SSH_IDENTITY_AGENT</code> |
|
|
|
|
Specifies which identity agent to use (overrides $SSH_AUTH_SOCK), forward agent must also be enabled.
|
|
|
|
### --workspace-poll-interval
|
|
|
|
| Property | Value |
|
|
|-------------|---------------------------------------------|
|
|
| Type | <code>duration</code> |
|
|
| Environment | <code>$CODER_WORKSPACE_POLL_INTERVAL</code> |
|
|
| Default | <code>1m</code> |
|
|
|
|
Specifies how often to poll for workspace automated shutdown.
|
|
|
|
### --wait
|
|
|
|
| Property | Value |
|
|
|-------------|------------------------------|
|
|
| Type | <code>yes\|no\|auto</code> |
|
|
| Environment | <code>$CODER_SSH_WAIT</code> |
|
|
| Default | <code>auto</code> |
|
|
|
|
Specifies whether or not to wait for the startup script to finish executing. Auto means that the agent startup script behavior configured in the workspace template is used.
|
|
|
|
### --no-wait
|
|
|
|
| Property | Value |
|
|
|-------------|---------------------------------|
|
|
| Type | <code>bool</code> |
|
|
| Environment | <code>$CODER_SSH_NO_WAIT</code> |
|
|
|
|
Enter workspace immediately after the agent has connected. This is the default if the template has configured the agent startup script behavior as non-blocking.
|
|
|
|
### -l, --log-dir
|
|
|
|
| Property | Value |
|
|
|-------------|---------------------------------|
|
|
| Type | <code>string</code> |
|
|
| Environment | <code>$CODER_SSH_LOG_DIR</code> |
|
|
|
|
Specify the directory containing SSH diagnostic log files.
|
|
|
|
### -R, --remote-forward
|
|
|
|
| Property | Value |
|
|
|-------------|----------------------------------------|
|
|
| Type | <code>string-array</code> |
|
|
| Environment | <code>$CODER_SSH_REMOTE_FORWARD</code> |
|
|
|
|
Enable remote port forwarding (remote_port:local_address:local_port).
|
|
|
|
### -e, --env
|
|
|
|
| Property | Value |
|
|
|-------------|-----------------------------|
|
|
| Type | <code>string-array</code> |
|
|
| Environment | <code>$CODER_SSH_ENV</code> |
|
|
|
|
Set environment variable(s) for session (key1=value1,key2=value2,...).
|
|
|
|
### --network-info-dir
|
|
|
|
| Property | Value |
|
|
|----------|---------------------|
|
|
| Type | <code>string</code> |
|
|
|
|
Specifies a directory to write network information periodically.
|
|
|
|
### --network-info-interval
|
|
|
|
| Property | Value |
|
|
|----------|-----------------------|
|
|
| Type | <code>duration</code> |
|
|
| Default | <code>5s</code> |
|
|
|
|
Specifies the interval to update network information.
|
|
|
|
### --disable-autostart
|
|
|
|
| Property | Value |
|
|
|-------------|-------------------------------------------|
|
|
| Type | <code>bool</code> |
|
|
| Environment | <code>$CODER_SSH_DISABLE_AUTOSTART</code> |
|
|
| Default | <code>false</code> |
|
|
|
|
Disable starting the workspace automatically when connecting via SSH.
|