Routes, links & images

Stainless Docs uses Starlight’s project structure and Astro’s routing capabilities. If you’re familiar with Starlight and Astro, you don’t have to learn anything new. If not, don’t worry—we explain everything in detail below.

Note

Starlight with Astro, which is what Stainless Docs uses, expects your content to be in src/content/docs, but Astro without Starlight looks for content in src/content and pages in src/content/pages. If you’re looking at Astro’s documentation, it’s important to keep this difference in mind.

File-based routing

Routes for your site are generated from the files and folders your project’s src/content/docs folder.

Have a look at this example folder and file structure:

📁 <root>
└─ 📁 src/
   ├─ 📁 assets/
   │  ├─ 📄 logo.svg
   │  └─ 📄 banner.png
   └─ 📁 content/
      └─ 📁 docs/
         ├─ 📄 getting-started.md
         └─ 📁 installation/
            ├─ 📄 macos.mdx
            ├─ 📄 windows.mdx
            └─ 📄 linux.mdx

A route is essentially the path to a content file, starting from the /src/content/docs directory, without its file extension. The file structure above will create these routes:

Route	Content the route points to
/getting-started	/src/content/docs/getting-started.md
/installation/macos	/src/content/docs/installation/macos.mdx
/installation/windows	/src/content/docs/installation/windows.mdx
/installation/linux	/src/content/docs/installation/linux.mdx

To get a full URL to a page, start with your domain and add the route. For example, if your domain is example.com, the full URL to the getting started page shown above would be https://example.com/getting-started.

For more information on advanced routing behaviors, refer to the Astro routing documentation.

Link to pages

To link to a page from a Markdown file, add a link to that page’s route.

For example, to link to src/content/docs/installation/macos.mdx, link to /installation/macos:

src/content/docs/getting-started.mdx

---
title: Getting started
description: This is a description of the page
---
## Hello, world!
[Link to a page](/installation/macos)

The forward slash (/) at the beginning of your link is important; it represents the root of your site and makes this an absolute link. Without that slash, the link would be a relative link, and relative links might not work on some pages.

Inside your astro.config.ts file, you can link to pages the same way. For example, to add a link to a page to your sidebar, add its route:

astro.config.ts

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

export default defineConfig({
  integrations: [
    stainlessDocs({
      title: "My Docs",
      tabs: [
        {
          label: "Guides",
          link: "/",
          sidebar: ["installation/macos"],
        },
      ],
    }),
  ],
});

Images

Stainless Docs uses Astro’s built-in image pipeline to serve images. Refer to the Astro images documentation for more information.

Redirects

Stainless Docs supports defining redirects via the redirects property in your Astro config. Documentation for redirects can be found in the Astro routing documentation.

When your site is hosted with Stainless, redirects defined in your Astro config are automatically handled with the appropriate HTTP status codes.