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 is critical to the article appearing correctly in docs.

`title (required)`

type: 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.

---
title: Kinde SDKs
---

`page_id (required)`

type: 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: Kinde SDKs
page_id: 684fc526-a338-4a67-9af6-742a39b66aff
---

`order` (optional)

type: 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.

---
title: Kinde SDKs
page_id: 684fc526-a338-4a67-9af6-742a39b66aff
sidebar:
  order: 1
---

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

Components

`PackageManagers`

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

`pkg` (required)

string — The package to be installed. For example: @kinde-oss/kinde-auth-nextjs

`type` (optional)

add create exec run remove

default: add

Example

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

Result

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

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

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

`Aside`

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

`type` (optional)

info warning danger upgrade

default: info

`title` (optional)

string

default: null

Example with title

<Aside type="warning" title="Attention">

This is the message

</Aside>

Result

Example without a title and a type (defaults to the `info` variant)

<Aside>

This is the message

</Aside>

Result

`FileTree`

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

Example

<FileTree>

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

</FileTree>

Result

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

`YoutubeVideo`

This will embed a YouTube video using lite-youtube behind the scenes.

`videoId` (required)

The YouTube video id.

string

`videoTitle` (optional)

The video title.

string

default: "Video"

Example

<YoutubeVideo videoId="ybmHcAVBnec" />

Result

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

title (required)

page_id (required)

order (optional)

Code samples

Regular syntax highlighting

Frames

Images

Components

PackageManagers

pkg (required)

type (optional)

Example

Result

Aside

type (optional)

title (optional)

Example with title

Result

Example without a title and a type (defaults to the info variant)

Result

FileTree

Example

Result

YoutubeVideo

videoId (required)

videoTitle (optional)

Example

Result

Useful links

Join the community

Contact support

`title (required)`

`page_id (required)`

`order` (optional)

`PackageManagers`

`pkg` (required)

`type` (optional)

`Aside`

`type` (optional)

`title` (optional)

Example without a title and a type (defaults to the `info` variant)

`FileTree`

`YoutubeVideo`

`videoId` (required)

`videoTitle` (optional)