|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +This is the Auth0 Documentation repository, a Mintlify-based documentation platform deployed at https://auth0.com/docs. It contains 4,305 MDX files organized across multiple documentation sections and supports 3 languages (English, French-Canada, Japanese). |
| 8 | + |
| 9 | +## Development Commands |
| 10 | + |
| 11 | +### Local Development |
| 12 | +```bash |
| 13 | +# Install Mintlify CLI (requires Node.js v20) |
| 14 | +npm install mint -g |
| 15 | + |
| 16 | +# Start development server from /main directory |
| 17 | +mint dev |
| 18 | +# Preview at localhost:3000 |
| 19 | +``` |
| 20 | + |
| 21 | +## Repository Structure |
| 22 | + |
| 23 | +``` |
| 24 | +/main/ |
| 25 | +├── docs.json # Mintlify configuration (24,200 lines) |
| 26 | +│ # Defines navigation, SEO, redirects, styling |
| 27 | +├── docs/ # Main documentation content (4,305 MDX files) |
| 28 | +│ ├── get-started/ # Getting started guides |
| 29 | +│ ├── authenticate/ # Authentication documentation |
| 30 | +│ ├── manage-users/ # User management |
| 31 | +│ ├── customize/ # Customization (Actions, Extensions, etc.) |
| 32 | +│ ├── secure/ # Security and token documentation |
| 33 | +│ ├── deploy-monitor/ # Deployment and monitoring |
| 34 | +│ ├── libraries/ # SDK documentation |
| 35 | +│ ├── quickstart/ # Platform-specific quickstarts |
| 36 | +│ ├── troubleshoot/ # Troubleshooting guides |
| 37 | +│ ├── fr-ca/ # French (Canada) translations (full mirror) |
| 38 | +│ ├── ja-jp/ # Japanese translations (full mirror) |
| 39 | +│ └── [assets]/ # css/, fonts/, images/, logo/, media/ |
| 40 | +├── snippets/ # Reusable React components and content |
| 41 | +│ ├── *.jsx # React components (AuthCodeBlock, etc.) |
| 42 | +│ ├── *.mdx # Reusable MDX content snippets |
| 43 | +│ └── quickstart/ # Platform/language-specific code examples |
| 44 | +│ ├── native/ # iOS, Android, Flutter, React Native, etc. |
| 45 | +│ ├── spa/ # React, Vue, Angular, Vanilla JS |
| 46 | +│ ├── webapp/ # Node.js, ASP.NET, Python, Java, etc. |
| 47 | +│ └── backend/ # API authentication examples |
| 48 | +└── ui/ # UI library files (CSS and JS bundles) |
| 49 | +``` |
| 50 | + |
| 51 | +## MDX File Structure |
| 52 | + |
| 53 | +All documentation files follow this structure: |
| 54 | + |
| 55 | +```mdx |
| 56 | +--- |
| 57 | +title: "Page Title" |
| 58 | +description: "SEO description for search engines" |
| 59 | +'og:image': https://cdn2.auth0.com/docs/... |
| 60 | +'og:title': "Social media title" |
| 61 | +'og:url': https://auth0.com/docs/path |
| 62 | +permalink: unique-path-slug |
| 63 | +sidebarTitle: "Optional sidebar label" |
| 64 | +'twitter:description': "Twitter card description" |
| 65 | +'twitter:title': "Twitter card title" |
| 66 | +--- |
| 67 | + |
| 68 | +import { Component } from '/snippets/component.jsx'; |
| 69 | + |
| 70 | +export const codeExample1 = `code content here`; |
| 71 | +export const codeExample2 = `more code here`; |
| 72 | + |
| 73 | +# Page Content Starts Here |
| 74 | + |
| 75 | +<AuthCodeBlock children={codeExample1} language="javascript" /> |
| 76 | +``` |
| 77 | + |
| 78 | +### Key Conventions |
| 79 | + |
| 80 | +1. **Frontmatter**: All MDX files require complete YAML frontmatter with SEO metadata |
| 81 | +2. **Code Examples**: Export code as constants at the top of the file (after imports, before content) |
| 82 | +3. **Imports**: Custom components imported from `/snippets/` directory |
| 83 | +4. **Permalinks**: Used for stable URLs and redirects |
| 84 | + |
| 85 | +## Custom Components |
| 86 | + |
| 87 | +Import and use these React components from `/snippets/`: |
| 88 | + |
| 89 | +- **`<AuthCodeBlock>`**: Code blocks with variable substitution (replaces placeholders dynamically) |
| 90 | + ```mdx |
| 91 | + export const code = `const domain = "{yourDomain}";`; |
| 92 | + <AuthCodeBlock children={code} language="javascript" /> |
| 93 | + ``` |
| 94 | + |
| 95 | +- **`<AuthCodeGroup>`**: Grouped code examples with language/platform tabs |
| 96 | + |
| 97 | +- **`<AuthDocsPipeline>`**: Visual navigation breadcrumb/pipeline |
| 98 | + ```mdx |
| 99 | + <AuthDocsPipeline activeId="authenticate"/> |
| 100 | + ``` |
| 101 | + |
| 102 | +- **`<Card>`**: Navigation cards for linking to other sections |
| 103 | + ```mdx |
| 104 | + <Card title="Title" href="/docs/path">Description</Card> |
| 105 | + ``` |
| 106 | + |
| 107 | +- **`<Tooltip>`**: Inline glossary tooltips |
| 108 | + ```mdx |
| 109 | + <Tooltip tip="Explanation" cta="View Glossary" href="/docs/glossary?term=Term">Text</Tooltip> |
| 110 | + ``` |
| 111 | + |
| 112 | +- Standard Mintlify components: `<Tabs>`, `<Tab>`, `<Frame>`, `<Callout>`, etc. |
| 113 | + |
| 114 | +## Navigation Configuration |
| 115 | + |
| 116 | +The `docs.json` file at the root defines the entire site structure: |
| 117 | + |
| 118 | +```json |
| 119 | +{ |
| 120 | + "navigation": { |
| 121 | + "languages": [ |
| 122 | + { |
| 123 | + "language": "en", |
| 124 | + "tabs": [ |
| 125 | + { |
| 126 | + "tab": "Documentation", |
| 127 | + "dropdowns": [ |
| 128 | + { |
| 129 | + "dropdown": "Getting Started", |
| 130 | + "description": "Learn the basics", |
| 131 | + "icon": "play", |
| 132 | + "pages": ["docs/get-started", ...] |
| 133 | + } |
| 134 | + ] |
| 135 | + } |
| 136 | + ] |
| 137 | + } |
| 138 | + ] |
| 139 | + } |
| 140 | +} |
| 141 | +``` |
| 142 | + |
| 143 | +### To Add/Remove Pages |
| 144 | + |
| 145 | +1. Edit `docs.json` to update the navigation structure |
| 146 | +2. Add/remove the corresponding MDX file in `docs/` |
| 147 | +3. Test locally with `mint dev` |
| 148 | + |
| 149 | +### Redirects |
| 150 | + |
| 151 | +`docs.json` includes a `redirects` array for URL changes: |
| 152 | +```json |
| 153 | +"redirects": [ |
| 154 | + {"source": "/old-path", "destination": "/new-path"} |
| 155 | +] |
| 156 | +``` |
| 157 | + |
| 158 | +## Content Organization |
| 159 | + |
| 160 | +### Main Documentation Sections |
| 161 | + |
| 162 | +1. **Getting Started** - Identity fundamentals, Auth0 overview, architecture |
| 163 | +2. **Authenticate** - Login, SSO, passwordless, identity providers, protocols |
| 164 | +3. **Manage Users** - User accounts, organizations, sessions, metadata |
| 165 | +4. **Customize** - Actions, custom domains, email templates, events, extensions, forms, hooks |
| 166 | +5. **Secure** - Access tokens, refresh tokens, ID tokens, rate limiting |
| 167 | +6. **Deploy and Monitor** - Deploy CLI, logs, monitoring |
| 168 | +7. **Libraries** - SDK documentation (Auth0.js, SPA SDK, mobile SDKs) |
| 169 | +8. **Quickstart** - Platform-specific implementation guides |
| 170 | + |
| 171 | +### Quickstart Structure |
| 172 | + |
| 173 | +Quickstarts are organized by application type: |
| 174 | +- **native/**: iOS, Android, React Native, Flutter, Ionic, MAUI |
| 175 | +- **spa/**: React, Vue, Angular, Vanilla JS |
| 176 | +- **webapp/**: Node.js, ASP.NET, PHP, Python, Java, Go, Ruby |
| 177 | +- **backend/**: API authentication |
| 178 | + |
| 179 | +Code examples for quickstarts live in `/snippets/quickstart/{type}/{platform}/` |
| 180 | + |
| 181 | +### Localization |
| 182 | + |
| 183 | +Full documentation is mirrored in three languages: |
| 184 | +- **`docs/`** - English (primary) |
| 185 | +- **`docs/fr-ca/`** - French (Canada) |
| 186 | +- **`docs/ja-jp/`** - Japanese |
| 187 | + |
| 188 | +When editing English content, consider whether translations need updates. The directory structure is identical across languages. |
| 189 | + |
| 190 | +## Contribution Workflow |
| 191 | + |
| 192 | +### Branch Naming Convention |
| 193 | + |
| 194 | +- **`fix/`** - Bug fixes, typos, broken links |
| 195 | +- **`feat/`** - New features or documentation sections |
| 196 | +- **`refactor/`** - Non-feature updates, reorganization |
| 197 | + |
| 198 | +Example: `fix/broken-link-in-quickstart` or `feat/new-mfa-guide` |
| 199 | + |
| 200 | +### Making Changes |
| 201 | + |
| 202 | +1. **Contact Auth0 Product Documentation team** before opening PRs |
| 203 | +2. Fork repository and create a feature branch with appropriate prefix |
| 204 | +3. Edit MDX files following the conventions above |
| 205 | +4. Test changes locally: `mint dev` and preview at `localhost:3000` |
| 206 | +5. Commit with clear messages explaining what changed and why |
| 207 | +6. Push to forked repository on GitHub |
| 208 | +7. Create pull request with completed template |
| 209 | +8. Request review from Auth0 Documentation team |
| 210 | + |
| 211 | +## Common Patterns and Pitfalls |
| 212 | + |
| 213 | +### Code Example Pattern |
| 214 | + |
| 215 | +**Correct:** |
| 216 | +```mdx |
| 217 | +--- |
| 218 | +title: "Example" |
| 219 | +--- |
| 220 | +import {AuthCodeBlock} from "/snippets/AuthCodeBlock.jsx"; |
| 221 | + |
| 222 | +export const codeExample = `console.log("hello");`; |
| 223 | + |
| 224 | +# Content |
| 225 | + |
| 226 | +<AuthCodeBlock children={codeExample} language="javascript" /> |
| 227 | +``` |
| 228 | + |
| 229 | +**Incorrect:** |
| 230 | +```mdx |
| 231 | +# Content |
| 232 | + |
| 233 | +export const codeExample = `console.log("hello");`; // ❌ Too late! |
| 234 | + |
| 235 | +<AuthCodeBlock children={codeExample} language="javascript" /> |
| 236 | +``` |
| 237 | + |
| 238 | +Code exports must be at the top of the file after imports, not inline with content. |
| 239 | + |
| 240 | +### Navigation Updates |
| 241 | + |
| 242 | +When creating new pages, remember to: |
| 243 | +1. Create the MDX file in the appropriate `docs/` subdirectory |
| 244 | +2. Add the page path to `docs.json` navigation |
| 245 | +3. Both steps are required for the page to appear in navigation |
| 246 | + |
| 247 | +### Variable Substitution |
| 248 | + |
| 249 | +`AuthCodeBlock` supports dynamic variable replacement. Variables like `{yourDomain}`, `{clientId}`, etc. are automatically replaced based on user context. Use this pattern for user-specific values in code examples. |
| 250 | + |
| 251 | +### Asset References |
| 252 | + |
| 253 | +- Images: `/docs/images/...` or use CDN URLs |
| 254 | +- Fonts: Configured in `docs.json` with CDN links |
| 255 | +- Custom CSS: `/docs/css/` or `/snippets/css/` |
| 256 | + |
| 257 | +### Glossary Links |
| 258 | + |
| 259 | +Link to glossary terms using Tooltip components rather than plain links for better UX: |
| 260 | +```mdx |
| 261 | +<Tooltip tip="Definition" href="/docs/glossary?term=TermName">Term</Tooltip> |
| 262 | +``` |
| 263 | + |
| 264 | +## Additional Resources |
| 265 | + |
| 266 | +- **Mintlify Documentation**: https://mintlify.com/docs |
| 267 | +- **Auth0 Docs Site**: https://auth0.com/docs |
| 268 | +- **Issue Tracker**: https://github.com/auth0/docs-v2/issues |
| 269 | +- **Security Disclosure**: https://auth0.com/whitehat (do not use public issue tracker) |
| 270 | +- **License**: MIT License |
0 commit comments