Rafiki style guide

Before committing changes

Your PR title must contain the appropriate prefix (docs:).
Run the following command within the /packages/documentation directory:
```
npx prettier . --write
```
You can also try the following. It might work, or you might get an error.
```
pnpm format
```

After a Starlight upgrade to rafiki

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

After a GraphQL schema change

GraphQL schema changes are rare, but when they happen, here’s what to do:

Generate the GraphQL docs

Run these commands in the packages/documentation folder:

npx spectaql config-auth.yml // Auth Admin API

npx spectaql config-backend.yml // Backend Admin API

These commands generate the static HTML files for the GraphQL API docs.

Add custom pages to search indexing

Open the generated HTML files (src/pages/apis/graphql/auth/index.html and src/pages/apis/graphql/backend/index.html) and add the data-pagefind-body attribute to the <div id="docs"> element:

    <div id="docs" data-pagefind-body>
      ...
    </div>

This ensures that the GraphQL API docs are included in the site search.

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>