Contributing to Documentation

This guide explains how to contribute to the Nudg3 API documentation. Whether you're fixing a typo or adding new content, we appreciate your help!

Getting Started

Prerequisites

Node.js 18+
pnpm 8+
Git

Local Development

Clone the repository:

git clone https://github.com/nudg3/nudg3-frontend-combined.git
cd nudg3-frontend-combined

Install dependencies:

pnpm install

Start the docs development server:

pnpm dev:docs

Open http://localhost:3004 in your browser

Content Structure

Documentation is organized in apps/docs/content/docs/:

content/docs/
├── index.mdx                    # Welcome page
├── meta.json                    # Navigation structure
├── getting-started/
│   └── index.mdx               # Quick start guide
├── authentication/
│   └── index.mdx               # Auth documentation
├── api/
│   ├── index.mdx               # API overview
│   └── analytics/              # Analytics endpoints
├── how-to/
│   ├── index.mdx               # How-to overview
│   ├── onboarding/             # Onboarding guides
│   └── analytics/              # Analytics guides
├── errors/
│   └── index.mdx               # Error reference
└── contributing/
    └── index.mdx               # This file

Writing Content

File Format

All documentation is written in MDX (Markdown + JSX):

---
title: Page Title
description: Brief description for SEO
---
 
# Page Title
 
Your content here...

Frontmatter

Every MDX file requires frontmatter:

Field	Required	Description
`title`	Yes	Page title (shown in sidebar and browser tab)
`description`	Yes	Brief description for SEO and search
`full`	No	Set to `true` for full-width layout

Update content/docs/meta.json when adding new pages:

{
  "title": "Documentation",
  "root": true,
  "pages": [
    "---Section Name---",
    "page-slug",
    "folder/page-slug"
  ]
}

MDX Components

Callouts

Use callouts to highlight important information:

<Callout type="info">
  Informational note
</Callout>
 
<Callout type="warning">
  Warning message
</Callout>
 
<Callout type="error">
  Error or danger message
</Callout>

Renders as:

Informational note

Warning message

Cards

Use cards for navigation:

<Cards>
  <Card
    title="Card Title"
    href="/docs/path"
    description="Brief description"
  />
</Cards>

Code Blocks

Always specify the language:

```bash
curl https://api.nudg3.ai/api/v1/endpoint
```
 
```javascript
const data = await fetch('/api/endpoint');
```
 
```python
response = requests.get('/api/endpoint')
```
 
```json
{
  "key": "value"
}
```

Content Guidelines

Writing Style

Be concise: Get to the point quickly
Use active voice: "Send a request" not "A request should be sent"
Include examples: Show, don't just tell
Use proper headings: H1 for title, H2 for sections, H3 for subsections

AI-Friendly Content

Our documentation is designed for AI agents (RAG systems). Follow these patterns:

Clear structure: Use consistent heading hierarchy
Semantic HTML: Tables for data, lists for steps
Code examples: Include working code snippets
No complex components: Keep MDX simple
Related links: Add cross-references at bottom of pages

API Documentation Pattern

When documenting API endpoints, use this template:

# Endpoint Name
 
Brief description of what the endpoint does.
 
## Endpoint
 
\`\`\`
METHOD /api/v1/path
\`\`\`
 
## Authentication
 
Required scope: `scope:name`
 
## Parameters
 
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| param_name | string | Yes | What this parameter does |
 
## Request Body
 
\`\`\`json
{
  "field": "value"
}
\`\`\`
 
## Response
 
\`\`\`json
{
  "data": {}
}
\`\`\`
 
## Errors
 
| Code | Message | Solution |
|------|---------|----------|
| 400 | Bad Request | How to fix |
 
## Example
 
\`\`\`bash
curl -X METHOD https://api.nudg3.ai/api/v1/path \\
  -H "Authorization: Bearer nudg3_live_ak_xxx"
\`\`\`

Pull Request Process

Create a branch:

git checkout -b docs/your-change-description

Make your changes in apps/docs/content/docs/
Test locally:

pnpm dev:docs
# Verify your changes at http://localhost:3004

Build to check for errors:

pnpm build:docs

Commit your changes:

git add .
git commit -m "docs: your change description"

Push and create PR:

git push origin docs/your-change-description

Common Tasks

Adding a New Page

Create MDX file in appropriate directory
Add frontmatter with title and description
Update meta.json navigation
Add links from related pages

Updating API Documentation

Check backend for latest endpoint details
Update relevant MDX file
Verify code examples work
Update OpenAPI spec if needed

Fixing Typos

Find the MDX file in content/docs/
Make the correction
Commit with message: docs: fix typo in [page-name]

Need Help?

Documentation issues: Open a GitHub issue
Technical questions: Ask in the development Slack channel
Fumadocs help: See Fumadocs documentation

Contributing to Documentation

On this page