Contribution guide

We love that you want to help us with our docs in GitHub, so here’s our guidelines to help make this easier for you.

The first thing to know is that Kinde has editorial discretion over all docs and we will review and edit community contributions to keep content in line with our styles and standards.

Don’t let this stop you from raising issues or making suggestions - we need your expertise. We just don’t expect writing perfection, so we’ve got you covered.

What to contribute

Our docs describe what Kinde does, how our platform works, the core functions, configurations, features, settings, etc. We’re not trying to cover every use case, just the most common.

Please raise an issue or suggestion if:

Something is incorrect and needs to be fixed
Something is under-explained and needs improvement
You find a gap in the docs or missing information

What we are not looking for:

Product suggestions or feature requests - please log these here
Workarounds or solutions from third-parties
Non-specific feedback such as ‘bad doc, please improve’.

Ways to contribute

Raise an issue

Let us know if a document is wrong or needs fixing. Be as specific as you can so we can address it quickly. An example is where a code snippet is incorrect, or a procedure is no longer working. For issues, provide:

Clear descriptive titles
Links to relevant pages/files
Explanations as to why (or for whom) this is a problem
Optional: proposed solutions

Suggest a single page edit

Suggest an improvement or change to a document by selecting Edit this page in your browser on the document. This will take you to GitHub where you can edit the content of the file and then create a pull request.

As part of creating the pull request, make sure you explain why the changes are needed, who they help, and how.

Raise a PR for bigger contributions

We prefer to write the big stuff ourselves, so we encourage people to raise issues about gaps in our content and provide suggestions that way.

However, if you want to create a new topic or edit multiple files, go to GitHub to create a branch or fork and raise a PR. There’s no guarantee your pages will be approved and merged, but we will review and get in touch to discuss and definitely consider new content for inclusion.

Contributing to SDK documentation

Our SDK docs are always evolving and we welcome suggestions and contributions to make them better. SDK docs are stored with our other docs (see the file structure below). The SDKs themselves are stored in separate Kinde repos.

General document structure

Most Kinde docs follow a similar structure:

What is the topic about and who is it for (1-2 sentences)
Conceptual explanations with appropriate headings
Before you begin section for prerequisites
Procedure with steps - How to do x.
Supplementary or adjacent information
Related topics

How we write

Our documents are used by developers of varying experience, people from different language backgrounds, and users who are in a hurry to get the answer they need. Our guiding principle is to always use clear, simple language.

Our docs are not translated currently, but they will be soon. Plain English makes translation easier.

Writing principles

Use direct, clear sentences and short paragraphs
Use simple, plain vocabulary and phrases
Minimize jargon, idioms, and internet shorthand
Don’t make assumptions about what readers already know
Explain abbreviations and acronyms in full

Content principles

Use short, descriptive headings that include keywords, so people can scan to find what they need. E.g. ‘Update redirect URLs’, instead of ‘Edit the .env file’.
Provide clear, step-by-step instructions that any level of user could follow easily.
Include conceptual explanations and use cases for complex topics.
Create tidy code snippets or examples that will help users get it right.

Tone and voice

Take a friendly but casual tone, like you are explaining things to a peer or colleague.
Don’t waffle on too much with preamble, get to the point.
Speak with clarity and confidence. You know what you’re talking about.

How to contribute to the Kinde docs

Edit an existing article

Navigate to the doc in your browser and select Edit page at the bottom. GitHub opens.
Make the required changes and then Commit.
Provide clear and direct notes about your changes.
Submit a PR. See below.

Create a new document

Navigate to the folder of the section and subsection the topic will go.
Select New file.
Type the name of the file in the blank field and add .mdx.
Add the required frontmatter of the topic (title and page_id). See the Docs syntax topic below.
Add content and commit.

Explain the reason for the topic as part of the PR.

File structure in GitHub

Our documentation articles are written in mdx and are structured as follows:

Directorysrc
- Directorycontent
  - Directorydocs
    Directorytopic group
    Directorysubtopic group
    article-1.mdx
    article-2.mdx

Raise a PR

When you’re ready to raise a PR, use the following naming conventions: feat:[description] for new topics or substantial changes fix:[description] for corrections and minor changes This helps us recognize and prioritize requests.

Docs syntax

This section describes some of our styles, elements, and conventions for docs content.

Frontmatter

The header/metadata part of the content helps the article appearing correctly in docs. It is also important for external AI tools and search optimization.

Copy the whole example below into the top of any new topic. And complete the required sections. Complete optional sections if you want.

---
page_id:
title:
description: "description"
sidebar:
  order:
tableOfContents:
  maxHeadingLevel: 3
relatedArticles:
  -
  -
app_context:
  - m:
    s:
topics:
  -
  -
  -
sdk: []
languages: []
audience:
complexity:
keywords:
  -
  -
  -
  -
  -
updated: yyyy-mm-dd
ai_summary:
---

Required Fields

page_id (uuid) - This is the internal unique id for the article. This will be used when referencing other articles within the relatedArticles frontmatter. You can use our online UUID generator tool to use as the page_id.

title (string) - You must provide a title for every page. This will be displayed at the top of the page, in browser tabs, and in page metadata.

description (string) - A brief description of the article content, used for SEO and metadata.

keywords (array) - Array of keywords for search optimization.

Optional Fields

sidebar

order (number) - Control the order of this article when sorting an autogenerated group of links under a specific topic or subtopic. Lower numbers are displayed higher up in the link group. Providing the order frontmatter is completely optional and will be treated as a hint for us to where to place the file. We may update the article’s order upon further review.
label (string) - The label of the article when displayed in the sidebar. Falls back to title if not provided.

topics (array) - Array of topic tags that help categorize the content.

sdk (array) - Array of SDKs that are relevant to this article. Use [] for no SDKs or null for not applicable.

languages (array) - Array of programming languages covered in the article.

ai_summary (string) - A full paragraph summary of the article content for AI processing and search (around 200 words). Falls back to description if not provided.

relatedArticles (array) - Array of page IDs for related articles that should be displayed at the bottom of the page.

app_context - Map doc item to the Kinde dashboard menu item and submenu items.

m (string) - The top level menu item
s (string) - The submenu item

How it looks in the dashboard:

In Kinde dashboard, they will appear in the “Help” menu popup under the Suggested for you section.

help menu suggested for you

How to add them:

Log in to your Kinde dashboard and navigate to the appropriate setting page. You will find them within the navigation URL of each page.

App context in the url

Example:

app_context:
  - m: releases
    s: feature_flags

Code samples

The code snippets in our docs are powered by astro-expressive-code. Here are some examples in how you can use them:

Regular syntax highlighting

For code highlighting, you will need a language identifier. (See full list of supported languages on GitHub)

e.g. js for JavaScript:

```js
console.log("This code is syntax highlighted!");
```

Will render:

console.log("This code is syntax highlighted!");

Frames

If you use a language identifier that is typically used for terminal sessions or shell scripts, a terminal frame will be added to the rendered output.

```bash
nano script.sh
```

Will render:

nano script.sh

If you add a value for title, then you get a title bar:

```powershell title="PowerShell terminal example
Write-Output "This one has a title!
```

Result:

Write-Output "This one has a title!

If the language identifier is not a terminal session or shell script one, providing the title attribute will render the frame with the file name, for example.

```tsx title="src/app/page.tsx
import { RegisterLink, LoginLink } from "@kinde-oss/kinde-auth-nextjs/components";
```

Output:

import {RegisterLink, LoginLink} from "@kinde-oss/kinde-auth-nextjs/components";

This can also been achieved by adding a comment with the file name at the top of your file.

```tsx
// src/app/page.tsx
import { RegisterLink, LoginLink } from "@kinde-oss/kinde-auth-nextjs/components
```

Output:

import {RegisterLink, LoginLink} from "@kinde-oss/kinde-auth-nextjs/components";

Images

Use images sparingly, to support complex or detailed procedures. For accessibility, do not use images instead of text. Always include alt-text.

If you need an image or screen shot in your article, you’ll have to:

Create a folder within src/assets/images with the same slug as your article (the article’s .mdx file name)
The image must be at least 1440px wide
Include alt text in the markdown.

Images are optimized before publishing, and have styles and zoom functionality added.

For example, this article lives under src/docs/contribute/index.mdx - In this case, we would create a contribute folder under src/assets/images and save the image there.

Directorysrc
- Directoryassets
  - Directoryimages
    Directorycontribute
    penguin.jpg

To add an image to an article, just simply use the markdown syntax like so:

![An image of a penguin](@assets/images/contribute/penguin.jpg)

The image will be rendered with some padding and will have the click to zoom functionality added to it.

An image of a penguin

Component reference

See below a list of the components ready to use. This list is constantly being updated.

`<PackageManagers>`

This component combines multiple useful commands from different package managers in the node ecosystem. It generates commands for npm, yarn, pnpm and bun.

Properties

type (string) - The type of command to be executed. (e.g., add, create, dlx, exec, run, remove). Defaults to add if not specified.
pkg (string) - The package to be installed. (e.g., firebase)
args (string) - The arguments to be passed to the command. (e.g., -e with-supabase)
dev (boolean) - Whether to install the package as a dev dependency. Defaults to false if not specified. (e.g., <PackageManagers pkg="dotenv" dev={true} />). You can also use dev as a shorthand: <PackageManagers pkg="dotenv" dev />.

Install a dependency

Syntax

<PackageManagers pkg="@kinde-oss/kinde-auth-nextjs" />

Output

npm i @kinde-oss/kinde-auth-nextjs

pnpm add @kinde-oss/kinde-auth-nextjs

yarn add @kinde-oss/kinde-auth-nextjs

bun add @kinde-oss/kinde-auth-nextjs

To add multiple packages, separate them with spaces:

<PackageManagers pkg="prisma firebase" />

Install a dev dependency

Syntax

<PackageManagers pkg="dotenv" dev />

Output

npm i -D dotenv

pnpm add -D dotenv

yarn add -D dotenv

bun add -d dotenv

Run a command

We can output the npm run dev command equivalent with this hack:

<PackageManagers pkg="dev" type="run" />

Output

npm run dev

pnpm run dev

yarn run dev

bun run dev

Execute a command (npx)

<PackageManagers pkg="prisma" type="dlx" args="studio" />

Output

npx prisma studio

pnpm dlx prisma studio

yarn dlx prisma studio

bunx prisma studio

Complex command with args

<PackageManagers type='dlx' pkg='create-next-app' args='-e with-supabase' />

Output

npx create-next-app -e with-supabase

pnpm dlx create-next-app -e with-supabase

yarn dlx create-next-app -e with-supabase

bunx create-next-app -e with-supabase

`<Aside>`

This component is useful for displaying secondary information alongside a page’s main content.

Properties

type (string) - The type of aside to be displayed. (e.g., info, warning, danger, upgrade). Defaults to info if not specified.
title (string) - The title of the aside. Defaults to null if not specified.

Example usage

Syntax

<Aside>
This is a helpful message for the user.
</Aside>

Output

Example with title

Syntax

<Aside title="Heads up!">
This is a helpful message for the user.
</Aside>

Output

Warning

Warn about potential pitfalls or things to avoid.

Syntax

<Aside type="warning">
Don't commit CLIENT_SECRET to source control!
</Aside>

Output

Upgrade

Inform about features that are only available on paid plans in Kinde.

Syntax

<Aside type="upgrade">
Google Analytics is available on the Kinde Pro plan and above.
</Aside>

Output

`<FileTree>`

Use the <FileTree> component to display the structure of a directory with file icons and collapsible subdirectories.

Content

The component has no props. Pass a nested markdown list as children: top-level items are files or folders at the project root, and each nested list under an item represents that folder’s contents. Indent with two spaces per level.

Simple tree

Syntax

<FileTree>

- .env.local
- src
  - app
    - page.tsx

</FileTree>

Output

.env.local
Directorysrc
- Directoryapp
  - page.tsx

Nested folders

Syntax

<FileTree>

- src
  - app
    - layout.tsx
    - page.tsx
    - dashboard
      - page.tsx
- next.config.ts
- .env.local

</FileTree>

Output

Directorysrc
- Directoryapp
  - layout.tsx
  - page.tsx
  - Directorydashboard
    page.tsx
next.config.ts
.env.local

`<YoutubeVideo>`

Embed a YouTube video using lite-youtube behind the scenes for faster loading than a full iframe embed.

Properties

videoId (string, required) - The YouTube video ID from the watch URL (the value after v=).
videoTitle (string, optional) - Accessible label for the embed. Defaults to "Video" when omitted.

Basic embed

Syntax

<YoutubeVideo videoId="ybmHcAVBnec" />

Output

With a custom title

Syntax

<YoutubeVideo videoId="ybmHcAVBnec" videoTitle="Kinde walkthrough" />

Output

`<Tabs>` and `<TabItem>`

Use <Tabs> as the wrapper and one or more <TabItem> children to group equivalent content so the reader can switch between variants (languages, stacks, or paths) without scrolling past every option.

Properties

<Tabs>

syncKey (string, optional) - When the same key is set on multiple <Tabs> groups, changing a tab in one group switches the others to the tab with the same label (state is stored in localStorage, so it can persist when navigating Starlight pages that use the same key).

<TabItem>

label (string, required) - The text shown on the tab control.
icon (string, optional) - A Starlight icon name to show beside the label.

Basic tabs

Syntax

<Tabs>
  <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem>
  <TabItem label="Moons">Io, Europa, Ganymede</TabItem>
</Tabs>

Output

Stars
Moons

Sirius, Vega, Betelgeuse

Tabs with code samples

Syntax

<Tabs>

  <TabItem label="JavaScript">

```js
console.log("hello world!");
```

  </TabItem>

  <TabItem label="PHP">

```php
echo "hello world";
```

  </TabItem>

</Tabs>

Output

JavaScript
PHP

console.log("hello world!");

echo "hello world";

Synchronized tab groups

Give two or more <Tabs> blocks the same syncKey so they stay on the same logical tab when the reader changes selection (tab labels must match across groups).

Syntax

<Tabs syncKey="contribute-guide-sync-demo">
  <TabItem label="JavaScript">Use `npm install`.</TabItem>
  <TabItem label="PHP">Use `composer require`.</TabItem>
</Tabs>

<Tabs syncKey="contribute-guide-sync-demo">
  <TabItem label="JavaScript">Second group follows the first.</TabItem>
  <TabItem label="PHP">Second group follows the first.</TabItem>
</Tabs>

Output

JavaScript
PHP

Use npm install.

Use composer require.

JavaScript
PHP

Second group follows the first.

Join the community

Get support from the Kinde team and expert users in the Kinde community

Join via Slack or Discord
Contact support

Chat to support through the Kinde help widget, or send a question via email

Send an email

Contribution guide

What to contribute

Ways to contribute

Raise an issue

Suggest a single page edit

Raise a PR for bigger contributions

Contributing to SDK documentation

General document structure

How we write

Writing principles

Content principles

Tone and voice

How to contribute to the Kinde docs

Edit an existing article

Create a new document

File structure in GitHub

Raise a PR

Docs syntax

Frontmatter

Required Fields

Optional Fields

Code samples

Regular syntax highlighting

Frames

Images

Component reference

<PackageManagers>

Properties

Install a dependency

Install a dev dependency

Run a command

Execute a command (npx)

Complex command with args

<Aside>

Properties

Example usage

Example with title

Warning

Upgrade

<FileTree>

Content

Simple tree

Nested folders

<YoutubeVideo>

Properties

Basic embed

With a custom title

<Tabs> and <TabItem>

Properties

Basic tabs

Tabs with code samples

Synchronized tab groups

Useful links

Join the community

Contact support

`<PackageManagers>`

`<Aside>`

`<FileTree>`

`<YoutubeVideo>`

`<Tabs>` and `<TabItem>`