Skip to content
Starlight Compass

Getting Started

In this tutorial, you install Starlight Compass, review a page of your Starlight site in the dev toolbar, and declare the page’s documentation type so Compass can warn you when it drifts.

Prerequisites

Section titled “Prerequisites”
  • A Starlight website. If you don’t have one yet, follow the “Getting Started” guide in the Starlight docs.
  • A TypeSafe API key. Jev is in early access. Create a key in the TypeSafe console.

Install the plugin

Section titled “Install the plugin”

  1. Install the package:

    Terminal window
    npm install starlight-compass

  2. Add the plugin to your Starlight configuration:

    astro.config.mjs
    import starlight from "@astrojs/starlight";
    import { defineConfig } from "astro/config";
    import starlightCompass from "starlight-compass";
    

    export default defineConfig({
      integrations: [
        starlight({
          plugins: [starlightCompass()],
          title: "My Docs",
        }),
      ],
    });

  3. Extend your content collection schema so that pages can declare their documentation type:

    src/content.config.ts
    import { docsLoader } from "@astrojs/starlight/loaders";
    import { docsSchema } from "@astrojs/starlight/schema";
    import { defineCollection } from "astro:content";
    import { compassSchema } from "starlight-compass/schema";
    

    export const collections = {
      docs: defineCollection({
        loader: docsLoader(),
        schema: docsSchema(),
        schema: docsSchema({ extend: compassSchema() }),
      }),
    };

  4. Create a .env file in your project root with your API key. Make sure .env is listed in your .gitignore file.

    .env
    TYPESAFE_API_KEY=apikey_...

Review your first page

Section titled “Review your first page”

  1. Start the development server:

    Terminal window
    npm run dev

  2. Open any documentation page in your browser and click the compass icon in the Astro dev toolbar at the bottom of the page.

    The Compass window shows the type the page reads like, for example “Reads like a how-to guide (92% confidence)”, and suggests declaring it.

  3. Declare the suggested type in the frontmatter of the page:

    src/content/docs/guides/deploy.md
    ---
    title: Deploy your site
    diataxis: how-to
    ---

  4. Save the file. The page reloads, Compass reviews it again, and the suggestion disappears.

  5. To see what drift looks like, change the value to diataxis: reference and save again.

    The toolbar icon now shows a red dot, and the Compass window reports an error: the page is declared as reference but reads like a how-to guide. Set the value back to how-to when you are done.

Next steps

Section titled “Next steps”

You reviewed a page while writing it and declared its type. From here, you can: