Merge pull request #493 from smallstep/carl/vale-zero

tashian · web-flow · commit 63979d5fd479 · 2026-02-04T10:54:15.000-08:00
Zero vale errors
diff --git a/.github/mdl.config.json b/.github/mdl.config.json
@@ -40,7 +40,7 @@
       "pattern": "^https://www.gnu.org"
     },
     {
-      "pattern": "^https://freedesktop.org"
+      "pattern": "^https://.*freedesktop.org"
     },
     {
       "pattern": "^https://www.hashicorp.com"
diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml
@@ -27,7 +27,7 @@ jobs:
       - name: Check changed files only (PR)
         if: github.event_name == 'pull_request'
         run: |
-          CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- '*.mdx')
+          CHANGED_FILES=$(git diff --name-only --diff-filter=ACMR origin/${{ github.base_ref }}...HEAD -- '*.mdx')
           if [ -z "$CHANGED_FILES" ]; then
             echo "No .mdx files changed"
             exit 0
diff --git a/.vale.ini b/.vale.ini
@@ -43,6 +43,13 @@ Google.Exclamation = NO
 # Slang like "TL;DR" is acceptable in developer-focused technical documentation
 Google.Slang = NO
 
+# "There is/There are" constructions are acceptable in technical documentation
+write-good.ThereIs = NO
+
+# DateFormat matches version numbers like "10.0.15063" incorrectly
+Google.DateFormat = NO
+
+
 TokenIgnores = (@smallstep/[a-zA-Z0-9-]+), \
                (_[a-zA-Z0-9_]+_), \
                ([a-zA-Z]+_[a-zA-Z_]+)
diff --git a/.vale/styles/Smallstep/Branding.yml b/.vale/styles/Smallstep/Branding.yml
@@ -3,7 +3,6 @@ message: "Use '%s' instead of '%s' for consistent branding."
 level: error
 ignorecase: false
 swap:
-  smallstep: Smallstep
   Small Step: Smallstep
   stepca: step-ca
   Step-CA: step-ca
diff --git a/.vale/styles/config/vocabularies/Smallstep/accept.txt b/.vale/styles/config/vocabularies/Smallstep/accept.txt
@@ -772,7 +772,6 @@ attestationRoots
 clientId
 complexify
 customappsso
-Emojivoto
 encryptedKey
 excludeIntermediate
 failover
@@ -948,3 +947,4 @@ organizationalUnit
 publicKey
 serialNumber
 testuser
+disallow
diff --git a/agent.md b/agent.md
@@ -1,4 +1,8 @@
-Use vale for docs linting, ignoring auto-generated files in step-cli/reference
+Use vale for docs linting.
+When running vale, always ignore auto-generated files in step-cli/reference:
+
+vale --no-wrap --glob='!step-cli/reference/**'
+
 DO NOT modify any auto-generated files inside step-cli/reference
 Use markdown-link-check to check links
 To preview the docs in a web browser, run `pnpm dev` inside the `smallstep.com` repo, which you may find in the parent directory. A server will open on https://localhost:5050
diff --git a/certificate-manager/acme-old.mdx b/certificate-manager/acme-old.mdx
@@ -22,7 +22,7 @@ Automatically manage certificates on internal websites, servers, and the entire
 ### About ACME
 At a high level, ACME is pretty simple. An ACME client creates an account with an ACME server and submits a certificate order. The server responds with a set of challenges for the client to complete to prove control over identifiers (domain names) in the certificate. Once the client successfully completes these challenges, it submits a certificate signing request (CSR) and the server issues a certificate.
 
-The most interesting part of all of this is the challenge – where the client proves control over an identifier. No single standard way exists to "prove control" over an "identifier", so the core ACME specification makes this an extension point. Smallstep supports all the popular ACME challenges including DNS, HTTP, ALPN, IP, and EAB configurations. 
+The most interesting part of all of this is the challenge—where the client proves control over an identifier. No single standard way exists to "prove control" over an "identifier", so the core ACME specification makes this an extension point. Smallstep supports all the popular ACME challenges including DNS, HTTP, ALPN, IP, and EAB configurations. 
 
 ### ACME challenge verification
 When public ACME Certificate Authorities (CA) like Let's Encrypt issue certificates to clients in the Web PKI, the CA depends heavily on public DNS for client verification. To get a certificate, a client must prove to the CA that it either directly controls the public DNS records for a domain (for the DNS-01 challenge type) or controls the IP address pointed to by public DNS records (for the HTTP-01 and TLS-ALPN-01 challenge types).
diff --git a/certificate-manager/basic-ops.mdx b/certificate-manager/basic-ops.mdx
@@ -23,7 +23,7 @@ This tutorial covers:
 ### Before you begin
 This tutorial assumes you have created a Smallstep Team and a Certificate Manager Authority using the steps in [Getting Started](./getting-started.mdx).
 
-### Step 1 - Create a test certificate
+### 1.Create a test certificate
 
 With an Authority created and your local client configured,
 you can create a test certificate by running the `step ca certificate` command.
@@ -43,7 +43,7 @@ In this command, we are asking the CA to create a certificate with the following
 When you run this command, it will envoke the `authority-admin` provisioner and start a single sign-on flow via the Smallstep console.
 After a successful sign-in, the authority will issue the certificate. 
 
-### Step 2 - Inspect a test certificate
+### 2. Inspect a test certificate
 You can inspect your certificate by running:
 
 <CodeBlock language="shell-session" copyText="step certificate inspect --short myservice.crt">
@@ -63,7 +63,7 @@ X.509v3 TLS Certificate (ECDSA P-256) [Serial: 2441...2018]
           to:  2021-10-05T21:31:12Z
 ```
 
-### Step 3 - Renew a certificate
+### 3. Renew a certificate
 Certificates expire. 
 Certificate Manager makes renewing a certificate ahead of expiration easy. 
 Renewals are authenticated using your existing certificate and produce an identical certificate with a new serial number and extended lifetime.
@@ -92,7 +92,7 @@ X.509v3 TLS Certificate (ECDSA P-256) [Serial: 2441...2018]
 </CodeBlock>
 
 
-### Step 4 - Revoke a certificate
+### 4. Revoke a certificate
 
 Certificate Manager DevOps Authorities use passive revocation and short-lived certificates by default. 
 To passively revoke a certificate means to block its renewal at the CA. 
diff --git a/certificate-manager/core-concepts.mdx b/certificate-manager/core-concepts.mdx
@@ -9,11 +9,11 @@ The Smallstep Platform is powered by a number of components that can be combined
 
 The components include:
 
-- **[Authorities]()**— Certificate or registration authorities powered by `step-ca`
-- **[Provisioners]()**— Machinery for securely automating certificate issuance
-- **[Inventories]()**— Catalogs of entities like hosts, services, and people for use with templates and provisioners
-- **[Templates]()**— Customization of x.509 or SSH certificates for any use case
-- **[Events]()**— Observability and alerting for certificate lifecycle activities
+- **[Authorities]()**: Certificate or registration authorities powered by `step-ca`
+- **[Provisioners]()**: Machinery for securely automating certificate issuance
+- **[Inventories]()**: Catalogs of entities like hosts, services, and people for use with templates and provisioners
+- **[Templates]()**: Customization of x.509 or SSH certificates for any use case
+- **[Events]()**: Observability and alerting for certificate lifecycle activities
 
 
 # Authorities
diff --git a/certificate-manager/how-it-works.mdx b/certificate-manager/how-it-works.mdx
@@ -157,7 +157,7 @@ default for the `OIDC` provisioner).
 * This is an Advanced Authority feature
 
 Some use cases demand an option to renew expired certificates.
-For example, intermittently-connected devices may not be able to reach the CA in time for a renewal.
+For example, intermittently connected devices may not be able to reach the CA in time for a renewal.
 The ability to renew expired certificates can be enabled on a per-provisioner basis.
 Enable it in the Smallstep console when you create a new provisioner,
 or on the command line for an existing provisioner.
diff --git a/certificate-manager/kubernetes-tls/kubernetes-step-issuer.mdx b/certificate-manager/kubernetes-tls/kubernetes-step-issuer.mdx
@@ -44,7 +44,7 @@ You'll need it for later steps.
 
 Upon success, you will see the provisioner’s configuration returned as a successful response. 
 
-Run the [following command](https://smallstep.com/docs/step-cli/reference/ca/provisioner/list), and make a note of the new provisioner’s `“kid”` field (the *5th line listed*; it will be required in later steps):
+Run the [following command](https://smallstep.com/docs/step-cli/reference/ca/provisioner/list), and make a note of the new provisioner's `"kid"` field (the *fifth line listed*; it will be required in later steps):
 
 <CodeBlock
   language="shell-session"
diff --git a/design-document.mdx b/design-document.mdx
@@ -42,7 +42,7 @@ It's the open source core of everything Smallstep does, and everything you need
 - Verify and inspect JWTs
 - Get an OAuth access token or OpenID Connect identity token to access APIs
 - Get TLS certificates from `step-ca`
-- Install root certificates and issue locally-trusted development certificates
+- Install root certificates and issue locally trusted development certificates
 - Inspect and lint X.509 certificates
 - Encrypt data using JWE or NaCl
 - Login to SSH using `step-ssh`
diff --git a/manifest.json b/manifest.json
@@ -1643,10 +1643,6 @@
               "title": "Run an SSH CA and connect to VMs using SSH certificates",
               "path": "/tutorials/ssh-certificate-login.mdx"
             },
-            {
-              "title": "Use AWS to deploy a certificate authority and secure microservices",
-              "path": "/tutorials/mutual-tls-aws.mdx"
-            },
             {
               "title": "Run `step-ca` in a Docker container",
               "path": "/tutorials/docker-tls-certificate-authority.mdx"
diff --git a/platform/README.mdx b/platform/README.mdx
@@ -9,7 +9,7 @@ Certificates are a fundamental part of any non-trivial architecture. They provid
 
 Smallstep is a comprehensive device identity solution for securely identifying company-owned or company-managed devices using high-assurance ***cryptographically attested device identity*** certificates. 
 
-As networks and resources become increasingly distributed — with SaaS moving sensitive resources off private networks and BYOD policies introducing personal devices — threats to data confidentiality grow more aggressive. Organizations are seeking more secure methods to ensure that only authorized users on authorized devices can access sensitive resources. Provisioning trusted devices with device-attested client certificates for accessing critical resources within your organisation is the most effective way to achieve this.
+As networks and resources become increasingly distributed—with SaaS moving sensitive resources off private networks and BYOD policies introducing personal devices—threats to data confidentiality grow more aggressive. Organizations are seeking more secure methods to ensure that only authorized users on authorized devices can access sensitive resources. Provisioning trusted devices with device-attested client certificates for accessing critical resources within your organisation is the most effective way to achieve this.
 
 Smallstep provides the means to use the strongest possible assurance of device identity to ensure that only trusted company-approved devices can enroll for client certificates to access sensitive organisational resources. This procedure is facilitated through the [ACME device attestation enrollment](https://smallstep.com/blog/managed-device-attestation/), effectively protecting your organization from data breaches caused by credential compromise or phishing.  
 
diff --git a/platform/enrollment-guide.mdx b/platform/enrollment-guide.mdx
@@ -52,7 +52,7 @@ using the [Smallstep Desktop App](./smallstep-app.mdx)
 or the [Smallstep Agent](./smallstep-agent.mdx).
 
 By default, administrators
-must approve newly-enrolled devices
+must approve newly enrolled devices
 before they can access any of your resources.
 You can change this in [Team Settings](https://smallstep.com/app/?next=/settings/team).
 
diff --git a/platform/smallstep-app.mdx b/platform/smallstep-app.mdx
@@ -19,15 +19,7 @@ On macOS and Windows, the Smallstep Agent includes an optional desktop app UI fo
 The agent runs as a background service on all platforms.
 </Alert>
 
-Installers for macOS, Windows and Linux can be also be downloaded from [GitHub releases](https://github.com/smallstep/smallstep-desktop/releases). Releases are signed with, and can be verified, by cosign.
-
-| Platform  | Release  |
-|:--|:--|
-| macOS  | <a href='https://packages.smallstep.com/stable/darwin/Smallstep.dmg'>Latest Version</a>  |
-| Linux (Flatpak) | <a href='https://packages.smallstep.com/stable/flatpak/Smallstep.flatpakref'>Latest Version</a>  |
-| Linux (.deb) | <a href='https://packages.smallstep.com/stable/deb/smallstep-desktop.deb'>Latest Version</a>  |
-| Linux (.rpm) | <a href='https://packages.smallstep.com/stable/rpm/smallstep-desktop.rpm'>Latest Version</a>  |
-| Windows  | <a href='https://packages.smallstep.com/stable/windows/Smallstep.exe'>Latest Version</a>  |
+Installers for macOS, Windows and Linux can be downloaded from [GitHub releases](https://github.com/smallstep/step-agent-plugin/releases). Releases are signed with, and can be verified, by cosign.
 
 ## System requirements
 
@@ -38,7 +30,7 @@ Installers for macOS, Windows and Linux can be also be downloaded from [GitHub r
 
 ### Linux
 
-- Flatpak, or Debian 12+, Ubuntu 22.04+, Fedora 38+
+- Debian 12+, Ubuntu 22.04+, Fedora 38+
 - `systemd`-based service manager
 - Trusted Platform Module (TPM 2.0)
 - p11-kit
diff --git a/ssh/acls.mdx b/ssh/acls.mdx
@@ -33,7 +33,7 @@ Let's look at an example:
 * The `data` group will have access to  `myserver #2` and  `myserver #3`.
 * The `ops` group will have `sudo` access to `myserver #2` and `myserver #3`.
 
-Of course, hosts and groups can have as many tag combinations as you like.  Take a minute to think about how you'd like to use Host Tags in your environment.
+Of course, hosts, and groups can have as many tag combinations as you like. Take a minute to think about how you'd like to use Host Tags in your environment.
 
 ### Step 1: Determine host tag combination
 
diff --git a/ssh/hosts-step-by-step.mdx b/ssh/hosts-step-by-step.mdx
@@ -71,7 +71,7 @@ step ssh certificate $hostname /etc/ssh/ssh_host_ecdsa_key.pub \
 
 #### If a host has multiple hostnames...
 
-> **Note:** When a host has multiple hostnames, your users will only be able to `ssh` to the canonical `$hostname`, as shown by the `step ssh hosts` command.
+> **Note:** When a host has multiple hostnames, your users can only `ssh` to the canonical `$hostname`, as shown by the `step ssh hosts` command.
 
 If you need multiple hostnames in your host certificate (for example, public and private hostnames, or a hostname and an IP address), you can pass each of them to `step ssh certificate` via the `--principal` flag:
 
diff --git a/ssh/hosts.mdx b/ssh/hosts.mdx
@@ -148,7 +148,9 @@ This script will:
 
 ## Optional hardening
 
-Now that you're using certificates, you may wish to explicitly disallow the use of `authorized_keys` files on the host.
+Now that you're using certificates,
+you may wish to explicitly block the
+use of `authorized_keys` files on the host.
 
 You can do this by setting `AuthorizedKeysFile none` in `sshd_config`. You may want to allow `authorized_keys` for an emergency access account, however. A configuration for this might look like:
 
diff --git a/step-ca/README.mdx b/step-ca/README.mdx
@@ -70,7 +70,7 @@ For example, you can have your CA issue certificates in exchange for:
   - ID tokens from Okta, Google Workspace, Microsoft Entra ID and Auth0
   - ID tokens from an OAuth OIDC service you host, like [Keycloak](https://www.keycloak.org/) or [Dex](https://github.com/dexidp/dex)
 - [Cloud instance identity documents](https://smallstep.com/blog/embarrassingly-easy-certificates-on-aws-azure-gcp/) for VMs on AWS, GCP, and Azure
-- [Single-use, short-lived JWK tokens](./provisioners.mdx#jwk), for example, issued by your CD tool — Puppet, Chef, Ansible, Terraform, etc.
+- [Single-use, short-lived JWK tokens](./provisioners.mdx#jwk), for example, issued by your CD tool—Puppet, Chef, Ansible, Terraform, etc.
 
 ### Templates
 
diff --git a/step-ca/certificate-authority-server-production.mdx b/step-ca/certificate-authority-server-production.mdx
@@ -770,7 +770,7 @@ Root rotation is out of scope for this document.
 
 ### Rotating an intermediate CA
 
-Creating a new Intermediate CA will not affect previously-issued leaf certificates.
+Creating a new Intermediate CA will not affect previously issued leaf certificates.
 When they were issued, these certificates were bundled with the old intermediate CA.
 When an old certificate is renewed,
 the entire PEM bundle is replaced.
diff --git a/step-ca/renewal.mdx b/step-ca/renewal.mdx
@@ -409,7 +409,7 @@ Unfortunately, it also lets an attacker with the private key do the same thing.
 To prevent this, you need to explicitly tell `step-ca` to revoke a retired certificate.
 See the [certificate revocation section](./revocation.mdx) for details.
 
-#### Renewal after expiry: For intermittently-connected devices
+#### Renewal after expiry: For intermittently connected devices
 
 You can configure a provisioner to allow certificates to be renewed after they expire.
 This is not the default behavior,
diff --git a/step-ca/templates.mdx b/step-ca/templates.mdx
diff --git a/tutorials/connect-intune-to-smallstep.mdx b/tutorials/connect-intune-to-smallstep.mdx
diff --git a/tutorials/connect-workspace-one-to-smallstep.mdx b/tutorials/connect-workspace-one-to-smallstep.mdx
diff --git a/tutorials/intermediate-ca-new-ca.mdx b/tutorials/intermediate-ca-new-ca.mdx
diff --git a/tutorials/intune-mdm-setup-guide.mdx b/tutorials/intune-mdm-setup-guide.mdx
diff --git a/tutorials/mutual-tls-aws.mdx b/tutorials/mutual-tls-aws.mdx
diff --git a/tutorials/user-authentication.mdx b/tutorials/user-authentication.mdx
diff --git a/tutorials/wifi-setup-guide.mdx b/tutorials/wifi-setup-guide.mdx

Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,7 @@`
`40`	`40`	`"pattern": "^https://www.gnu.org"`
`41`	`41`	`},`
`42`	`42`	`{`
`43`		`- "pattern": "^https://freedesktop.org"`
	`43`	`+ "pattern": "^https://.*freedesktop.org"`
`44`	`44`	`},`
`45`	`45`	`{`
`46`	`46`	`"pattern": "^https://www.hashicorp.com"`