8f82dac84e
* draft style guide * broken links * rename partial file * added content to style guide, more links * sidebar and link * polish * typo * forgot to save * kens formatting trick * typo * Jens' edits * tweak * simplify formatting for variables * edits from 4d62 * fixed link * more edits * tweak re formatting command * tweak re formatting command --------- Co-authored-by: Tana M Berry <tana@goauthentik.com>
40 lines
1.9 KiB
Markdown
40 lines
1.9 KiB
Markdown
---
|
|
title: "Reference topic"
|
|
---
|
|
|
|
:::info
|
|
**How to use this template**: start with the markdown version of the template, either by copying the [`reference.tmpl.md`](https://github.com/goauthentik/authentik/tree/main/website/developer-docs/docs/templates) file from our GitHub repo or downloading the template file using the following command:
|
|
|
|
```
|
|
wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/templates/reference.tmpl.md
|
|
```
|
|
|
|
Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [General Guidelines](../writing-documentation#writing-guidelines) for writing tips and authentik-specific rules.
|
|
:::
|
|
|
|
Create a title that specifies the component you are documenting. For example, "Group attributes".
|
|
|
|
Provide a sentence or two about the topic.
|
|
|
|
Reference documentation provides details, values, syntax, etc., about specific programming elements.
|
|
|
|
The most common type of reference documentation is for REST APIs; the request syntax, a successful response, any parameters such as query, header, or request body parameters, and possible http status codes.
|
|
|
|
Other types of reference content include lists of functions, parameters, object properties, event actions, and attributes.
|
|
|
|
## Head 2
|
|
|
|
Use a title that is descriptive, such as "User object attributes" or "Expression policy functions".
|
|
|
|
Use tables, bullet lists, Head3s... whatever you need to clearly present the values.
|
|
|
|
Be sure to use a sentence after every heading, to explain what the section is about, how the values are used, etc.
|
|
|
|
### Head 3 (optional, if needed)
|
|
|
|
Add a sentence explaining the following grouping.
|
|
|
|
### Head 3 (optional, if needed)
|
|
|
|
Add a sentence explaining the following grouping.
|