/ory-docs

Documentation for all ORY products

Primary LanguageJavaScriptApache License 2.0Apache-2.0

Ory Documentation

Chat | Newsletter

Documentation | Support this project!

Work in Open Source, Ory is hiring!

Ory Documentation

Documentation is the single source of truth

The Ory documentation is the place to find all information related to Ory services, usage and troubleshooting.

This repository contains meta-documentation for the Ory Ecosystem. You can find the source code for each project here:

Other Ory Projects documentation:

Style

Categories

The Ory Developer documentation can be organized in three different main categories:

  • Concepts
    • The purpose of this category is to give the reader a deep understanding of the ideas upon which the project is built. Content in this category has the form of a discursive explanation. The main goal is to explain.
  • Guides
    • The purpose of this category is to solve a specific problem. It has the form of a series of steps towards a goal. It's aimed towards more experienced users, who are already familiar with the concepts and tools
  • Reference
    • The purpose of this category is to provide a detailed & in-depth description of the project. It has the form of an austere and to the point explanation and is rooted in code, most often these documents are built directly from code without editor interaction. It doesn't give information on how to do specific things.

There are also sub-types:

  • Introduction
    • The purpose of this guide is to introduce the very basics of the project and give newcomers an easy way to start. Contains the most basic explanation of the project, an installation guide or a Quickstart/5-Minute Tutorial.
  • Troubleshooting
    • Contains instructions on how to resolve issues with Ory services.

Document frontmatter

Add a meaningful title and an ID to the top of the document. id needs to be separated with - and lowercase, title with space and Uppercase. Example:

---
id: documentation-id
title: Documentation Title
---

Text

Ory documentation should be clear and easy to understand.

  • Avoid unnecessary words.
  • Be clear, concise, and stick to the goal of the topic.
  • Write in US English with US grammar.
  • Use articles such as a/an and the wherever possible.
  • Use active voice.
  • Avoid slang and jargon, while allowing for specific terminology.

Headings

  • Use sentence case for headings.
  • Start with an h2 (##), and respect the order h2 > h3 > h4 > h5 > h6. Never skip the hierarchy level, such as h2 > h4
  • Avoid using symbols and special characters in headers. Whenever possible, they should be plain and short text.
  • Leave one blank line before and after a heading.
  • Don't use links in headings.
  • Search engines prioritize words used in headings and subheadings. Make your subheading titles clear, descriptive, and complete to help users find the right example, as shown in the section on heading titles.
Headings capitalization

Names for console UI elements

Lists

  • Always start list items with a capital letter, unless they're parameters or commands that are in backticks, or similar.
  • Always leave a blank line before and after a list.
  • Begin a line with spaces (not tabs) to denote a nested sub-item.
  • Indent all code blocks in lists so that they are formatted to be part of list items.

Testing

Playwright tests

The Playwright (E2E) tests file names end with .spec.ts and can be found in /tests/playwright. Node.js is required to run Playright tests locally. To test the documentation locally:

  1. Clone this repository.
  2. Enter the /docs folder in your local git environment.
  3. Install dependencies by running: npm install.
  4. Run the Docs webserver and test the documentation by running: npm start
  5. Build the docs and verify by running: npm run build

Jest tests

The Playwright (E2E) tests file names end with .test.ts and can be found in /tests/jest.

Formatting documentation

All documents and other files in this repository must be formatted with Prettier using the Ory Prettier styles.

The recommended way to achieve this is installing the Prettier plugin for your editor:

To format all relevant files, run these commands from the main directory of the repository:

npm install
npm run format
git commit -a -m "styles: format"
git push

Markdownlint

Locally:

  1. Download and install the markdownlint CLI. brew install markdownlint-cli
  2. Check if markdownlint installed. `markdownlint --help``
  3. Lint all files in the project, in the docs folder use cd docs markdownlint '**/*.md' --ignore node_modules
  4. Fix all files in the project, Warning: This writes to your files! cd docs markdownlint './docs/**/*.+(md|mdx)' --ignore node_modules --fix

How to...

Add content to Examples page

The Examples page provides an overview of Ory examples. Add a new example or modify existing entries:

  • Open examples-content.tsx under the path docs/src/pages/_assets/
  • Copy the following snippet and append it in the correct array (either official, community or self-hosting examples):
{
      title: 'Protect a Page with Login: NextJs/React', //Your example title goes here
      language: 'typescript',                           //The main programming language of your example
      author: 'ory',                                    //The author's GitHub handle
      tested: true,                                     //Is the example in ory/examples or ory/docs and has automated tests?
      repo: 'https://github.com/ory/docs/tree/master/code-examples/protect-page-login/nextjs', //The repo containing the example code
      docs: 'https://www.ory.sh/docs/guides/protect-page-login/next.js'                        //Documentation for the example, can be README, blog article or similar
    },

  • language can be one of: dart, django, docker, erlang, flutter, go, java, javascript, kotlin, kubernetes, nextjs, nodejs, ory, php, python, react, rescript, svelte, typescript, vue

  • Open a pull request with your changes.

Links to other pages

If you would add a link to an outside resource, just go ahead.

If you want to add a link to a document in our own documentation, add the filename.

  • ✅ [XY Guide](./guide/XY.md)
  • 🚫 [XY Guide](./guide/XY)

This prevents broken links issue when you load the documentation from an outside link.

Import Markdown

Use the same markdown in several places:

```mdx-code-block
import ExampleMarkdown from './_common/example.md'

<ExampleMarkdown />
```

Code snippets

From Github

Use CodeFromRemote to import code directly from Github.

Import at the beginning of your document like so:

---
id: documentation id
title: Documentation Title
---

import CodeFromRemote from '@theme/CodeFromRemote'

Then at the place you want the code to appear in the document add:

<CodeFromRemote
  lang="js" # the language of the code you want to add e.g. jsx,tsx,ts,go,yaml,yml,js,html,pug
  link="https://github.com/ory/kratos-selfservice-ui-node/blob/master/src/middleware/simple.ts"
  src="https://raw.githubusercontent.com/ory/kratos-selfservice-ui-node/master/src/middleware/simple.ts"

/>

You can use startAt and endAt if you only want to show a part of the code:

<CodeFromRemote
  lang="yml"
  src="https://github.com/gen1us2k/kratos_flask_example/blob/master/docker-compose.yml"
  startAt="postgres-kratos:"
  endAt="postgres-keto:"
/>

From this repository

Use the same code example in several places:

```mdx-code-block
import CodeBlock from '@theme/CodeBlock'
import exampleJs from '!!raw-loader!./code-example.jsx'
import exampleGo from '!!raw-loader!./code-example.go'

<CodeBlock className="language-jsx">{exampleJs}</CodeBlock>
<CodeBlock className="language-go">{exampleGo}</CodeBlock>
```

Code examples in MDX

If you are using MDX and are in, for example, code tabs, use the CodeBlock to nest code items:

```mdx-code-block
import CodeBlock from '@theme/CodeBlock'

<Tabs
  defaultValue="ui"
  values={[
    {label: 'UI', value: 'ui'},
  ]}>
  <TabItem value="ui">
    <CodeBlock className="language-jsx">{`Your

code

here`}</CodeBlock>
  </TabItem>
  <TabItem value="node">
    <CodeFromRemote
      src="https://github.com/ory/hydra-login-consent-node/blob/master/src/routes/consent.ts"
    />
  </TabItem>
  <TabItem value="html">
    <CodeFromRemote
      src="https://github.com/ory/hydra-login-consent-node/blob/master/views/consent.pug"
    />
  </TabItem>
</Tabs>
```

Shell examples

Use shellsession:

```shellsession
npx create-next-app@latest --typescript
npm i --save @ory/integrations
```

Please do not prefixes with $

- $ command --arg # do not
+ command --arg # do

Images

Add images directly with an img tag:

<img
  alt="Image description which will be the alt tag"
  src="{useBaseUrl('images/some-folder/some-image.png')}"
/>

The useBaseUrl is https://www.ory.sh/ and exposes src/static/..., so all images are stored in src/static/images/....

Compress new images you add to the documentation. One known tool is pngquant. Related article.

  • Don't use lorem ipsum text.
  • Capture only the relevant UI.

Videos

When you record your screen using Quicktime, a .mov file is recorded. Follow these rules:

  1. Please use 16:9 format with at least 1024 pixels wide. ffmpeg will scale it to the right size.
  2. Please make sure that no history or auto-suggestions are visible.

Once recorded, use the commands below to convert them to mp4 and webm:

file="screencast.mov"

ffmpeg -i $file -an -c:v libvpx-vp9 -vf scale=1024:-1 -crf 30 -b:v 0 "${file%.*}".webm
ffmpeg -i $file -vcodec h264 -vf scale=1024:-1 -an "${file%.*}".mp4

Next copy them next to the markdown file you are editing. Then use the following code to display the video:

```mdx-code-block
import mp4 from './screencast.mp4'
import webm from './screencast.webm'
import VideoEmbed from '@site/src/components/VideoEmbed'

<VideoEmbed mp4={mp4} webm={webm} />
```

To embed Youtube videos just copy & paste the link, it's that easy!

CLI documentation

Fixing autogenerated Ory CLI docs

If you find an error in the Ory CLI documentation here are some pointers on how to fix it:

The code that generates the CLI docs (for Kratos) comes from here: https://github.com/ory/kratos/blob/master/cmd/clidoc/main.go

cmd/clidoc/main.go is the general path for all Ory projects.

The command to generate the CLI docs can be found here: https://github.com/ory/x/blob/master/clidoc/generate.go#L96