cleanup

macalinao · macalinao · commit 7457d6810ca6 · 2025-08-22T11:21:50.000+08:00
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -314,7 +314,7 @@ When writing documentation for Coda or generated clients:
 
 ## Documentation Site
 
-The `docs/` folder contains the documentation site built with Fumadocs and Next.js 15. The structure follows the Fumadocs reference implementation in `vendor/fumadocs/apps/docs/`.
+The `apps/docs/` folder contains the documentation site built with Fumadocs and Next.js 15. The structure follows the Fumadocs reference implementation in `vendor/fumadocs/apps/docs/`.
 
 ### Tech Stack
 - **Framework**: Next.js 15 with App Router
@@ -326,23 +326,29 @@ The `docs/` folder contains the documentation site built with Fumadocs and Next.
 
 ### Development
 ```bash
-cd docs
+cd apps/docs
 bun run dev     # Start dev server on localhost:3000
 bun run build   # Build for production
 ```
 
 ### Adding Documentation
-1. Create MDX files in `docs/content/docs/`
+1. Create MDX files in `apps/docs/content/docs/`
 2. Update navigation in `meta.json` files if needed
 3. Code blocks automatically get syntax highlighting
 4. Use frontmatter for page metadata (title, description)
+5. **Important**: Do NOT include `# Title` headers in MDX files - the title is already specified in the YAML frontmatter and will be rendered automatically
 
 ### Key Files
 - `src/app/layout.config.tsx` - Site branding and navigation
 - `source.config.ts` - MDX and syntax highlighting config
 - `src/app/global.css` - Tailwind v4 imports with @source directives
 - `content/docs/` - Documentation content in MDX
 
+### MDX Writing Guidelines
+- **No redundant headers**: Since the title is specified in YAML frontmatter, do NOT add `# Title` as the first line of content
+- Start documentation content directly with the introduction paragraph or first section (`##`)
+- The title from frontmatter will be automatically rendered by Fumadocs
+
 ## Troubleshooting
 
 ### Common Issues
diff --git a/apps/docs/content/docs/api.mdx b/apps/docs/content/docs/api.mdx
@@ -3,8 +3,6 @@ title: API Reference
 description: Pre-built TypeScript client libraries for popular Solana programs
 ---
 
-# API Reference
-
 Coda provides pre-built TypeScript client libraries for popular Solana programs. These clients are generated using Coda and are ready to use in your projects.
 
 ## Available Clients
diff --git a/apps/docs/content/docs/configuration.mdx b/apps/docs/content/docs/configuration.mdx
@@ -3,8 +3,6 @@ title: Configuration
 description: Customize Coda generation with coda.config.mjs
 ---
 
-# Configuration
-
 Coda works zero-config out of the box, but you can customize its behavior with a `coda.config.mjs` file.
 
 ## Initialize Configuration
@@ -64,6 +62,39 @@ export default defineConfig({
 });
 ```
 
+### Important: Handling Naming Conflicts
+
+When generating clients from multiple IDLs, be aware of potential naming conflicts:
+
+- **Naming conflicts will NOT throw errors** during code generation
+- Conflicting names will be silently overwritten by the last processed IDL
+- This can lead to unexpected behavior and missing types/instructions
+
+To avoid conflicts, use the `renameVisitor` from `@macalinao/codama-rename-visitor`:
+
+```javascript
+import { renameVisitor } from "@macalinao/codama-rename-visitor";
+
+export default defineConfig({
+  visitors: [
+    renameVisitor({
+      // Rename conflicting instructions in specific programs
+      programA: {
+        instructions: {
+          transfer: "transferA",  // Rename transfer to transferA
+          deposit: "depositA",    // Rename deposit to depositA
+        },
+        definedTypes: {
+          account: "accountA",    // Rename account type to accountA
+        },
+      },
+    }),
+  ],
+});
+```
+
+See the [Quarry configuration](https://github.com/macalinao/coda/blob/master/clients/quarry/coda.config.mjs) for a real-world example where instructions like `claimRewards`, `initMiner`, and `withdrawTokens` were renamed to avoid conflicts between the `quarryMine` and `quarryMergeMine` programs.
+
 ## Custom PDAs
 
 Define program-derived addresses with custom seeds:
diff --git a/apps/docs/content/docs/examples.mdx b/apps/docs/content/docs/examples.mdx
@@ -0,0 +1,90 @@
+---
+title: Examples
+description: Real-world implementations of Coda for Solana client generation
+---
+
+Learn from real-world implementations of Coda in production projects. These examples demonstrate different configuration approaches and use cases for generating TypeScript clients from Anchor IDLs.
+
+## Official Examples
+
+### Token Metadata Client
+
+[![npm version](https://img.shields.io/npm/v/@macalinao/clients-token-metadata.svg?style=flat-square)](https://www.npmjs.com/package/@macalinao/clients-token-metadata)
+[![npm downloads](https://img.shields.io/npm/dm/@macalinao/clients-token-metadata.svg?style=flat-square)](https://www.npmjs.com/package/@macalinao/clients-token-metadata)
+
+[View on GitHub →](https://github.com/macalinao/coda/tree/master/clients/token-metadata)
+
+The Token Metadata client showcases Coda's capabilities for a **single program** setup:
+
+- **Single IDL configuration** - Simple `coda.config.mjs` for one program
+- **Custom PDAs** - Adds program-derived addresses using Codama visitors
+- **Production-ready** - Pre-generated client for Metaplex Token Metadata
+- **Type-safe operations** - Full TypeScript support with proper typing
+
+Perfect for projects that need to interact with a single Solana program or want to see how to configure custom PDAs and transformations.
+
+### Quarry Client
+
+[![npm version](https://img.shields.io/npm/v/@macalinao/clients-quarry.svg?style=flat-square)](https://www.npmjs.com/package/@macalinao/clients-quarry)
+[![npm downloads](https://img.shields.io/npm/dm/@macalinao/clients-quarry.svg?style=flat-square)](https://www.npmjs.com/package/@macalinao/clients-quarry)
+
+[View on GitHub →](https://github.com/macalinao/coda/tree/master/clients/quarry)
+
+The Quarry client demonstrates Coda's **multi-program** capabilities:
+
+- **Multiple IDL handling** - Uses glob patterns to process multiple IDLs
+- **Workspace management** - Generates clients for an entire protocol suite
+- **Shared types** - Manages dependencies between related programs
+- **Modular structure** - Organized output for complex protocol interactions
+
+Ideal for protocol developers managing multiple interconnected programs or anyone building comprehensive DeFi integrations.
+
+## What Makes These Examples Unique
+
+### Token Metadata
+- Shows how to extend generated code with custom PDAs
+- Demonstrates integration with existing Metaplex ecosystem
+- Includes practical patterns for NFT and metadata operations
+
+### Quarry
+- Illustrates handling of protocol-wide client generation
+- Shows glob pattern configuration for discovering IDLs
+- Demonstrates organizing multiple programs in a single package
+
+## Add Your Example
+
+Using Coda in your project? We'd love to showcase it!
+
+**[Submit a Pull Request →](https://github.com/macalinao/coda/pulls)** to add your project to this documentation.
+
+### How to Add Your Example
+
+1. Fork the [Coda repository](https://github.com/macalinao/coda)
+2. Edit this file at `docs/content/docs/examples.mdx`
+3. Add your project following this format:
+
+```mdx
+### Your Project Name
+
+[View on GitHub →](https://github.com/yourname/yourproject)
+
+Brief description of what makes your implementation unique:
+
+- **Key feature 1** - Description
+- **Key feature 2** - Description
+- **Key feature 3** - Description
+
+What developers can learn from your example.
+```
+
+4. Submit your PR with a clear description
+
+We welcome examples that demonstrate:
+- Novel configuration approaches
+- Integration patterns
+- Complex visitor usage
+- Multi-program setups
+- Custom code generation workflows
+- Production deployment strategies
+
+Help the Solana developer community by sharing your Coda implementation!
diff --git a/apps/docs/content/docs/index.mdx b/apps/docs/content/docs/index.mdx
@@ -3,7 +3,7 @@ title: Introduction
 description: TypeScript client generation for Solana programs
 ---
 
-# Welcome to Coda
+## Welcome to Coda
 
 Coda automatically generates TypeScript clients for Solana programs using Anchor IDLs.
 
diff --git a/apps/docs/content/docs/installation.mdx b/apps/docs/content/docs/installation.mdx
@@ -3,8 +3,6 @@ title: Installation
 description: Install and configure Coda for your project
 ---
 
-# Installation
-
 Coda can be installed and used in several ways depending on your project needs.
 
 ## Quick Start (No Installation)
diff --git a/apps/docs/content/docs/meta.json b/apps/docs/content/docs/meta.json
@@ -6,6 +6,7 @@
     "quick-start",
     "why-coda",
     "configuration",
+    "examples",
     "api"
   ]
 }
diff --git a/apps/docs/content/docs/quick-start.mdx b/apps/docs/content/docs/quick-start.mdx
@@ -3,8 +3,6 @@ title: Quick Start
 description: Generate your first TypeScript client with Coda
 ---
 
-# Quick Start
-
 This guide walks you through generating your first TypeScript client from an Anchor IDL.
 
 ## Step 1: Build Your Program
diff --git a/apps/docs/content/docs/why-coda.mdx b/apps/docs/content/docs/why-coda.mdx
@@ -3,8 +3,6 @@ title: Why Coda?
 description: Understanding the advantages of Coda over Anchor's built-in TypeScript client
 ---
 
-# Why Coda?
-
 While Anchor provides a built-in TypeScript client via [@coral-xyz/anchor](https://www.anchor-lang.com/docs/clients/typescript), Coda offers a modern alternative that addresses several limitations and provides additional features critical for production Solana applications.
 
 ## The Limitations of Anchor's TypeScript Client

Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,7 @@`
`6`	`6`	`"quick-start",`
`7`	`7`	`"why-coda",`
`8`	`8`	`"configuration",`
	`9`	`+ "examples",`
`9`	`10`	`"api"`
`10`	`11`	`]`
`11`	`12`	`}`