habsi/authentik
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

website/docs: add more content about flows (#10527)

Browse Source 
* first pass

* reordered config options to match UI, added more

* tweaks

* add content for creating flows, add links to policies, update Style Guide

* tweaks

* procedurals, info about bindings

* stages stub file

* messy

* reorg procedurals

* tweak titles

* tweaks

* images

* images, remove old images

* tweak

* tweaks and fixes

* smaller image

* tweak

* had to rollback

* starting over after VS Code branch war

* fix links

* more tweaks

* Optimised images with calibre/image-actions

* fighting build break

* remove dupe image

* replace image with diagram code

* add image of UI, and reformat to look more like field names, not headings in the document

* Optimised images with calibre/image-actions

* new image

* rest of Jens' edits

* Optimised images with calibre/image-actions

* fix order of stages in example

* fixed arrows in image

---------

Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>
Co-authored-by: Tana M Berry <tana@goauthentik.com>
Co-authored-by: authentik-automation[bot] <135050075+authentik-automation[bot]@users.noreply.github.com>
Co-authored-by: Jens Langhammer <jens@goauthentik.io>
This commit is contained in:
Tana M Berry
2024-08-06 07:56:23 -05:00
committed by GitHub
parent 3d63143c38
commit 34b01d9785
14 changed files with 326 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
website/developer-docs/docs/writing-documentation.md
View File

@ -2,7 +2,21 @@
title: Writing documentation
---
Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project.
Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project. We appreciate contributions to our documentation; everything from fixing a typo to adding additional content to writing a completely new topic.
Adhering to the following guidelines will help us get your PRs merged much easier and faster, with fewer edits needed.
- Ideally, when you are making contributions to the documentation, you should fork and clone our repo, then [build it locally](#set-up-your-local-build), so that you can test the docs and run the required linting and spell checkers before pushing your PR. While you can do much of the writing and editing within the GitHub UI, you cannot run the required linters from the GitHub UI.
- Please refer to our [Style Guide](./style-guide.mdx) for authentik documentation. Here you will learn important guidelines about not capitalizing authentik, how we format our titles and headers, and much more.
- Remember to use our [docs templates](./templates/index.md) when possible; they are already set up to follow our style guidelines, they make it a lot easier for you (no blank page frights!), and keeps the documentation structure and headings consistent.
- To test how the documentation renders you can build locally and then use the Netlify Deploy Preview, especially when using Docusaurus-specific features. You can also run the `make website-watch` command on your local build, to see the rendered pages as you make changes.
- Be sure to run the `make website` command on your local branch, before pushing the PR to the authentik repo. This command does important linting, and the build check in our repo will fail if the linting has not been done.
- For new entries, make sure to add any new pages to the appropriate `sidebar.js` file. Otherwise, the new page will not appear in the table of contents to the left.
## Set up your local build
@ -12,7 +26,7 @@ Requirements:
The docs and the code are in the same Github repo, at https://github.com/goauthentik/authentik, so if you have cloned the repo, you already have the docs.
You can do local builds of the documentation to test your changes or review your new content, and to run the required `prettier` and linters before pushing your PR.
You can do local builds of the documentation to test your changes or review your new content, and to run the required `make website` command (which runs `prettier` and other linters) before pushing your PR.
The documentation site is situated in the `/website` folder of the repo.
@ -28,22 +42,12 @@ The site is built using npm, below are some useful make commands:
- **Live editing**: `make website-watch`
For real time viewing of changes, as you make them.
For real-time viewing of changes, as you make them.
:::info
Be sure to run a formatting command before committing changes.
:::
## Writing guidelines
Please refer to our [Style Guide](./style-guide.mdx) for authentik documentation. Here you will learn important guidelines about not capitalizing authentik, how we format our titles and headers, and much more.
Whenever possible, use one of our [doc templates](./templates/index.md). This makes it a lot easier for you (no blank page frights!) and keeps the documentation consistent.
Make sure to add the new pages to the appropriate place in `/website/sidebars.js`. Otherwise, the content will not appear in the table of contents to the left.
Following the guidelines will make getting your PRs merged much easier and faster, with fewer edits needed. We appreciate our community contributors helping us keep the Docs consistent, easy-to-use, and high quality.
## Documentation for Integrations
In addition to following the [Style Guide](./style-guide.mdx) please review the following guidelines.