Merge commit '268f15fe002ecfab2469da87e979c7c26d56595a' as 'docs'

Author: emnul

docs/.github/pull_request_template.md

@@ -0,0 +1,27 @@
+## Documentation Pull Request
+
+### Summary
+<!-- Briefly describe what documentation changes are included in this PR -->
+
+### Type of Change
+<!-- Check all that apply -->
+- [ ] New documentation
+- [ ] Documentation update/revision
+- [ ] Fix typos or grammar
+- [ ] Restructure/reorganize content
+- [ ] Add examples or tutorials
+- [ ] Update API documentation
+- [ ] Other: ___________
+
+### Related Issues
+<!-- Link any related issues -->
+Fixes #
+Relates to #
+
+### Checklist
+- [ ] Build succeeds locally with `pnpm run build`
+- [ ] Lint is successful when running `pnpm run check`
+- [ ] Docs follow [OpenZeppelin Documentation Standards](https://github.com/OpenZeppelin/docs/blob/main/STANDARDS.md)
+
+### Additional Notes
+<!-- Any additional context, concerns, or information for reviewers -->

docs/.github/workflows/lint.yml

@@ -0,0 +1,40 @@
+name: Lint & Format
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  NEXT_TELEMETRY_DISABLED: 1
+
+jobs:
+  lint:
+    name: Lint and Format Check
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v5
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run lint and format checks
+        run: pnpm run check
+
+      - name: Build check
+        run: pnpm run build

docs/.github/workflows/sync-search.yml

@@ -0,0 +1,27 @@
+name: Sync Search Content
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  sync-search:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Run sync search content
+        run: bun run scripts/sync-search-content.ts
+        env:
+          NEXT_PUBLIC_ALGOLIA_ID: ${{ secrets.NEXT_PUBLIC_ALGOLIA_ID }}
+          ALGOLIA_PRIVATE_KEY: ${{ secrets.ALGOLIA_PRIVATE_KEY }}

docs/.gitignore

@@ -0,0 +1,35 @@
+# deps
+/node_modules
+
+# generated content
+.contentlayer
+.content-collections
+.source
+
+# test & build
+/coverage
+/.next/
+/out/
+/build
+*.tsbuildinfo
+
+# misc
+.DS_Store
+*.pem
+/.pnp
+.pnp.js
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# others
+.env*.local
+.vercel
+next-env.d.ts
+old-docs
+.claude
+TODO.md
+broken-links.md
+
+# Local Netlify folder
+.netlify

docs/AGENTS.md

@@ -0,0 +1,118 @@
+# AGENTS.md - OpenZeppelin Docs Codebase Guide
+
+## Build/Lint/Test Commands
+- `pnpm run build` - Build the Next.js application
+- `pnpm run dev` - Start development server with turbo
+- `pnpm run start` - Start production server
+- `pnpm run postinstall` - Process MDX files with fumadocs-mdx
+- `pnpm run lint` - Lint code with Biome
+- `pnpm run lint:fix` - Lint and auto-fix issues with Biome
+- `pnpm run format` - Check code formatting with Biome
+- `pnpm run format:fix` - Format code with Biome
+- `pnpm run check` - Run both linting and formatting checks
+- `pnpm run check:fix` - Run both linting and formatting with auto-fix
+- No test commands configured - this is a documentation site
+
+## Navigation Management
+The site uses a **modular JSON navigation system** instead of fumadocs meta.json files:
+
+### Navigation Structure
+- `src/navigation/` - Modular navigation configuration
+  - `types.ts` - TypeScript interfaces for navigation
+  - `contracts.json` - All contract-related navigation
+  - `tools.json` - Tools section navigation
+  - `ecosystems.json` - Ecosystem-specific sections
+  - `index.ts` - Combines all sections into navigationTree
+
+### Editing Navigation
+- **Add new pages**: Edit the relevant JSON file (contracts/tools/ecosystems)
+- **Reorder sections**: Modify array order in respective JSON files
+- **Add new sections**: Create new JSON file and import in `index.ts`
+- **Do NOT use meta.json files** - they have been removed and are not supported
+
+## Code Style Guidelines
+
+### TypeScript/JavaScript
+- Use TypeScript strict mode (enabled in tsconfig.json)
+- Prefer named imports: `import { RootProvider } from 'fumadocs-ui/provider'`
+- Use path aliases: `@/*` for src/, `@/.source` for .source/
+- Function components with explicit return types when needed
+- Use React 19+ features and patterns
+
+### File Structure
+- Source files in `src/` directory
+- Documentation content in `content/` with nested version folders (v2.x, v3.x, etc.)
+- Examples in `examples/` directory organized by feature
+- Public assets in `public/` directory
+- Navigation config in `src/navigation/` directory
+
+### Naming Conventions
+- PascalCase for React components and interfaces
+- camelCase for variables and functions
+- kebab-case for file names in content directories
+
+## Markdown Link Cleanup Strategy
+
+### Problem
+Legacy markdown files often contain complex, unreadable link syntax that creates URL-encoded URLs like:
+```
+http://localhost:3000/api/access#has_role(role:-felt252,-account:-contractaddress)-%E2%86%92-bool-external
+```
+
+### Solution Approach
+When cleaning up markdown files with complex link syntax, follow this systematic approach:
+
+#### 1. Identify Complex Link Patterns
+Look for these problematic patterns:
+- **Function list links**: `[`+function_name+`](#`[.contract-item-name]#`function_name`#`(params)``-[.item-kind]#external#)`
+- **Event list links**: `[`+EventName+`](#`[.contract-item-name]#`eventname`#`(params)``-[.item-kind]#event#)`
+- **Function headings**: `#### `[.contract-item-name]#`function_name`#`(params)`` [.item-kind]#external#`
+
+#### 2. Create Clean Link Strategy
+Replace with simple, readable format:
+- **Clean list links**: `[`function_name`](#prefix-function_name)`
+- **Clean headings with anchors**: 
+  ```markdown
+  <a id="prefix-function_name"></a>
+  #### `function_name(params) → return_type`
+  ```
+
+#### 3. Anchor ID Naming Convention
+Use descriptive prefixes to avoid conflicts:
+- `iaccesscontrol-` for interface functions/events
+- `component-` for component functions/events  
+- `extension-` for extension functions/events
+
+#### 4. Implementation Process
+1. **Use Task agent** for systematic fixes across large files
+2. **Fix by section** - group related functions/events together
+3. **Update both links and targets** - ensure table of contents links point to correct anchors
+4. **Verify no complex patterns remain** - search for `[.contract-item-name]#` and `[.item-kind]#`
+
+#### 5. Benefits
+- ✅ Clean, readable URLs
+- ✅ Better SEO and user experience
+- ✅ Easier maintenance and debugging
+- ✅ Consistent markdown formatting
+
+### Example Before/After
+
+**Before (Complex):**
+```markdown
+* [`+has_role(role, account)+`](#`[.contract-item-name]#`has_role`#`(role:-felt252,-account:-contractaddress)-→-bool``-[.item-kind]#external#)
+
+#### `[.contract-item-name]#`has_role`#`(role: felt252, account: ContractAddress) → bool`` [.item-kind]#external#
+```
+
+**After (Clean):**
+```markdown
+* [`has_role(role, account)`](#iaccesscontrol-has_role)
+
+<a id="iaccesscontrol-has_role"></a>
+#### `has_role(role: felt252, account: ContractAddress) → bool`
+```
+
+### Framework Compatibility Notes
+- **DO NOT use `{#anchor}` syntax** - breaks the framework parser
+- **USE HTML anchor tags** - `<a id="anchor-name"></a>` format is safe
+- **Test locally** to ensure links work properly after changes

docs/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing
+
+Thank you for your interest in contributing to the OpenZeppelin Docs! We welcome contributions from everyone.
+
+## How to Contribute
+
+Please follow this guide if you have something to contribute.
+
+### Reporting Issues
+
+If you find a bug or have a suggestion for improvement:
+
+1. Check if the issue already exists in [GitHub issues](https://github.com/OpenZeppelin/docs/issues)
+2. If not, create a new issue with a clear description
+3. Wait for a team member to comment before moving forward with a pull request
+
+### Making Changes
+
+1. Fork the repository
+2. Create a new branch for your change
+3. Follow the local development guide in the [README](README.md) or with the steps [below](#development-setup)
+4. Use [conventional commits](https://www.conventionalcommits.org/) when making changes
+5. Make sure your changes follow the [OpenZeppelin Docs Standards](STANDARDS.md)
+6. Submit a pull request
+
+### Pull Request Guidelines
+
+- Keep pull requests focused on a single feature or fix
+- Write clear commit messages
+- Spelling fixes should be grouped as much as possible (i.e. fixing multiple errors instead of just one)
+
+### Development Setup
+
+1. Make sure [pnpm](https://pnpm.io) is installed
+
+```bash
+pnpm --version
+```
+
+2. Clone the repo and install dependencies
+
+```bash
+git clone https://github.com/OpenZeppelin/docs
+cd docs
+pnpm install
+```
+
+3. Run the `dev` server to see a live preview and have your changes reflected at `http://localhost:3000`
+
+```bash
+pnpm dev
+```
+
+4. After making changes run the lint command to make formatting rules are applied
+
+```bash
+pnpm run check:fix
+```
+
+## Code of Conduct
+
+Please be respectful and constructive in all interactions. We strive to maintain a welcoming and inclusive environment for all contributors.
+
+## Questions?
+
+If you have questions about contributing, feel free to open an issue or reach out to the maintainers.