Interledger documentation style guide

After a Starlight upgrade to docs-styleguide

cd <to project folder>
bun install
bun run start

Interledger uses Starlight (powered by Astro) for all its documentation sites. In order to keep our visual styling consistent across our numerous documentation sites, we have packaged our styles and shared components in an npm package.

npm i @interledger/docs-design-system

Feel free to install with the package manager of your choice.

Because we are using Starlight, content has to be authored in Markdown or MDX.

Components can be written in JSX, and imported into MDX files. Documentation pages cannot be .astro files. You are free to create Astro pages in the /pages folder though.

Visual themes

We have two visual themes for now, teal and orange. These themes are built on top of Starlight’s defaults and overrides some of the out-of-the-box styling. They are just CSS files, so use them with the path to node_modules. Unfortunately, we did not have enough braincells to figure out how to make it prettier than that. To use them in the astro.config.mjs:

export default defineConfig({
  integrations: [
    starlight({
      customCss: [
        "./node_modules/@interledger/docs-design-system/src/styles/teal-theme.css",
        "./node_modules/@interledger/docs-design-system/src/styles/ilf-docs.css",
      ],
    }),
  ],
});

If you are using them in an Astro layout file, then the import must look like this:

import '/node_modules/@interledger/docs-design-system/src/styles/teal-theme

Components

Starlight provides some built-in components that are commonly used for documentation sites. Refer to the Starlight documentation for detailed information on how to use them.

We also have a number of documentation-specific helper components that can be imported and used where necessary. You can refer to the individual pages in the sidebar to see them in action.

If you are using multiple shared components on a single page, you can import them like so:

import { CodeBlock, LinkOut } from "@interledger/docs-design-system";

For more information about importing things in Javascript, refer to import on MDN.

Docs site building

Each documentation site will inevitably have its own unique requirements. One may have custom pages and components which do not apply to any of the other documentation sites. As such, we have a general pattern for handling this. For CSS, our shared styles are all in the docs-design-system npm package. If the documentation site you’re building is simple enough, you might not even need more than what was outlined above.

In the event there are certain components or elements that only apply to specific documentation sites, we will need to write additional styles. These will go into the /src/styles folder, and use the project name as the file name, e.g. rafiki.css.

export default defineConfig({
  integrations: [
    starlight({
      customCss: [
        "./node_modules/@interledger/docs-design-system/src/styles/orange-theme.css",
        "./node_modules/@interledger/docs-design-system/src/styles/ilf-docs.css",
        "./src/styles/rafiki.css",
      ],
    }),
  ],
});

Some of our sites also have custom pages, like Web Monetization or the Interledger Developer Portal.

These are pages that live outside the Starlight integration ecosystem, and do not come with any styles nor structure. As such, you will also need to create a layout which forms the base structure of a standard web page, down to the <!doctype html> and <head> elements.

You can create multiple layout files if there are different types of pages required, and all these layout files will go into the /src/layouts folder, while the pages themselves will go into the /src/pages folder. It is highly recommended you read the Astro documentation to familiarise yourself with how this all works.

This is a very generic starter sample layout that you can work off from:

/src/layouts/Layout.astro

---
import '../styles/dinosaurland.css';

interface Props {
  title: string;
  description?: string;
}

const { title, description } = Astro.props;
---

<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="author" content="Interledger Foundation" />
    <meta name="description" content={description ? description : 'Making
    payments as easy as sending an email'}>
    <meta name="viewport" content="width=device-width" />
    <meta name="generator" content="{Astro.generator}" />
    <title>{title ? `${title} | Interledger` : 'Interledger'}</title>
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
  </head>

  <body>
    <slot />
  </body>
</html>

It had been possible to override the default Starlight components since v0.11.0, and most of our documentation sites implement this for our site header. This is because the default search bar takes up too much space for our aesthetic liking. 乁 ⁠(⁠ ⁠•⁠_⁠•⁠ ⁠)⁠ ㄏ

Although we have contemplated making this a shared component, each site header is different enough that we’ve decided to leave it up to each individual site to handle. Consult the documentation for how this works.

We want to keep some other UI components that come with the default header, so those have to be imported like so:

/src/components/Header.astro

---
import type { Props } from '@astrojs/starlight/props';
import Search from "@astrojs/starlight/components/Search.astro";
import ThemeSelect from "@astrojs/starlight/components/ThemeSelect.astro";
import SocialIcons from "@astrojs/starlight/components/SocialIcons.astro";
---
<div class="header sl-flex">
  <a href="/" class="site-logo">
    <img src="/img/logo.svg" alt="Rafiki logo">
  </a>
  <div class="secondary-wrap">
    <Search {...Astro.props} />
    <SocialIcons {...Astro.props} />
    <div class="sl-hidden md:sl-flex">
      <ThemeSelect {...Astro.props} />
    </div>
  </div>
</div>

<style>
  /* necessary styles not displayed here */
</style>