Smallstep Docs

This repository contains documentation for Smallstep projects and products. These docs are served at https://smallstep.com/docs.

Issues and pull requests are welcome!

Docs Style & Syntax

• The docs repo uses MDX syntax. MDX allows us to intersperse traditional Markdown with JSX tags (React components and other HTML-like tags). A JSX tag block looks like this:

  <Alert severity="info">
      <AlertTitle>Want to run an SSH CA?</AlertTitle>
      <div>
          By default, the SSH CA is disabled.
          Create a CA with SSH CA capabilities by running <Code>step ca init --ssh</Code>.
      </div>
  </Alert>
  

  Take a look through a few docs pages to get familiar with the React components we use in our docs, and how to use them. There's no formal docs for these yet.

• Use semantic linefeeds when possible.

• Follow the conventions outlined in Google's Technical Writing classes.

• Further reading: Writing Tools I Learned from The Economist

Preview docs locally

To run and preview docs locally (requires Node.js and Yarn):

$ yarn install
$ yarn start

Before opening a PR, format your code changes (only affects JSX and MDX):

$ yarn format

Check formatting with yarn lint.

Updating the step CLI reference docs

Everything under src/pages/docs/step-cli/reference is auto-generated whenever we release a new version of step. To make a change to the CLI reference, you'll have to make the edit in smallstep/cli and make a PR over there. The reference docs are embedded in the source files under the command folder in that repo.

Practical Zero Trust

The Practical Zero Trust articles are a bit different. They are templated, rather than freeform Markdown. Look at existing examples in src/pzt for reference.