Rafiki style guide

Before committing changes

Ensure your PR title contains the appropriate prefix (docs:).
Run the following commands in the /packages/documentation directory and fix any errors:
```
pnpm format
pnpm lint
```

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 (for example, back end). FWIW, this is how Microsoft, Google, and Cloudflare treat the terms in their docs.

Rafiki-specific styles

Custom table styles

Many of the tables in the Rafiki docs are wider than the main content panel. We’ve tried to care for this in a few ways.

We implemented toggles across all doc sites that allows you to collapse/expand the left and right panels. This gives the main content panel a wider viewable area.
We also added support to the Rafiki docs for custom CSS table styles.

You can wrap your markdown table in one of the following divs.

<div class="overflow-table">
  // Markdown table goes here
</div>

Example Regular overflow table example

The 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">
  // Markdown table goes here
</div>

Example

Wide overflow table example

The 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">
  // Markdown table goes here
</div>

Example

Wider overflow table example