Skip to content

Commit 7af0887

Browse files
stevedylandevstevedylandev
committed
chore: update readme
1 parent d1ca70a commit 7af0887

File tree

2 files changed

+119
-20
lines changed

2 files changed

+119
-20
lines changed

‎CONTRIBUTING.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,12 @@ pnpm install
5050
pnpm dev
5151
```
5252

53+
4. After making changes run the lint command to make formatting rules are applied
54+
55+
```bash
56+
pnpm run check:fix
57+
```
58+
5359
## Code of Conduct
5460

5561
Please be respectful and constructive in all interactions. We strive to maintain a welcoming and inclusive environment for all contributors.

‎README.md‎

Lines changed: 113 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,7 @@ Welcome to the OpenZeppelin Docs repo! Before opening an issue or creating a PR
66

77
## Development
88

9-
This is a Next.js application generated with
10-
[Fumadocs](https://github.com/fuma-nama/fumadocs).
9+
This is a Next.js application generated with [Fumadocs](https://github.com/fuma-nama/fumadocs).
1110

1211
To start local development follow the steps below
1312

@@ -31,32 +30,126 @@ pnpm install
3130
pnpm dev
3231
```
3332

33+
## Project Structure
3434

35-
## Explore
35+
### Content Organization
3636

37-
In the project, you can see:
37+
The documentation content is organized in the `content/` directory with the following structure:
3838

39-
- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.
40-
- `app/layout.config.tsx`: Shared options for layouts, optional but preferred to keep.
39+
```
40+
content/
41+
├── community-contracts/ # Community-contributed contracts
42+
├── confidential-contracts/ # Confidential/privacy-focused contracts
43+
├── contracts/ # Core OpenZeppelin Contracts documentation
44+
├── contracts-cairo/ # Cairo contracts for StarkNet
45+
├── contracts-compact/ # Compact contract implementations
46+
├── contracts-stylus/ # Stylus contracts for Arbitrum
47+
├── contracts-ui-builder/ # UI Builder documentation
48+
├── defender/ # Defender platform documentation
49+
├── monitor/ # Monitoring tools documentation
50+
├── relayer/ # Relayer service documentation
51+
├── stellar-contracts/ # Stellar blockchain contracts
52+
├── substrate-runtimes/ # Substrate runtime documentation
53+
├── uniswap-hooks/ # Uniswap v4 hooks
54+
├── upgrades-plugins/ # Upgrade plugins documentation
55+
├── upgrades.mdx # General upgrades guide
56+
└── wizard.mdx # Contract wizard documentation
57+
```
58+
59+
Each product directory contains:
60+
- `index.mdx` - Main documentation entry point
61+
- `changelog.mdx` - Version history and changes
62+
- Subdirectories for specific features/modules
63+
- API reference files
64+
65+
### Application Structure
66+
67+
| Path | Description |
68+
| --------------------------------------- | -------------------------------------------------------------- |
69+
| `src/app/(docs)/` | Documentation pages route group |
70+
| `src/app/(docs)/layout.tsx` | Docs layout wrapper |
71+
| `src/app/(docs)/[...slug]/page.tsx` | Dynamic documentation pages |
72+
| `src/app/page.tsx` | Homepage |
73+
| `src/app/layout.tsx` | Root application layout |
74+
| `src/app/layout.config.tsx` | Shared layout configuration and navigation |
75+
| `src/components/` | Reusable React components |
76+
| `src/components/layout/` | Layout-specific components |
77+
| `src/components/icons/` | Custom SVG icons for products |
78+
| `src/components/ui/` | UI component library |
79+
| `src/lib/source.ts` | Content source adapter with Fumadocs loader |
80+
81+
### Configuration Files
82+
83+
- `source.config.ts` - Fumadocs MDX configuration with math, mermaid, and code highlighting
84+
- `next.config.mjs` - Next.js configuration
85+
- `postcss.config.mjs` - PostCSS configuration for styling
86+
87+
## Navigation & Components
88+
89+
### Navigation Structure
90+
91+
The top navigation is configured in `src/app/layout.config.tsx` and includes:
92+
93+
- **Main Navigation**: Home, Forum, Website links
94+
- **Product Categories**: Auto-generated from content structure
95+
- **Search**: Full-text search across all documentation
96+
- **Theme Toggle**: Light/dark mode switching
97+
98+
Sidebar navigation is handled in `src/navigation/` where multiple navigation JSON trees are exported and used inside `src/components/layout/docs-layout-client.tsx`
99+
100+
### Key Components
101+
102+
#### Layout Components
103+
- `DocsLayoutClient` - Client-side docs layout with sidebar
104+
- `BaseLayoutProps` - Shared layout configuration
105+
- `PageClient` - Individual page wrapper
106+
107+
#### UI Components
108+
- `Card` & `SmallCard` - Content cards for homepage
109+
- `TOC` - Table of contents with scrollspy
110+
- `Search` - Search interface with custom results
111+
- `ThemeToggle` - Theme switching
112+
- `VersionBanner` - Version-specific messaging
113+
114+
#### Custom Icons
115+
Product-specific icons located in `src/components/icons/`:
116+
- Ethereum, Arbitrum, StarkNet, Stellar, Polkadot chains
117+
- Product icons for Contracts, Defender, Monitor, etc.
118+
- Tool icons for Wizard, Ethernaut, etc.
119+
120+
### Content Features
121+
122+
#### MDX Enhancements
123+
- **Math Support**: LaTeX math rendering with KaTeX
124+
- **Mermaid Diagrams**: Flowcharts and diagrams
125+
- **Code Highlighting**: Multi-theme syntax highlighting
126+
- **OpenAPI Integration**: Automatic API documentation generation
127+
128+
#### Interactive Elements
129+
- **OpenZeppelin Wizard**: Embedded contract generation tool
130+
- **Code Examples**: Copy-to-clipboard functionality
131+
- **Version Switching**: Multi-version documentation support
132+
- **Responsive Design**: Mobile-optimized navigation and content
133+
134+
## Content Management
41135

42-
| Route | Description |
43-
| ------------------------- | ------------------------------------------------------ |
44-
| `app/(home)` | The route group for your landing page and other pages. |
45-
| `app/docs` | The documentation layout and pages. |
46-
| `app/api/search/route.ts` | The Route Handler for search. |
136+
### Adding New Content
47137

48-
### Fumadocs MDX
138+
1. Create `.mdx` files in appropriate `content/` subdirectories
139+
2. Use frontmatter for metadata (title, description, etc.)
140+
3. Follow existing directory structure for consistency
141+
4. Update navigation if adding new product categories
49142

50-
A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
143+
### Versioning
51144

52-
Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details.
145+
- Version-specific content in numbered subdirectories (e.g., `contracts/4.x/`)
146+
- Latest content at root level of each product directory
147+
- Automatic version detection and routing
53148

54149
## Learn More
55150

56-
To learn more about Next.js and Fumadocs, take a look at the following
57-
resources:
151+
To learn more about the technologies used:
58152

59-
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
60-
features and API.
61-
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
62-
- [Fumadocs](https://fumadocs.vercel.app) - learn about Fumadocs
153+
- [Next.js Documentation](https://nextjs.org/docs) - React framework features and API
154+
- [Fumadocs](https://fumadocs.vercel.app) - Documentation framework
155+
- [MDX](https://mdxjs.com/) - Markdown with JSX components

0 commit comments

Comments
 (0)