Interledger documentation style guide
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.
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.
We have 2 visual themes, green for specification documentation and orange for product documentation. 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
If you are using them in an Astro layout file, then the import would look like this for the build to not fail:
Starlight provides some built-in components that are commonly used for documentation sites. Please 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.
For the shared components, if you are using both CodeBlock and Disclosure on the same page, you can import them both like so:
Docs site building
Each documentation site will inevitably have their own unique requirements, some 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.
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
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 suggested 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:
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. Please 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: