The Ory documentation
Ory documentation is the single source of truth for usage, implementation, configuration, and troubleshooting of the Ory Network and all projects of the Ory Ecosystem. The documentation is best consumed through the Ory documentation portal.
To see the source code of each of the projects, visit the project repository:
Documentation of other Ory projects:
This style guide outlines the most important rules and conventions that apply to the Ory documentation. If there are no Ory-specific requirements or guidelines for a given topic, refer to the Microsoft Writing Style Guide and follow the rules described there.
Ory documentation must be clear, concise, and unambiguous. To achieve that, follow these simple rules:
e.g
or i.e
.a
, an
, the
) in your writing.aren't
, don't
, doesn't
to sound
friendly and informal.Ory follows the Microsoft Writing Style Guide list formatting guidelines.
`
).,
), semicolons (;
), or conjunctions
(and
, or
) at the end of list items..
) only at the end of list items that are proper sentences,
even very short ones.h2
. Use h1
only when you
override the document title
.h4
. If you absolutely need to add
more heading levels, don't go lower than h5
.Write in Markdown. Don't mix HTML tags with
Markdown. Files with the .mdx
extension use
JSX-extended Markdown (MDX).
Add this front matter to every document you create:
---
id: excellent_feature
title: Learn how to use the excellent feature in your implementation
sidebar_label: Excellent feature
slug: excellent-feature-for-some-reason
---
id
is the document identifier that makes up the last part of the document
URL. Try to come up with a short ID that accurately describes the content. IDs
that use multiple words must use hyphens (-
) to separate the words.title
is the document title that’s displayed as the page header. Used by
search engines when displaying search results. Try to make it descriptive so
that it helps readers understand what the document is about at the first
glance. If it comes out long(ish), you can overwrite it by adding a h1
in
the very first line following the front matter. Use sentence case.sidebar_label
represents the document title used in the sidebar (left
navigation). Create a short document title that fits the sidebar width. Use
sentence case.slug
is an optional property that allows you to customize the document URL.
Use it to create more meaningful, SEO-friendly URLs.code
and bold formatting. Don't use any other formatting.`
). For code blocks use
three backticks (```
)code
formatting for:
ory --help
file.txt
, ~/Desktop/git/docs
CUSTOM_ENV_VAR
Link to external web pages using absolute links. Don't expose the link on its own. Instead, embed it in descriptive text. For example:
Ory documentation uses [Prism syntax highlighting](https://prismjs.com/).
Link to documents within this repository using relative links. When referencing the file, use the file name.
[Some link](../path/to/file.mdx)
Always add a programming language identifier to code blocks. Ory documentation uses Prism syntax highlighting.
```json
{some-JSON-code-here}
```
For command line examples, use shell
as the programming language identifier.
Don't put $
before the command.
```shell
ory get identities
```
For Ory Permissions (Keto) relation tuples, use keto-relation-tuples
language identifier, and for relationships use keto-relationships
.
```keto-relation-tuples
namespace:object#relation:subject
// comment
```
```keto-relationships
namespace:subject is relation of object
is namespace:subject allowed to permission on object?
// comment
```
For multi-line commands, indent subsequent lines of the command with two spaces.
```shell
curl --request GET -sL \
--header "Content-Type: application/json" \
--header "Authorization: Bearer {ORY_API_KEY}" \
'https://{project-slug}.projects.oryapis.com/admin/identities/{identity_id}?include_credential=oidc'
```
Using placeholders and dummy data in code snippets and command examples is a good way to ensure that users run commands in the context of their setups and, as a result, achieve success faster. Additionally, this fabricated information prevents leaking of sensitive data such as tokens or API keys.
Follow these rules when using placeholders and dummy data:
{}
).-
) or underscores (_
) to separate multiple words, for example
{ORY_SESSION_COOKIE}
or {project-slug}
.https://{project.slug}.projects.oryapis.com
.https://ory.your-custom-domain.com
.When talking about any user interface (UI) in the Ory documentation, follow these rules:
code
.Example: In the Identity Model Schema box, type
MyCustomIdentitySchema
.
Use Mermaid to create diagrams. You can run the tool locally or use Mermaid Live Editor in the browser. See the Mermaid Cheatsheet for a detailed description on how to use Mermaid.
To add a Mermaid diagram, use this mdx-code-block
:
```mdx-code-block
import Mermaid from "@site/src/theme/Mermaid"
<Mermaid
chart={`
{your-Mermaid-code}
`}
/>
```
If a certain piece of content must be re-used across multiple documents in the exact form, it's a good idea to turn it into a partial. Thanks to that, you maintain content in a single file, instead of multiple instances of the same content in many docs.
Add partials to the _common
directory.
To import a partial, use this mdx-code-block
:
```mdx-code-block
import ExamplePartial from './_common/example.md'
<ExamplePartial />
```
TIP: Headings contained in partials aren't added to the Docusaurus table of contents (ToC). To make sure users can access all headings through the ToC, don't add headings to partials. Instead, add appropriate headings to the document manually and introduce partials after them. To see an implementation of this approach, look at this file.
Use CodeFromRemote to import code directly from GitHub.
Use this mdx-code-block
:
```mdx-code-block
import CodeFromRemote from '@theme/CodeFromRemote'
<CodeFromRemote
lang="js"
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"
startAt="{CONTENT_FROM_CODE}"
endAt="{CONTENT_FROM_CODE}"
/>
```
lang
specifies the programming language the code is inlink
is the file location displayed in the top part of the code block windowsrc
is the direct link used to import the code (optional)startAt
, endAt
are used to define where the imported snippet starts and
ends (optional)```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>
```
_static
folders.
_static
directory, each document that uses media has its own
directory.1.png
, 2.png
, 3.png
. The filenames should reflect the stage
at which the media is used in the document. This means that the screenshot
named 1.png
will be used in line 70, while the diagram 2.svg
will be
used in line 100.Compress images you add to the documentation to keep the repository lean. You
can use pngquant
.
Read this article to learn a trick to make your screenshots 80% smaller.
We recommend using Quicktime to record videos. Follow these rules:
ffmpeg
will scale it to
the right size.After recording the video, convert the .mov
file 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
Use this mdx-code-block
to add the video to your document:
```mdx-code-block
import mp4 from './_static/screencast.mp4'
import webm from './_static/screencast.webm'
import VideoEmbed from '@site/src/components/VideoEmbed'
<VideoEmbed mp4={mp4} webm={webm} />
```
When referring to specific pages within Ory Console in the documentation, you
can use the /current/
route to navigate users to their currently active Ory
Network project. For example, to access the Custom UI settings for the currently
active Ory Network project in the Console, you can link to:
https://console.ory.sh/projects/current/ui
Using the /current/
route you can dynamically direct users to the relevant
sections based on their project context.
To test the documentation locally:
npm install
to install all
dependencies.npm run start
.npm run build
.All documents and other files in this repository must be formatted with Prettier using the Ory Prettier styles.
To format all relevant files, run these commands from the main directory of the repository:
make format
git commit -a -m "chore: format"
git push
For a better workflow, install the Prettier plugin for your editor:
The Quickstart overview provides an overview of Ory quickstarts. To add a new example or modify existing entries:
Open examples-content.tsx
in src/pages/_assets/
.
Copy the following snippet and append it to 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, vueOpen a pull request with your changes.
Ory documentation contains auto-generated content such as CLI and API references. Documents of this type are generated from source code and are pushed to this repository by an automated job.
As such, editing any of these documents in the Ory documentation repository isn't the way to change or fix this content. Any changes you make will be overwritten by the next push that follows the generation process.
Instead, find the lines in question in the source code of the Ory projects and edit them there. For example, if you want to edit the documentation of the Ory Kratos CLI, you must edit this file:
https://github.com/ory/kratos/blob/master/cmd/clidoc/main.go
The 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