Contribution Guide #329

avanscoy · 2025-11-21T17:24:22Z

📝 Before you begin

By opening this PR, you agree to the terms of the Auth0 Code of Conduct. For guidance on creating a high-quality PR, see the Contributing Guidelines.

✏️ Changes

Adding the Contribution Guide. This Guide is going to be part of the PR Template in draft by @btiernay.

Problem solved: Provides requirements and references on how to contribute to help get the repo ready for contributions from Auth0 Staff
Docs/UI areas affected: main/ documentation site
Scope: Adds comprehensive contribution guidelines including references to Mintlify and Auth0 Product Documentation best practices to ensure clarity and coherence

📁 Documentation scope

Docs site(s) affected

main/
auth4genai/

Other areas

Shared UI library (ui/)
GitHub workflows (.github/workflows/)
Tooling or scripts (tools/)

Type of change

New page or major section
Update to existing content
Navigation or structure change
Code examples or snippets
UI component or Mintlify configuration
GitHub workflows (.github/workflows/)
Scripts or tooling (tools/)

Paths: main/CONTRIBUTION.mdx

🔗 References

Mintlify documentation
Auth0 Product Documentation best practices (internal)
Screenshot Use Policy (internal)
Auth0 Docs Style Guide (internal)

Related PRs:

PR #301 - GitHub pull request template
PR #333 - Add taking-screenshots skill for standardized documentation screenshots
PR #299 - Add Auth0 Docs Style Guide skill for Claude Code

🎯 Testing

Local validation

Content-only change (no build or navigation impact)
mint dev in affected folders
mint broken-links (when applicable)
mint a11y (when applicable)
npm run build in ui/ (for UI changes)

Style and structure

Follows the Contributing Guidelines
Uses correct Auth0 terminology
Code blocks include language and filenames when needed

Repo checks

All required GitHub checks are passing
The correct base branch is being used

🔄 Redirects

Not applicable - no URL changes.

🌍 Internationalization (main docs only)

Not applicable - contribution guide is not part of localized content

🧩 Impact and dependencies

User-facing impact

Establishes clear contribution guidelines for Auth0 Staff contributors
Provides references to Mintlify documentation and best practices
Documents file standards, heading requirements, formatting guidelines
Includes screenshot policy guidance

Dependencies

Complements the PR template being developed by @btiernay
References internal Auth0 documentation (Style Guide, Screenshot Policy)

🚀 Deployment

Safe to deploy on merge

📝 Follow-up

No follow-up needed

💬 Additional context

This contribution guide includes comprehensive documentation for Auth0 Staff contributors covering:

General guidelines: Links to internal style guide and documentation resources
Docs-as-code workflow: GitHub account requirements, Mintlify references, local environment setup
File standards: Naming conventions (hyphenated, not camelCase or underscores)
File headings: Complete reference for metadata fields including og:description, og:title, permalink, sidebarTitle, etc.
Format text: Markdown formatting with accessibility considerations (no italics, minimal underline)
Media: Image upload requirements, screenshot guidelines, and policy references
Embedded content types: Guidance on warnings, notes, lists, and other UI elements

The guide ensures consistency and quality across all documentation contributions.

Tip

Useful references:

Contributing Guidelines
Mintlify documentation: https://www.mintlify.com/docs
main README
auth4genai README

btiernay · 2025-11-21T22:47:20Z

main/CONTRIBUTION.mdx

A few comments / suggestions on this file:

Should we call it CONTRIBUTING.md (note, not .mdx) and hoist to the root of the project per GitHub conventions / guidance?

Does this apply to both sites (i.e. auth0 and auth0-genai) or just one (i.e. main/ (auth0))?

@btiernay this should also apply to auth4genai

btiernay · 2025-11-21T22:47:52Z

main/CONTRIBUTION.mdx

+For contributors in the Auth0 organization:
+* Use your Auth0 GitHub account.
+* Review the [Mintlify documentation](https://www.mintlify.com/docs).
+* Review the [READ.ME](main/README.md) to set up your local environment and contribution workflow.


nit: README

btiernay · 2025-11-21T22:48:45Z

main/CONTRIBUTION.mdx

+    "enforce_online_refresh_tokens": true
+  }
+}
+```


Should this continue to subsume the subsequent content / example?

lrzhou25 · 2025-11-22T00:17:33Z

main/CONTRIBUTION.mdx

+**Example**
+> 1. Navigate to your application’s settings, [Auth0 Dashboard > Applications > Settings](https://manage.auth0.com/application/settings).
+>
+>   <Frame!>[Auth0 Dashboard > Applications > Settings](/relative-link-to-the-image)</Frame>


Suggested change

> <Frame!>[Auth0 Dashboard > Applications > Settings](/relative-link-to-the-image)</Frame>

> <Frame>![Auth0 Dashboard > Applications > Settings](/relative-link-to-the-image)</Frame>

lrzhou25 · 2025-11-22T00:18:31Z

main/CONTRIBUTION.mdx

@btiernay this should also apply to auth4genai

lrzhou25 · 2025-11-22T00:19:15Z

main/CONTRIBUTION.mdx

+Auth0 documentation, https://www.auth0.com/docs is located at https://github.com/auth0/docs-v2/. If you are not in the Auth0 organization, report inconsistencies and bugs under the [Issues](https://github.com/auth0/docs-v2/issues) section.
+
+For contributors in the Auth0 organization:
+* Use your Auth0 GitHub account.


i don't think you can use your Auth0 (Atko) GitHub account. you'll need to use your personal GitHub account

lrzhou25 · 2025-11-22T00:20:17Z

main/CONTRIBUTION.mdx

+* We do **not** use italics in docs due to issues with screen readers and accessibility.
+* Avoid using underline. We use this for linking and additional underline can clutter the UI.
+
+To learn about UI elements, such as Notes, Code blocks, Tabs, and Warning labels, review Embedded Content Types.


should Embedded Content Types be linked to an article somewhere?

lrzhou25 · 2025-11-22T00:21:00Z

main/CONTRIBUTION.mdx

+Do not store images in external locations like Dropbox, CloudUp, or the Auth0 CDN.
+</Warning>
+
+Auth0 organization members should review the Screenshot policy.


should we link to the screenshot policy here? https://oktawiki.atlassian.net/wiki/spaces/DOCS/pages/2544472521/Screenshot+Use+Policy or an anchor link to the screenshot section below?

This is a Public doc so we should review what the policy / guidance is for linking to internal resources.

in that case, let's just do the anchor link to the screenshot section then

lrzhou25 · 2025-11-22T00:21:38Z

main/CONTRIBUTION.mdx

+
+### Components
+
+We use component in technical documentation to draw attention to important information customers need to know. Review the following components and when best to use them. To learn more, read [Components](https://www.mintlify.com/docs/components).


Suggested change

We use component in technical documentation to draw attention to important information customers need to know. Review the following components and when best to use them. To learn more, read [Components](https://www.mintlify.com/docs/components).

We use components in technical documentation to draw attention to important information customers need to know. Review the following components and when best to use them. To learn more, read [Components](https://www.mintlify.com/docs/components).

lrzhou25 · 2025-11-22T00:23:43Z

main/CONTRIBUTION.mdx

+    "enforce_online_refresh_tokens": true
+  }
+}
+```


lrzhou25 · 2025-11-22T00:24:22Z

main/CONTRIBUTION.mdx

+
+## Reference links
+
+ The Learn More section at the bottom of each page indicates a list of associated articles to read.


Suggested change

The Learn More section at the bottom of each page indicates a list of associated articles to read.

The Learn More section at the bottom of each page indicates a list of associated articles to read.

lrzhou25 · 2025-11-22T00:26:20Z

main/CONTRIBUTION.mdx

+
+### Borders
+
+Apply a 1px centered border of color #cccccc to keep the image from blending with the background and appearing to float.


are we still planning on doing this when we have Frames now?

lrzhou25 · 2025-11-22T00:27:45Z

main/CONTRIBUTION.mdx

+
+Next, add the relative path to the `{}docs.json` file to add it to the side navigation panel under the appropriate heading:
+
+```


could you pretty print this json :)

btiernay

Line 82: Incomplete sentence

2. Scroll down the

This sentence is cut off mid-thought. Please complete it or remove the incomplete example.

btiernay · 2025-11-23T22:36:08Z

main/CONTRIBUTION.mdx

+<Note>
+Try to keep sub-bullets even. If you have an A, try to also have a B.
+</Note>
+


Typo: should be "asterisks" instead of "astricks"

btiernay · 2025-11-23T22:36:27Z

main/CONTRIBUTION.mdx

+3. For existing words, find the short text you will need for the tooltip. You can search for the term with the `term=` tag.
+
+<Note>
+Use the same short description to maintain consistency across Auth0 documentation.


Would be helpful to add language tags to code blocks for syntax highlighting. Examples:

Line 277: glossary.jsx could use javascript

Line 305: osascript command could use bash

Line 345: docs.json could use json

btiernay · 2025-11-23T22:36:39Z

main/CONTRIBUTION.mdx

+```
+osascript -e 'tell application "Chrome" to set the bounds of the front window to {100, 150, 1200, 900}'
+```
+


The osascript command only works on macOS. Could add a note for cross-platform compatibility:

> **Note**: This script is macOS-specific. Windows and Linux users should manually resize their browser window to 1100x750px.

Or alternatively, could document using browser DevTools responsive design mode as a cross-platform option.

btiernay · 2025-11-23T22:38:32Z

main/CONTRIBUTION.mdx

+| `configure-identity-provider.mdx` | `ConfigureIdentityProviders.mdx` |
+| `customize-ul-templates.mdx` | `customize_ul_templates.mdx` |
+
+### File headings


Mintlify and most MDX documentation typically refers to this as "frontmatter" or "metadata" rather than "File headings". Might be clearer to use the more common term.

btiernay · 2025-11-23T22:39:04Z

main/CONTRIBUTION.mdx

+2. Choose the application to update.
+3. Scroll to the **Cross-Origin Authentication** setting.
+
+Sub-level steps:


Using <p></p> tags for spacing here - Mintlify usually handles spacing with blank lines. Might be simpler to use standard Markdown formatting with blank lines between sub-steps.

btiernay · 2025-11-23T22:39:14Z

main/CONTRIBUTION.mdx

+* Include any default values, minimum and maximum values, and/or recommended values.
+* Use monospaced font (code font) for parameter, field, or property.
+* Descriptions should be in regular text with the exception of other properties, fields, or parameters.
+


Extra space before the asterisks here - should just be **Markdown tables**

btiernay · 2025-11-23T22:39:26Z

main/CONTRIBUTION.mdx

+<tr>
+<th><strong>Parameter</strong></th>
+<th><strong>Description</strong></th>
+</tr>


The <Note> here looks like it might be part of the HTML table example. Could move it outside the code block to make it clearer it's separate guidance about when to use Markdown vs HTML tables.

Contribution Guide

2702d6c

avanscoy added documentation Improvements or additions to documentation main-docs Changes related to auth0's main docs (https://auth0.com/docs) DO NOT MERGE labels Nov 21, 2025

avanscoy requested review from BcnCarlos, btiernay, lrzhou25 and nick-gagliardi November 21, 2025 17:24

mintlify bot deployed to staging - main November 21, 2025 17:29 View deployment

btiernay reviewed Nov 21, 2025

View reviewed changes

lrzhou25 reviewed Nov 22, 2025

View reviewed changes

btiernay mentioned this pull request Nov 23, 2025

Add taking-screenshots skill for standardized documentation screenshots #333

Merged

26 tasks

btiernay reviewed Nov 23, 2025

View reviewed changes

	> <Frame!>[Auth0 Dashboard > Applications > Settings](/relative-link-to-the-image)</Frame>
	> <Frame>![Auth0 Dashboard > Applications > Settings](/relative-link-to-the-image)</Frame>


		### Components

		We use component in technical documentation to draw attention to important information customers need to know. Review the following components and when best to use them. To learn more, read [Components](https://www.mintlify.com/docs/components).

	We use component in technical documentation to draw attention to important information customers need to know. Review the following components and when best to use them. To learn more, read [Components](https://www.mintlify.com/docs/components).
	We use components in technical documentation to draw attention to important information customers need to know. Review the following components and when best to use them. To learn more, read [Components](https://www.mintlify.com/docs/components).


		## Reference links

		The Learn More section at the bottom of each page indicates a list of associated articles to read.


		### Borders

		Apply a 1px centered border of color #cccccc to keep the image from blending with the background and appearing to float.


		Next, add the relative path to the `{}docs.json` file to add it to the side navigation panel under the appropriate heading:

		```

Contribution Guide #329

Are you sure you want to change the base?

Contribution Guide #329

Conversation

avanscoy commented Nov 21, 2025 • edited by btiernay Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📝 Before you begin

✏️ Changes

📁 Documentation scope

🔗 References

🎯 Testing

🔄 Redirects

🌍 Internationalization (main docs only)

🧩 Impact and dependencies

🚀 Deployment

📝 Follow-up

💬 Additional context

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

btiernay Nov 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

btiernay left a comment

Choose a reason for hiding this comment

Uh oh!

btiernay Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

btiernay Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

btiernay Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

btiernay Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

btiernay Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

btiernay Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

avanscoy commented Nov 21, 2025 •

edited by btiernay

Loading

btiernay Nov 22, 2025 •

edited

Loading

btiernay Nov 23, 2025 •

edited

Loading

btiernay Nov 23, 2025 •

edited

Loading

btiernay Nov 23, 2025 •

edited

Loading

btiernay Nov 23, 2025 •

edited

Loading

btiernay Nov 23, 2025 •

edited

Loading

btiernay Nov 23, 2025 •

edited

Loading

btiernay Nov 23, 2025 •

edited

Loading