Docs Platform quickstart

The Stainless Docs Platform is currently in early access. Expect breaking changes to APIs before 1.0. To request access, fill out our interest form.

Get your documentation site up and running quickly, complete with automatically-generated API and SDK references.

Requirements

You need Node.js v22+, a Stainless account, the Stainless CLI, and early access to the Stainless Docs Platform to follow this guide.

If you don’t have the Stainless CLI, install it using Homebrew:

brew install stainless-api/tap/stl

If you don’t have early access to the Stainless Docs Platform, fill out our interest form.

Create your docs site

In the Stainless dashboard, select a project you want to create documentation for and go to the API Docs tab. Press the Get started button to create a new GitHub repository for your site, assign a staging domain, and start your first docs site deploy.

If you don’t see the API Docs tab, make sure you have early access to the Stainless Docs Platform. To request access, fill out our interest form.

If you have access, make sure you’re viewing a specific project in the dashboard, your list of all projects.

Another reason you may not see the API Docs tab is if you don’t

After you press the Get started button you’ll see information about your new docs site, including its domain, repository, and build history.

Your site’s GitHub repo is part of the stainless-sdks GitHub organization by default. Let us know if you want it moved to your own organization.

Create a local copy

To make changes and preview them, create a local copy of your site.

Clone your site’s repository

First, clone your site’s GitHub repository.

If you’re not familiar with GitHub, refer to GitHub’s documentation for cloning repositories for more information.

Install dependencies

Run the following command inside your site’s directory to install the required dependencies:

pnpm install

Authenticate with Stainless

To generate API and SDK reference pages, you’ll need to authenticate with the Stainless CLI:

stl auth login

Run stl auth status to confirm you’re logged in.

You can also authenticate using an .env file and an API key.

View your site

To view the local copy of your site, run this command inside your site’s directory to build your site and start a local web development server:

pnpm dev

You’ll see a URL in the output of this command (typically http://localhost:4321, unless that port is already in use). Open the URL in your web browser to see your docs site.

Edit your site

Your docs site is an Astro project that you fully own and control, so you can change the style, content, behavior, and structure of your site to meet your needs.

Let’s make a few changes to see how things work. Have a look at our product structure docs if you’re curious about the files and folders you’re seeing.

Change a page’s title and content

The content of your site’s home page is in src/content/docs/index.mdx. Open that file in your editor of choice.

Alongside your editor, open your locally running site in a web browser so you can see changes as you make them.

At the top of index.mdx you’ll see some frontmatter which includes a title property. Below that you’ll see some imports, an <Image> component, and the text content of the page.

Change the title and the text content in index.mdx, then save the file.

src/content/docs/index.mdx

---
title: Hello, World!
title: My Docs
description: Get started building your docs site with Stainless.
---

import { Card, CardGrid } from "@astrojs/starlight/components";
import Image from "astro/components/Image.astro";
import steel from "../../assets/steel.png";

<Image
  src={steel}
  alt="The Stainless logo"
  style="height: 200px; width: auto;"
/>

Welcome to your Stainless Docs site!
My front page content.

When you save the file, your web browser will automatically reload the page and display your changes.

Add a new page

To add a new page to your docs site, add a new Markdown or MDX file in your site’s src/content/docs directory.

Here’s an example of a new product overview page:

src/content/docs/product-overview.mdx

---
title: Product overview
description: This is an example product overview page
---

This content appears immediately under the page's `title` (defined in the
frontmatter above) which is automatically rendered on this page as a first
level heading.

## This is a second level heading

More content...

Frontmatter containing a title is required. You can also add any frontmatter supported by Astro and Starlight. See Starlight’s frontmatter reference for details.

Add your logo

To add your logo, put your logo’s image file in your site’s src/assets directory. We recommend using an SVG or PNG image, but any image format supported by Astro will work.

Next, add your logo to astro.config.ts:

astro.config.ts

import { defineConfig } from "astro/config";
import {
  generateAPIReferenceItems,
  stainlessDocs,
} from "@stainless-api/docs";

export default defineConfig({
  integrations: [
    stainlessDocs({
      // ...
      logo: {
        src: "./src/assets/logo.svg",
        replacesTitle: true, // If your logo contains your site's title
        alt: "My Docs",
      },
    }),
  ],
});

Now replace the Stainless logo on your front page with your own logo:

src/content/docs/index.mdx

---
title: My Docs
description: Get started building your docs site with Stainless.
---

import { Card, CardGrid } from "@astrojs/starlight/components";
import Image from "astro/components/Image.astro";
import steel from "../../assets/steel.png";
import logo from "../../assets/logo.svg";

<Image
  src={steel}
  alt="The Stainless logo"
  src={logo}
  alt="Your logo description"
  style="height: 200px; width: auto;"
/>

My front page content.

You can use the same approach to add your logo, or any other image, to any page of your site.

If you have different logo images for light and dark mode, refer to Starlight’s documentation for adding light and dark variants.

Change theme colors

To use your brand colors for links and accents on your site, open theme.css and modify the six CSS variables at the top (three for light mode, three for dark mode).

For example, this will change your site’s colors from blue to green:

theme.css

:root[data-theme="light"] {
  --stl-ui-swatch-accent-base: #155dfc;
  --stl-ui-swatch-accent-muted: #bedbff;
  --stl-ui-swatch-accent-faint: #eff6ff;
  --stl-ui-swatch-accent-base: #11cc8d;
  --stl-ui-swatch-accent-muted: #beffe9;
  --stl-ui-swatch-accent-faint: #effff9;
}

:root[data-theme="dark"] {
  --stl-ui-swatch-accent-base: #2b7fff;
  --stl-ui-swatch-accent-muted: #132762;
  --stl-ui-swatch-accent-faint: #0b1128;
  --stl-ui-swatch-accent-base: #1eb281;
  --stl-ui-swatch-accent-muted: #136247;
  --stl-ui-swatch-accent-faint: #0b281e;
}

Make sure everything looks correct in both light and dark mode when you change these colors. You can quickly switch between light and dark mode using the switcher at the top right on your site.

Add custom JavaScript

You can add custom JavaScript to every page of your site, or to individual pages.

Add a script to every page

To add a script to every page of your site (in your site’s <head> element), first put the JavaScript file in your site’s public directory:

public/example-script.js

console.log('Hello from the example script!');

Next, add the script to your astro.config.ts file:

astro.config.ts

import { defineConfig } from "astro/config";
import {
  generateAPIReferenceItems,
  stainlessDocs,
} from "@stainless-api/docs";

export default defineConfig({
  integrations: [
    stainlessDocs({
      // ...
      head: [
        {
          tag: "script",
          attrs: {
          src: "example-script.js",
        },
      ],
    }),
  ],
});

The JavaScript in example-script.js will now run every time any page of your site loads.

Add a script to a specific page

To add JavaScript to a specific page, refer to Astro’s client-side scripts documentation for details.

Add a React component

To add a React component to your site, put the component’s code in a file in src/components:

src/components/Counter.tsx

import { useState } from "react";

export default function Counter() {
  const [count, setCount] = useState(0);
  return (
    <div>
      Counter: {count}
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
}

Next, import the component on any page of your site:

src/content/docs/example-page.mdx

---
title: Example page
---

import Counter from "/src/components/Counter.tsx";

This is an example page with a counter:

<Counter client:load />

The client:load directive ensures that your component is rendered client-side. Without client:load, the component will only be rendered server-side at build time and will not be interactive. See the Astro client-directives documentation for more information.

Add components from other frameworks

We provide built-in support for React, but you can use components from other frameworks by adding the appropriate Astro integration. Here are some Astro integrations for a few popular frameworks:

• Vue
• Svelte
• Solid
• Preact

Deploy your site

When you’re happy with your local changes, commit to your repository’s main branch and push to GitHub:

# Stage all files
git add -A

# Commit your changes
git commit -m "My site changes"

# Push to main on GitHub
git push origin main

When you push to main we’ll automatically build and deploy your site. Go to your Stainless dashboard, navigate to your project, and look in the API Docs tab to see the status of your site’s build.

When the build is complete, your updated site will be available at your staging domain.

Next steps

Now that you’re up and running with the Stainless Docs Platform, check out the rest of this documentation to see what else is possible. You can also refer to Astro’s documentation and Starlight’s documentation for more details about the underling technologies the Stainless Docs Platform is built on.

The Stainless Docs Platform is currently in early access, and we’d love to know what you think. If we can help, or if you have questions or thoughts you’d be kind enough to share, please reach out!