Documentation
This repository contains meta-documentation for the
ORY Ecosystem.
You can find the source files for each projects documentation here:
Other Ory Projects documentation:
Contributing Documentation
Documentation for
the Ory Ecosystem lives in
ory/docs.
Documentation for the individual projects live in their respective docs
folder. (Ory Hydra,
Ory Kratos,
Ory Oathkeeper,
Ory Keto)
If you make changes, please consider making the same changes in the lastest
version of /versioned_docs
To test the documentation locally:
Change into the /docs
folder in your local git environment.
Install dependencies npm install
Test build the documentation:
npm start # test if everything works
To build the docs:
npm run build
Formatting documentation
All documentation (as well as any other files) must be formatted using Ory's prettier styles
To format all for documentation relevant files simply run the following command from the repositories main directory:
cd docs
npm install
npm run format
git commit -a -m "styles: format"
git push
Categories
Ory Documentations is structured into several main categories.
Each of those categories serves a specific purpose.
The purpose of each category is outline in short here, to help find the correct category for your documentation to live in.
- Introduction
- The purpose of this category is to introduce the very
basics
of the project and give newcomers a easy way to start. Contains the most basic explanation of the project, an installation guide, a Quickstart/5-Minute Tutorial and Contribution Guidelines.
- The purpose of this category is to introduce the very
- 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 toexplain
.
- The purpose of this category is to give the reader a deep
- 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 is aimed towards more experienced users, who are already familiar with the concepts and tools.
- The purpose of this category is to solve a specific problem. It has the form of a
- Reference
- The purpose of this category is to provide detailed & in-depth description of the project . It has the form of a
austere and to the point explanation
and is rooted in code, most often these documents are built directly from code without editor interaction. It does not give information on how to do specific things, but describes how to correctly use the APIs ect.
- The purpose of this category is to provide detailed & in-depth description of the project . It has the form of a
- SDK
- Same as the above category but for SDKs, also containing simple guides for using SDKs.
Document Structure
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
---
How to add links to other pages
If you would add a link to an outside ressource, just go ahead.
If you want to add a link to a document in our own documentation, please make sure to add the filename.
For example [XY Guide](./guide/XY.md)
rather than [XY Guide](./guide/XY)
.
This prevents broken links (issue) when you load the documentation from an outside link.
How to add code 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"
/>
CLI Docs
Fixing Ory CLI docs
If you find an error in the Ory CLI documentation here are some pointer 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