Rafiki style guide

Before committing changes

Your PR title must contain the appropriate prefix (probably docs:).

Run the following command in the /packages/documentation directory:

pnpm format

Why tho? ಠ╭╮ಠ For the same reason as Open Payments

After a Starlight upgrade to rafiki

cd <to project folder>
pnpm install
cd packages/documentation
pnpm start

Nouns

Common nouns

authorization server
resource server

Spellings

backend/frontend

When writing about the backend/frontend services and packages in Rafiki, spell as shown. Don’t hyphenate or add a space (e.g., back end). FWIW, this is how Microsoft, Google, and Cloudflare treat the terms in their docs.

Rafiki-specific styles

Custom table styles

We’ve implemented a few different custom table styles specifically for Rafiki docs. These custom styles were developed because we were running into scrolling issues as well as column width issues, primarily when text was formatted as code.

You can wrap your markdown table in an HTML <div> with one of the following custom table styles:

overflow-table

A long and wide table (vertical and horizontal scrollbars on overflow) with regular column sizing.

<div class="overflow-table">

| Column Header 1 | Column Header 2 | Column Header 3 |
| --------------- | --------------- | --------------- |
| Content         | Content         | Content         |
| Content         | Content         | Content         |

</div>

overflow-table wide-column

A long and wide table (vertical and horizontal scrollbars on overflow) that needs extra wide columns to accommodate text formatted as code.

wide-column sets the minimum width of the table (sum of the total width of all columns) to 60rem.

<div class="overflow-table wide-column">

| Column Header 1 | Column Header 2 | Column Header 3 |
| --------------- | --------------- | --------------- |
| Content         | Content         | Content         |
| Content         | Content         | Content         |

</div>

overflow-table wider-column

A long and wide table (vertical and horizontal scrollbars on overflow) that needs even larger, extra wide columns to accommodate text formatted as code.

wider-column sets the minimum width of the table (sum of the total width of all columns) to 80rem.

<div class="overflow-table wider-column">

| Column Header 1 | Column Header 2 | Column Header 3 |
| --------------- | --------------- | --------------- |
| Content         | Content         | Content         |
| Content         | Content         | Content         |

</div>