<commit_before># Contributing to Auth0 Documentation

:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:

The following is a set of guidelines for contributing to the Auth0 documentation. These are just guidelines, not rules, use your best judgment and feel free to propose changes to this document in a pull request.

## Table of Contents

* [General Guidelines](#general-guidelines)
* [Reusing Content](#reusing-content)
* [Markdown](#markdown)
  * [Headings](#headings)
  * [UI Components](#ui-components)
  * [HTTP Request Snippets](#http-request-snippets)
  * [Escaping Strings](#escaping-strings)
  * [Image zooming](#image-zooming)
  * [Screenshots](#screenshots)
  * [Front Matter](#front-matter)
  * [Linting](#linting)
* [Sidebar](#sidebar)
* [Beta Content](#beta-content)
* [Finishing](#finishing)
* [Editing with Wordy](#editing-with-wordy)
* [Test Procedures](#test-procedures)
* [Review Apps](#review-apps)
* [Quickstarts](#quickstarts)
  * [Creating Quickstarts](#creating-quickstarts)
  * [Versioning Quickstarts](#versioning-quickstarts)
  * [Quickstart Guidelines](#quickstart-guidelines)
  * [Seed Projects](#seed-projects)
* [Updates Feed](#updates-feed)
* [API](#api)
* [Code snippets](#code-snippets)
* [Document Front-matter](#document-front-matter)
* [Document Variables](#document-variables)
  * [Common Variables](#common-variables)
  * [User Specific Variables](#user-specific-variables)
* [Versioning](#versioning)

## General Guidelines

* Read and follow the [Style Guide](STYLEGUIDE.md).
* Consult the [Words](WORDS.md) document for Auth0 specific spellings and definitions.
* Always use relative URLs for internal `auth0.com/docs` links. For example, if the absolute path to the document is `https://auth0.com/docs/identityproviders`, use `/identityproviders`. These links will be correctly formatted in the build process.
* Do not hard code links to Auth0 sites like `docs.auth0.com` or `manage.auth0.com`. Instead, use [Parameter Aliases](#parameter-aliases), such as `${manage_url}`.
* Name files with all lowercase using dashes (-) to separate words. If using a date in the file name, it should be in the format YYYY-MM-DD. For example, `this-is-my-file.md` or `this-is-a-title-2015-10-01.md`.
* Do not store images in external locations like Dropbox, CloudUp, or the Auth0 CDN. Link to images in this repo using a relative path `![ALT_TEXT](/media/folder/image-name.png)`. The image will be uploaded to the CDN and the link will be formatted during the build process. Do not forget to set the alternate text for each image.
* Keep images to no more than 750 pixels wide.
* Screenshots of the Auth0 dashboard including the browser window with dropshadow can be up to 900 pixels wide to maintain legibility.
* Run all images through [TinyPNG](https://tinypng.com/).

## Reusing content

To avoid duplication of content, you can create document fragments to be referenced from other documents. The process of including another document is shown below.

First, create your fragment document. The convention is to name fragments with an underscore, like: `_mydocument.md`.

After you create your markdown document, you can reference it in another document with a relative path:

```markdown
<%= include('../_mydocument.md') %>
```

Additionally, you can send variables to the included document:

```markdown
<%= include('../_mydocument.md', { key: 'value', something: true }) %>
```

## Markdown

Markdown on this site conforms to the [CommonMark](http://commonmark.org/) spec. Additionally, there are a few custom markdown features available as described below.

### Headings

One common mistake with formatting of headings is to not include a space between the hashes and the text. Some markdown processors allow this, but we do not. You must put a space as shown below.

INVALID: `#My Heading`

VALID: `# My Heading`

### UI Components

General advice:
- Don't add custom UI components with HTML unless it's really necessary.
- Don't add any element before the main title. If you want to show some general information for the whole doc put the element after the main title.
- Try to keep the amount of UI components on your docs to a minimum. They make the documentation more difficult to read and cut the reading flow.
- Only use the `blockquote` element (`>` in markdown) to represent actual quotes. Use a `note` or a `panel` if you want to highlight the information.

#### Note

Use this component if you want to display some extra information, links to related content or clarifications.

Only use this if the content is brief (one to four lines), if not use the `panel` component.

```markdown
::: note
  If you need a refresher on the OAuth 2.0 protocol, you can go through our <a href="/protocols/oauth2">OAuth 2.0</a> article.
:::
```

![Note container](https://cloud.githubusercontent.com/assets/6318057/26081072/91318302-399f-11e7-8cf2-57cb55c6ce1d.png)

#### Warning

Use this component if you want to notify that the content is deprecated, there is a security issue or to highlight some **very important** information.

Only use this if the content is brief (one to four lines), if not use the `panel-warning` component. It's recommended to keep the copy of the warnings short and clear.

```markdown
::: warning
Long-lived tokens compromise your security. Following this process is <strong>NOT</strong> recommended.
:::
```

![Warning container](https://cloud.githubusercontent.com/assets/6318057/26081268/6a894af4-39a0-11e7-96bc-6ef69a3be941.png)

#### Panels

Use panels when you want to separate long information from the main body of the document.

Try to add a meaningful title to the panel. Avoid using "NOTE" or "WARNING".

We support two types of panels: **panel** and **panel-warning**.

##### Panel (default)

```markdown
::: panel Title
Description
:::

::: panel Enable APIs Section
If you can't see the [API section](${manage_url}/#/apis) in the left hand menu of the dashboard then you will have to enable it. Navigate to your [Account Advanced Settings](${manage_url}/#/account/advanced), scroll down to the *Settings* section and toggle the **Enable APIs Section** switch.
:::
```

![Panel default container](https://cloud.githubusercontent.com/assets/6318057/26082080/4a465756-39a4-11e7-99a1-79846c7cdfa6.png)

##### Panel (warning)

```markdown
::: panel-warning Title
Description
:::

::: panel-warning Security Warning
It is important to understand that the Authorization Code flow should only be used in cases such as a Regular Web Application where the Client Secret can be safely stored. In cases such as a Single Page Application, the Client Secret is available to the client (in the web browser), so the integrity of the Client Secret cannot be maintained. That is why the [Implicit Grant flow](/api-auth/grant/implicit) is more appropriate in that case.
:::
```

![Panel warning container](https://cloud.githubusercontent.com/assets/6318057/26082243/588586b0-39a5-11e7-88ef-3290be88e96a.png)

##### Next steps list

Use this container to mark a Next to read/Continue reading list of links.

Try to keep the list length to a minimum (up to 5 links).

```
::: next-steps
* [Access Token](/tokens/access-token)
* [ID Token](/tokens/id-token)
* [OpenID Connect Overview](/protocols/oidc)
:::
```

![Next steps list](https://user-images.githubusercontent.com/6318057/27233085-b116f28a-528e-11e7-9ac3-4463a9c5db3d.png)

### HTTP Request Snippets
You can add a [HAR request format](http://www.softwareishard.com/blog/har-12-spec/#request) snippet to make an example HTTP request availible in a variety of languages. This will generate a tab view showing the HTTP request in various languages.

**NOTE:** You need to set the language type to `har` for this to work. View this raw markdown document for an example.

```har
{
    "method": "GET",
    "url": "http://www.example.com/path/?param=value",
    "httpVersion": "HTTP/1.1",
    "cookies": [],
    "headers": [
      { "name" "Authorization", "value": "Bearer ABCD" }
    ],
    "queryString" : [],
    "postData" : {
      "mimeType": "application/json",<commit_msg>add library info for HAR elements<commit_after># Contributing to Auth0 Documentation

:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:

The following is a set of guidelines for contributing to the Auth0 documentation. These are just guidelines, not rules, use your best judgment and feel free to propose changes to this document in a pull request.

## Table of Contents

* [General Guidelines](#general-guidelines)
* [Reusing Content](#reusing-content)
* [Markdown](#markdown)
  * [Headings](#headings)
  * [UI Components](#ui-components)
  * [HTTP Request Snippets](#http-request-snippets)
  * [Escaping Strings](#escaping-strings)
  * [Image zooming](#image-zooming)
  * [Screenshots](#screenshots)
  * [Front Matter](#front-matter)
  * [Linting](#linting)
* [Sidebar](#sidebar)
* [Beta Content](#beta-content)
* [Finishing](#finishing)
* [Editing with Wordy](#editing-with-wordy)
* [Test Procedures](#test-procedures)
* [Review Apps](#review-apps)
* [Quickstarts](#quickstarts)
  * [Creating Quickstarts](#creating-quickstarts)
  * [Versioning Quickstarts](#versioning-quickstarts)
  * [Quickstart Guidelines](#quickstart-guidelines)
  * [Seed Projects](#seed-projects)
* [Updates Feed](#updates-feed)
* [API](#api)
* [Code snippets](#code-snippets)
* [Document Front-matter](#document-front-matter)
* [Document Variables](#document-variables)
  * [Common Variables](#common-variables)
  * [User Specific Variables](#user-specific-variables)
* [Versioning](#versioning)

## General Guidelines

* Read and follow the [Style Guide](STYLEGUIDE.md).
* Consult the [Words](WORDS.md) document for Auth0 specific spellings and definitions.
* Always use relative URLs for internal `auth0.com/docs` links. For example, if the absolute path to the document is `https://auth0.com/docs/identityproviders`, use `/identityproviders`. These links will be correctly formatted in the build process.
* Do not hard code links to Auth0 sites like `docs.auth0.com` or `manage.auth0.com`. Instead, use [Parameter Aliases](#parameter-aliases), such as `${manage_url}`.
* Name files with all lowercase using dashes (-) to separate words. If using a date in the file name, it should be in the format YYYY-MM-DD. For example, `this-is-my-file.md` or `this-is-a-title-2015-10-01.md`.
* Do not store images in external locations like Dropbox, CloudUp, or the Auth0 CDN. Link to images in this repo using a relative path `![ALT_TEXT](/media/folder/image-name.png)`. The image will be uploaded to the CDN and the link will be formatted during the build process. Do not forget to set the alternate text for each image.
* Keep images to no more than 750 pixels wide.
* Screenshots of the Auth0 dashboard including the browser window with dropshadow can be up to 900 pixels wide to maintain legibility.
* Run all images through [TinyPNG](https://tinypng.com/).

## Reusing content

To avoid duplication of content, you can create document fragments to be referenced from other documents. The process of including another document is shown below.

First, create your fragment document. The convention is to name fragments with an underscore, like: `_mydocument.md`.

After you create your markdown document, you can reference it in another document with a relative path:

```markdown
<%= include('../_mydocument.md') %>
```

Additionally, you can send variables to the included document:

```markdown
<%= include('../_mydocument.md', { key: 'value', something: true }) %>
```

## Markdown

Markdown on this site conforms to the [CommonMark](http://commonmark.org/) spec. Additionally, there are a few custom markdown features available as described below.

### Headings

One common mistake with formatting of headings is to not include a space between the hashes and the text. Some markdown processors allow this, but we do not. You must put a space as shown below.

INVALID: `#My Heading`

VALID: `# My Heading`

### UI Components

General advice:
- Don't add custom UI components with HTML unless it's really necessary.
- Don't add any element before the main title. If you want to show some general information for the whole doc put the element after the main title.
- Try to keep the amount of UI components on your docs to a minimum. They make the documentation more difficult to read and cut the reading flow.
- Only use the `blockquote` element (`>` in markdown) to represent actual quotes. Use a `note` or a `panel` if you want to highlight the information.

#### Note

Use this component if you want to display some extra information, links to related content or clarifications.

Only use this if the content is brief (one to four lines), if not use the `panel` component.

```markdown
::: note
  If you need a refresher on the OAuth 2.0 protocol, you can go through our <a href="/protocols/oauth2">OAuth 2.0</a> article.
:::
```

![Note container](https://cloud.githubusercontent.com/assets/6318057/26081072/91318302-399f-11e7-8cf2-57cb55c6ce1d.png)

#### Warning

Use this component if you want to notify that the content is deprecated, there is a security issue or to highlight some **very important** information.

Only use this if the content is brief (one to four lines), if not use the `panel-warning` component. It's recommended to keep the copy of the warnings short and clear.

```markdown
::: warning
Long-lived tokens compromise your security. Following this process is <strong>NOT</strong> recommended.
:::
```

![Warning container](https://cloud.githubusercontent.com/assets/6318057/26081268/6a894af4-39a0-11e7-96bc-6ef69a3be941.png)

#### Panels

Use panels when you want to separate long information from the main body of the document.

Try to add a meaningful title to the panel. Avoid using "NOTE" or "WARNING".

We support two types of panels: **panel** and **panel-warning**.

##### Panel (default)

```markdown
::: panel Title
Description
:::

::: panel Enable APIs Section
If you can't see the [API section](${manage_url}/#/apis) in the left hand menu of the dashboard then you will have to enable it. Navigate to your [Account Advanced Settings](${manage_url}/#/account/advanced), scroll down to the *Settings* section and toggle the **Enable APIs Section** switch.
:::
```

![Panel default container](https://cloud.githubusercontent.com/assets/6318057/26082080/4a465756-39a4-11e7-99a1-79846c7cdfa6.png)

##### Panel (warning)

```markdown
::: panel-warning Title
Description
:::

::: panel-warning Security Warning
It is important to understand that the Authorization Code flow should only be used in cases such as a Regular Web Application where the Client Secret can be safely stored. In cases such as a Single Page Application, the Client Secret is available to the client (in the web browser), so the integrity of the Client Secret cannot be maintained. That is why the [Implicit Grant flow](/api-auth/grant/implicit) is more appropriate in that case.
:::
```

![Panel warning container](https://cloud.githubusercontent.com/assets/6318057/26082243/588586b0-39a5-11e7-88ef-3290be88e96a.png)

##### Next steps list

Use this container to mark a Next to read/Continue reading list of links.

Try to keep the list length to a minimum (up to 5 links).

```
::: next-steps
* [Access Token](/tokens/access-token)
* [ID Token](/tokens/id-token)
* [OpenID Connect Overview](/protocols/oidc)
:::
```

![Next steps list](https://user-images.githubusercontent.com/6318057/27233085-b116f28a-528e-11e7-9ac3-4463a9c5db3d.png)

### HTTP Request Snippets
You can add a [HAR request format](http://www.softwareishard.com/blog/har-12-spec/#request) snippet to make an example HTTP request availible in a variety of languages. This will generate a tab view showing the HTTP request in various languages.

The library we use is [HTTP Snippet](https://github.com/Kong/httpsnippet).

**NOTE:** You need to set the language type to `har` for this to work. View this raw markdown document for an example.

```har
{
    "method": "GET",
    "url": "http://www.example.com/path/?param=value",
    "httpVersion": "HTTP/1.1",
    "cookies": [],
    "headers": [
      { "name" "Authorization", "value": "Bearer ABCD" }
    ],
    "queryString" : [],
    "postData" : {
      "mimeType": "application/json",
{'fraction_non_alphanumeric': 0.11230241391986276, 'fraction_numerical': 0.026834946697708615, 'mean_word_length': 4.659847434119278, 'pattern_counts': {'":': 14, '<': 15, '<?xml version=': 0, '>': 17, 'https://': 15, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6764348', 'n_tokens_mistral': 5126, 'n_tokens_neox': 4654, 'n_words': 1925}