search

ory / docs

The Ory documentation
https://www.ory.sh/docs
Apache License 2.0
136 stars 379 forks source link
docs documentation hacktoberfest ory

readme

Ory Documentation

Chat | Newsletter

Documentation | Support this project!

Work in Open Source, Ory is hiring!

Overview

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:

Style guide

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.

Grammar and style

Ory documentation must be clear, concise, and unambiguous. To achieve that, follow these simple rules:

  1. Use active voice and present tense.
  2. Always write in American English.
  3. Use zero conditional when talking about the cause-and-effect in software behavior.
  4. Use the right words to make sure that your message is clear and unambiguous. Don't use words like "should", "could", or "may".
  5. Don't use phrasal verbs, colloquialisms, and jargon.
  6. Don't refer to users in ways that imply their sex.
  7. Don't use contractions of Latin origins such as e.g or i.e.
  8. Remember to use articles (a, an, the) in your writing.
  9. Use common contractions such as aren't, don't, doesn't to sound friendly and informal.

Lists

Ory follows the Microsoft Writing Style Guide list formatting guidelines.

Headings

Formatting

Write in Markdown. Don't mix HTML tags with Markdown. Files with the .mdx extension use JSX-extended Markdown (MDX).

Document front matter

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
---

Bolding, 'code formatting'

Linking

Code blocks

Placeholders and dummy data

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:

UI references

When talking about any user interface (UI) in the Ory documentation, follow these rules:

Example: In the Identity Model Schema box, type MyCustomIdentitySchema.

Diagrams

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}

`}
/>

## Import & reference content

### Markdown partials

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`:

````md
```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](https://github.com/ory/docs/blob/0137302d511b2a6b0e17a570e917d92fcdff1d1f/docs/kratos/social-signin/10_google.mdx?plain=1#L237).

### Code snippets

#### From GitHub

Use
[CodeFromRemote](https://github.com/ory/docusaurus-template/blob/master/src/theme/CodeFromRemote.js)
to import code directly from GitHub.

Use this `mdx-code-block`:

````md
```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 in
- `link` is the file location displayed in the top part of the code block window
- `src` is the direct link used to import the code (optional)
- `startAt` , `endAt` are used to define where the imported snippet starts and
  ends (optional)

#### From this repository

````md
```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>

## Screenshots and videos

- Use screenshots and videos sparingly. These resources tend to get out-of-date
  quickly and are cumbersome to maintain.
- Screenshots and videos must capture only the relevant parts of the screen.
- Screenshots and videos must capture UI elements in English. If you’re
  capturing parts of the browser UI in your work, make sure the UI is in
  English.
- Make an effort to get the screenshots and videos looking as clean as possible.
  Avoid situations where text fields suggest irrelevant inputs, avoid erratic
  mouse cursor movements and general chaos.
- You must add media to `_static` folders.
  - In the `_static` directory, each document that uses media has its own
    directory.
  - In the directory of the document, the files have numbers for names, for
    example, `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.

### Compressing images

Compress images you add to the documentation to keep the repository lean. You
can use [`pngquant`](https://pngquant.org/).
[Read this article to learn a trick to make your screenshots 80% smaller](https://about.gitlab.com/blog/2020/01/30/simple-trick-for-smaller-screenshots/).

### Recording and compressing videos

We recommend using
[Quicktime to record videos](https://support.apple.com/en-gb/guide/quicktime-player/qtp97b08e666/mac).
Follow these rules:

- Use 16:9 format with at least 1024 pixels of width. `ffmpeg` will scale it to
  the right size.
- Make sure that no history or auto-suggestions are visible.

After recording the video, convert the `.mov` file to `mp4` and `webm`:

```shellsession
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} />

## Ory Console

### Navigate to Ory Console Pages

You can use the `/current/` route to navigate users to their active Ory Network
project. For example, to access the Custom UI settings for the active Ory
Network project in the Console, you can link to:
https://console.ory.sh/projects/current/ui

When referencing a page of the Ory Console, use the
`<ConsoleLink route="project..." />` component in MDX files.

The component resolves the navigation section and page title for the given
route, and renders a standard markup for both, as well as the link with the
`/current/` shortcut mentioned above:

```tsx
<ConsoleLink route="project.activity.events" />

// becomes:
// Activity → Logs & Events in the [Ory Console](https://console.ory.sh/current/projects/activity/events)

A list of all supported routes can be found here: src/components/ConsoleLink/console-routes.ts.

Please note that the syntax is like accessing a path in a JS object, but as a string. If the route you want to reference is found in the console-routes.ts file in the following way:

{
  project: {
    activity: {
      events: {
        route: "/projects/[project]/activity/events",
      }
    }
  }
}

Use <ConsoleLink route="project.activity.events" /> to reference it.

To add a new route, you need to add an entry in console-routes.ts as well as console-nav-data.ts.

Testing

To test the documentation locally:

  1. Clone this repository.
  2. Navigate to the cloned repository and run npm install to install all dependencies.
  3. Run the development server and test the changes you made using a fully operational version of the documentation portal that runs on your machine. Run npm run start.
  4. Create a production build to check for any technical issues, such as invalid internal links. Run npm run build.

Formatting documentation

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:

Adding content to "Examples" page

The Quickstart overview provides an overview of Ory quickstarts. To add a new example or modify existing entries:

  1. Open examples-content.tsx in src/pages/_assets/.

  2. 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, vue

  3. Open a pull request with your changes.

CLI and API reference - auto-generated content

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