smallstep · tashian · Jan 28, 2026 · Jan 28, 2026
@@ -29,5 +29,6 @@ jobs:
           files: .
           fail_on_error: true
           reporter: github-pr-review
+          vale_flags: "--glob='!step-cli/reference/**'"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -8,20 +8,26 @@ Vocab = Smallstep
 SkippedScopes = script, style, pre, figure, code
 IgnoredScopes = code, tt, img, url, a
 
-[formats]
-mdx = md
-
 [*.{md,mdx}]
 BasedOnStyles = Vale, Google, write-good, Smallstep
 
 # Disable Vale.Terms - conflicts with case-variant vocabulary entries
 Vale.Terms = NO
 
-TokenIgnores = (<\/?[A-Z][A-Za-z0-9]*[^>]*\/?>), \
-               (\{[`'][^`']+[`']\}), \
-               (\x60[^\n\x60]+\x60)
+# Disable Google.Quotes - technical docs often place punctuation outside quotes for clarity
+Google.Quotes = NO
+
+# Disable rules that are too strict for technical documentation
+write-good.Passive = NO
+Google.Will = NO
+Google.We = NO
+
+TokenIgnores = (@smallstep/[a-zA-Z0-9-]+), \
+               (_[a-zA-Z0-9_]+_), \
+               ([a-zA-Z]+_[a-zA-Z_]+)
 
 BlockIgnores = (?s)<Alert.*?</Alert>, \
                (?s)<CodeBlock.*?</CodeBlock>, \
-               (?s)<Code>.*?</Code>
+               (?s)<Code>.*?</Code>, \
+               (?s)^---\n.*?\n---
 
@@ -5,8 +5,8 @@ ignorecase: false
 swap:
   smallstep: Smallstep
   Small Step: Smallstep
-  StepCA: step-ca
-  step CA: step-ca
   stepca: step-ca
   Step-CA: step-ca
   StepCLI: Step CLI
+  Smallstep UI: Smallstep console
+  Smallstep dashboard: Smallstep console
@@ -776,3 +776,163 @@ strongSwan
 Unconfigured
 userInfo
 asin
+AACompromise
+abc
+account_selection_required
+accountId
+apiVersion
+at_hash
+availabilityZone
+azp
+basicConstraints
+billingProducts
+CACompromise
+CAFingerprint
+certType
+certificateAuthority
+cfssl
+cfssljson
+choco
+cicd
+cmd
+commonName
+Concat
+consent_required
+criticalOptions
+crypto_auth
+crypto_auth_verify
+crypto_box
+crypto_box_keypair
+crypto_box_open
+crypto_secretbox
+crypto_secretbox_open
+crypto_sign
+crypto_sign_keypair
+crypto_sign_open
+crv
+cty
+digitalSignature
+disable_tlsalpn_challenge
+dpop
+emailAddresses
+excludedDNSDomains
+excludedIPRanges
+excludedURIDomains
+fi
+ghu
+Hea
+iat
+identity_policies
+imageId
+insecureAddress
+instanceId
+instanceType
+intermediate_ca_key
+iss
+Jee
+jku
+jq
+jti
+KDFs
+kdf
+kernelId
+keyAgreement
+keyEncipherment
+keyId
+keyUsage
+kty
+Kilian
+kubectl
+Liusvaara
+login_required
+matchLabels
+modutil
+mv
+my_acme_provisioner
+my_provisioner
+my_scep_provisioner
+my_webhook
+nameConstraints
+nbf
+npm
+ns
+openid
+pem_file
+pendingTime
+permanentIdentifier
+permittedDNSDomains
+permittedIPRanges
+permittedURIDomains
+preferred_username
+privateIp
+ramdiskId
+reasonCode
+redirect_uri
+reverse_proxy
+root_ca_key
+sed
+select_account
+serverAuth
+serviceAccounts
+signatureAlgorithm
+signatureAlgorithms
+systemctl
+tashian
+tls_trust_pool
+token_accessor
+token_duration
+token_policies
+token_renewable
+typeIs
+url
+vaultcas
+vault_ca_fingerprint
+vault_role_id
+vault_secret_id
+vault_uri
+wireapp
+xargs
+zsh
+_certificate
+apachectl
+disableSidebar
+html_title
+updated_at
+autogenerated
+autonumber
+awskms
+cacerts
+caBundle
+certonly
+certreq
+chmod
+DBs
+dnf
+gpg
+hostonly
+hurd
+jetstack
+killall
+launchctl
+lighttpd
+minimalistic
+Mmap
+nocopy
+pkgutil
+pnpm
+sequenceDiagram
+SSLEngine
+sublicense
+tpmkms
+virtualbox
+ykman
+alice
+issuerRef
+maxVersion
+minVersion
+notAfter
+notBefore
+organizationalUnit
+publicKey
+serialNumber
+testuser
@@ -0,0 +1 @@
+agent.md
@@ -64,6 +64,12 @@ After cloning the repository, sync Vale packages:
 vale sync
 ```
 
+Install the MDX parser for native MDX support:
+
+```bash
+pnpm add -g mdx2vast
+```
+
 ### Usage
 
 ```bash

@@ -0,0 +1,6 @@
+DO NOT modify auto-generated files inside step-cli/reference
+Use vale for docs linting
+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
+Use pnpm
+If new dependencies are needed, update CONTRIBUTING.md to reflect requirements
@@ -1,4 +1,5 @@
 ---
+updated_at: January 28, 2026
 title: Smallstep Certificate Manager Private ACME Server
 html_title: Smallstep Certificate Manager Private ACME Server
 description: Create your internal ACME server with Smallstep Certificate Manager. 
@@ -43,5 +44,5 @@ Create a [Smallstep account](https://smallstep.com/signup?product=cm) and start
 ### Even more ACME stuff
 
 * Learn [why and where](https://smallstep.com/blog/the-embarrassing-state-of-enterprise-acme/) you should consider using ACME.  
-* [Read the blog](https://smallstep.com/blog/private-acme-server/) that announced smallstep support.
+* [Read the blog](https://smallstep.com/blog/private-acme-server/) that announced Smallstep support.
 * Start using ACME for Kubernetes certificates, learn how in [this tutorial](../tutorials/kubernetes-acme-ca.mdx)
@@ -1,13 +1,13 @@
 ---
-updated_at: January 20, 2026
+updated_at: January 28, 2026
 title: Smallstep Certificate Manager Getting Started
 html_title: Get Started with Certificate Manager Guide
 description: Get started with Certificate Manager in minutes. Quick setup guide for enterprise certificate automation and PKI management with best practices.
 ---
 
 Smallstep [Certificate Manager](https://smallstep.com/certificate-manager) is a commercial product that delivers a managed certificate authority (CA) capable of issuing private x.509 TLS certificates. 
 
-Certificate Manager builds on two open-source projects, maintained by smallstep:
+Certificate Manager builds on two open-source projects, maintained by Smallstep:
 * `step-ca`: a private online certificate authority for secure automated certificate management.
 * `step`: a general-purpose cryptography toolkit and the client-side counterpart to `step-ca`.
 With Certificate Manager, you can create your own private CA to manage certificates on internal services, websites, infrastructure, people, or devices. 
@@ -30,7 +30,7 @@ Creating a team gives you access to Smallstep's products.
 Click [here](https://smallstep.com/signup?product=cm) to create a team.
 You will be asked to provide:
 * `Team Name` - Usually, this is your company name. 
-* `Team URL` - This is where you will access the smallstep console and will also be the base domain for the CA URL for any Authorities you create. 
+* `Team URL` - This is where you will access the Smallstep console and will also be the base domain for the CA URL for any Authorities you create. 
 * `First & Last Name` - Smallstep Team administrator's name. 
 * `E-mail` - Smallstep Team administrator's e-mail address.
 * `password` - This password is used to login into the Smallstep console
@@ -41,7 +41,7 @@ Smallstep team admins can subscribe to and manage Smallstep products.
 A Certificate Manager Authority is an online CA that authenticates and authorizes certificate requests.
 It can issue, renew, and revoke your x.509 TLS certificates.
 To create an Authority:
-* Log into the smallstep console, select the Certificate Manager tab, and click the "Add Authority" button.
+* Log into the Smallstep console, select the Certificate Manager tab, and click the "Add Authority" button.
 * Choose "Create a new hosted Authority".
 * Give your Authority a name and subdomain value (the URL path you wish to use for your online CA).
 * Choose "Create"
@@ -61,7 +61,7 @@ storing the private keys into [Google's Cloud KMS](https://cloud.google.com/secu
 On the Authority detail page, you will see the CA URL and Fingerprint used to interact with your CA.
 
 Certificate Manager also creates a default provisioner called `authority-admin`,
-connected to your smallstep login.
+connected to your Smallstep login.
 You can use this provisioner to administer the Authority and to get certificates. 
 See [basic certificate operations](basic-ops.mdx) for examples. 
 

@@ -1,5 +1,5 @@
 ---
-updated_at: January 20, 2026
+updated_at: January 28, 2026
 title: Smallstep Certificate Manager How It Works
 html_title: Certificate Manager Architecture Guide
 description: Technical architecture of Certificate Manager. Understand components, workflows, and security model for enterprise PKI deployment planning.
@@ -20,7 +20,7 @@ flexible, extensible toolchain with all of the server and client-side components
 you'll need to solve this problem, carefully designed to be operationally
 simple, easy to use, and hard to misuse.
 
-Certificate Manager builds on two open source projects, maintained by smallstep:
+Certificate Manager builds on two open source projects, maintained by Smallstep:
 
 - `step-ca`: a private online certificate authority for secure automated
   certificate management.
@@ -34,7 +34,7 @@ Here's how the elements described in [Core Concepts]() work are used to enable t
 
 Before issuing a certificate, your software and systems must be configured to
 trust your authorities. More precisely, you need to configure everything to
-trust your _root certificate_ (i.e., the certificate that belongs to your root
+trust your _root certificate_ (that is, the certificate that belongs to your root
 CA). You can include your root certificate in base images, distribute it using
 configuration management, or use
 [`step ca bootstrap`](https://smallstep.com/docs/step-cli/reference/ca/bootstrap)

@@ -1,5 +1,5 @@
 ---
-updated_at: November 06, 2025
+updated_at: January 28, 2026
 title: Smallstep Certificate Manager Single Sign-on Certificates
 html_title: Smallstep Certificate Manager single sign-on certificates for humans
 description: Connect your IDP to Smallstep Certificate Manager and issue certificates to your developers. 
@@ -77,7 +77,7 @@ Use the following command as a template for adding an OIDC provisioner.
 </Alert>
 
 
-This command requires Administrator privileges on the Authority. The terminal will prompt you to enter your email and perform a single sign-on flow via the smallstep console. 
+This command requires Administrator privileges on the Authority. The terminal will prompt you to enter your email and perform a single sign-on flow via the Smallstep console. 
 
 <CodeBlock language="shell-session" >
 {`No admin credentials found. You must login to execute admin commands.
@@ -87,7 +87,7 @@ Your default web browser has been opened to visit:`}
 </CodeBlock>
 
 Upon completion, your OIDC provisioner will be created.
-It will appear on your smallstep console authority detail page. 
+It will appear on your Smallstep console authority detail page. 
 
 ### Step 3 - Enable self-service single sign-on certificates. 
 From the user's perspective, when requesting a certificate, `step` detects the OIDC provisioner and initiates the OAuth login flow automatically:

@@ -1,5 +1,5 @@
 ---
-updated_at: September 17, 2025
+updated_at: January 28, 2026
 title: Webhook Events
 html_title: Configure Certificate Webhook Events Guide
 description: Integrate certificate lifecycle events via webhooks. Automate workflows based on certificate issuance, renewal, and revocation.
@@ -96,7 +96,7 @@ Where:
         </TableRow>
         <TableRow>
             <TableCell>id</TableCell>
-            <TableCell>The smallstep ssh session id </TableCell>
+            <TableCell>The Smallstep ssh session id </TableCell>
         </TableRow>
          <TableRow>
             <TableCell>timestamp</TableCell>

@@ -1,5 +1,5 @@
 ---
-updated_at: September 18, 2025
+updated_at: January 28, 2026
 title: The Design & Architecture of Smallstep
 html_title: step-ca Architecture & Design Document
 pagetitle: Architectural Design Document | Smallstep Documentation
@@ -15,14 +15,14 @@ For readers who are less familiar check out...
 
 ## About the `step` toolchain
 
-`step` is the command-line interface for all things smallstep, and a swiss-army knife for day-to-day Production Identity operations.
+`step` is the command-line interface for all things Smallstep, and a swiss-army knife for day-to-day Production Identity operations.
 
 `step` is a command-line tool for developers, operators, and security professionals to:
 
-- configure, operate, and automate all of smallstep's tools, and
+- configure, operate, and automate all of Smallstep's tools, and
 - work with open standard Production Identity technologies
 
-It's the open source core of everything smallstep does, and everything you need to work with certificates, tokens, JOSE structures (JWT, JWK, JWE, JWS), and many other common cryptography primitives.
+It's the open source core of everything Smallstep does, and everything you need to work with certificates, tokens, JOSE structures (JWT, JWK, JWE, JWS), and many other common cryptography primitives.
 
 #### `step` Characteristics
 
@@ -508,4 +508,4 @@ The `step ca federate` subcommand can be used to setup this federation, and `ste
 
 ## Get Started Today
 
-We encourage you to visit smallstep on [Github](https://github.com/smallstep/ 'smallstep on github') to build your own internal PKI and empower mTLS between your distributed services. We would love to hear about your experience and [welcome feedback](https://smallstep.com/feedback/ 'feedback') and/or questions on our [community gitter](https://gitter.im/smallstep/community 'smallstep gitter'). Or give us your opinions by taking [the PKI Survey](https://www.surveymonkey.com/r/DC6NTKN). The team continues to innovate on our offerings and new features are coming every couple of weeks so please check back often to follow our progress. Alternatively you can subscribe to our updates by entering your email below.
+We encourage you to visit Smallstep on [Github](https://github.com/smallstep/ 'Smallstep on github') to build your own internal PKI and empower mTLS between your distributed services. We would love to hear about your experience and [welcome feedback](https://smallstep.com/feedback/ 'feedback') and/or questions on our [community gitter](https://gitter.im/smallstep/community 'smallstep gitter'). Or give us your opinions by taking [the PKI Survey](https://www.surveymonkey.com/r/DC6NTKN). The team continues to innovate on our offerings and new features are coming every couple of weeks so please check back often to follow our progress. Alternatively you can subscribe to our updates by entering your email below.