Skip to Content
DevelopmentContributingManaging Documentation

Managing Documentation

This guide explains how to manage and maintain the Rhesis documentation site built with Nextra.

Documentation Management Learn how to run the documentation site, add new pages, configure search, and maintain the documentation effectively.

Quick Start

Running the Documentation

There are multiple ways to run the Rhesis documentation site. Choose the method that works best for your workflow.

The easiest way to run the documentation is using our CLI tool from the project root:

code.txt
# From the project root directory
./rh docs start

This command will:

  • Navigate to the docs directory automatically
  • Install dependencies if needed
  • Start the development server on port 3001
  • Provide status feedback

Method 2: Manual Steps

If you prefer to run the documentation manually or need more control:

code.txt
# Navigate to docs directory
cd apps/documentation

# Install dependencies (if not already done)
npm install

# Start development server
npm run dev

The documentation will be available at: http://localhost:3001 

Method 3: Additional Commands

code.txt
# Build for production
npm run build

# Start production server (after building)
npm run start

# Run linting (if available)
npm run lint

# Check for outdated dependencies
npm outdated

Verification

Once the server is running, you can verify it’s working correctly:

code.txt
# Check if the server is responding
curl -s -o /dev/null -w "%{http_code}" http://localhost:3001

# Expected output: 200

Troubleshooting

Port Conflicts:

code.txt
# Check what's using port 3001
lsof -i :3001

# Kill the process if needed
kill -9 <PID>

# Or use a different port
PORT=3002 npm run dev

Dependencies Issues:

code.txt
# Clear npm cache
npm cache clean --force

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Documentation URLs - Development: http://localhost:3001  - Production: After build, served on configured domain - Search: Available after build (Pagefind indexing)

Project Structure

The documentation is organized using Nextra’s file-based routing:

Documentation Structure
apps/documentation/
├── app/                    # Next.js App Router pages
│   ├── page.mdx           # Home page (/)
│   ├── docs/              # Documentation pages (/docs/*)
│   │   ├── page.mdx       # Docs overview (/docs)
│   │   ├── backend/       # Backend documentation
│   │   ├── frontend/      # Frontend documentation
│   │   ├── contributing/  # Contributing guide
│   │   └── ...
│   └── layout.jsx         # Root layout
├── components/            # Custom React components
├── public/               # Static assets (images, etc.)
├── theme.config.jsx      # Nextra theme configuration
├── mdx-components.js     # MDX component customization
└── package.json         # Dependencies and scripts

Adding New Pages

Creating a New Page

  1. Create a new .mdx file in the appropriate directory:
code.txt
# Example: Create a new API documentation page
touch apps/documentation/app/docs/backend/api.mdx
  1. Add content to the page:
apps/documentation/app/docs/backend/api.mdx
# API Reference

Welcome to the Rhesis API reference documentation.

<Callout type="default">
**API Overview** This page provides comprehensive documentation for all Rhesis
API endpoints.
</Callout>

## Authentication

All API requests require authentication using JWT tokens.

## Endpoints

### Users

#### GET /api/users

Retrieve a list of users.

**Parameters:**

- `page` (optional): Page number for pagination
- `limit` (optional): Number of items per page

**Response:**

```json
{
"data": [
    {
      "id": "1",
      "email": "user@example.com",
      "name": "John Doe"
    }
],
"total": 100,
"page": 1,
"pageSize": 20
}
```

## Error Handling

All endpoints return consistent error responses:

```json
{
"error": "Error message",
"code": "ERROR_CODE",
"details": {}
}
```

Page Organization

Backend Docs

API documentation, architecture, and backend guides.

Frontend Docs

Component library, state management, and frontend guides.

Development

Setup guides, coding standards, and contribution guidelines.

User Guides

Tutorials, how-to guides, and user documentation.

API Reference

Complete API endpoint documentation.

Architecture

System design and architectural documentation.

Using Nextra Components

Callout Components

Nextra provides built-in callout components for highlighting information:

Callout Examples
<Callout type="default">
**Default Callout**
This is a standard informational callout.
</Callout>

<Callout type="warning">
**Warning Callout**
This is a warning callout for important notices.
</Callout>

<Callout type="error">
**Error Callout**
This is an error callout for critical issues.
</Callout>

Grid Layouts

Use CSS Grid for responsive layouts:

Grid Layout Example
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
<div>
    <h3>Feature 1</h3>
    <p>Description of the first feature.</p>
</div>
<div>
    <h3>Feature 2</h3>
    <p>Description of the second feature.</p>
</div>
<div>
    <h3>Feature 3</h3>
    <p>Description of the third feature.</p>
</div>
</div>

Code Blocks

Use syntax highlighting for code examples:

Python Code Block Example
```python
def create_user(user_data: UserCreate, db: Session) -> User:
    """Create a new user in the database."""
    user = User(**user_data.dict())
    db.add(user)
    db.commit()
    db.refresh(user)
    return user
```
TypeScript Example
const createUser = async (userData: UserCreate): Promise<User> => {
const response = await fetch("/api/users", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(userData),
});
return response.json();
};

Configuration

Theme Configuration

The theme.config.jsx file controls the documentation appearance:

theme.config.jsx
import ThemeAwareLogo from './components/ThemeAwareLogo'

export default {
logo: <ThemeAwareLogo />,
project: {
    link: 'https://github.com/rhesis-ai/rhesis',
},
docsRepositoryBase: 'https://github.com/rhesis-ai/rhesis',
footer: {
    text: '© 2025 Rhesis AI GmbH. Made in Germany.',
},
useNextSeoProps() {
    return {
      titleTemplate: '%s – Rhesis'
    }
},
head: (
    <>
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <meta property="og:title" content="Rhesis Documentation" />
      <meta property="og:description" content="AI-powered testing and evaluation platform" />
    </>
),
banner: {
    key: 'rhesis-docs',
    text: 'Welcome to Rhesis Documentation'
},
}

MDX Components

Customize MDX rendering in mdx-components.js:

mdx-components.js
import { useMDXComponents as getThemeComponents } from "nextra-theme-docs";

const themeComponents = getThemeComponents();

export function useMDXComponents(components) {
return {
    ...themeComponents,
    ...components,
    Callout,
};
}

Search Functionality

Nextra 4 uses Pagefind for full-text search:

Search Note Search is only available after building the documentation. During development, you’ll see a message indicating that search requires a build.

code.txt
# Build the documentation
npm run build

# This automatically runs Pagefind indexing
# The search index is generated in public/_pagefind/

Search Configuration

The search is automatically configured in package.json:

package.json
{
  "scripts": {
    "postbuild": "pagefind --site .next/server/app --output-path public/_pagefind"
  }
}

Development Workflow

Local Development

code.txt
# Start development server
npm run dev

# The server will be available at http://localhost:3001
# Changes are automatically reflected

Building and Deploying

code.txt
# Build for production
npm run build

# Start production server
npm run start

# Or deploy to your hosting platform
# The built files are in .next/ and public/

Continuous Integration

For automated documentation deployment:

.github/workflows/docs.yml
# .github/workflows/docs.yml
name: Deploy Documentation

on:
push:
    branches: [main]
    paths: ["apps/documentation/**"]

jobs:
deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: "18"
      - run: cd apps/documentation && npm install
      - run: cd apps/documentation && npm run build
      - name: Deploy to hosting platform
        # Add your deployment steps here

Content Guidelines

Writing Style

Clear and Concise

Write in a clear, straightforward manner.

Consistent Formatting

Use consistent headings, lists, and code blocks.

Examples

Include practical examples and code snippets.

Progressive Disclosure

Start with basics, then add advanced topics.

Cross-references

Link to related pages and external resources.

Markdown Best Practices

Markdown Best Practices
# Use proper heading hierarchy

## Section headings

### Subsection headings

# Use lists for better readability

- First item
- Second item
- Third item

# Use code blocks with language specification

```python
def example():
    return "Hello, World!"
```

# Use links for navigation

[Backend API](/development/backend/api-structure)

# Use images with alt text

![Rhesis Logo](/logo/rhesis-Logo-rgb-main-logo.png "Rhesis Logo")

Troubleshooting

Common Issues

Build Issues If you encounter build errors, check:

  • All dependencies are installed
  • MDX syntax is correct
  • No circular imports in components
  • Environment variables are set correctly

Search Not Working:

code.txt
# Ensure Pagefind is installed
npm install pagefind

# Rebuild the documentation
npm run build

# Check that _pagefind directory exists
ls public/_pagefind/

Styling Issues:

code.txt
# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Restart development server
npm run dev

Performance Optimization

Image Optimization

Use optimized images and Next.js Image component.

Code Splitting

Nextra automatically handles code splitting.

Caching

Configure proper caching headers for static assets.

Maintenance

Regular Tasks

Maintenance Checklist - Update dependencies regularly - Review and update outdated content - Check for broken links - Optimize images and assets - Monitor search functionality

Content Updates

  1. Review existing content for accuracy
  2. Update outdated information and examples
  3. Add new features and API endpoints
  4. Remove deprecated content
  5. Improve navigation and cross-references

Version Management

code.txt
# Create a new documentation version
git checkout -b docs/update-api-reference

# Make your changes
# Test locally
npm run dev

# Build and test
npm run build
npm run start

# Commit and push
git add .
git commit -m "docs: update API reference with new endpoints"
git push origin docs/update-api-reference

Need Help? If you need assistance with documentation: - Check the Nextra documentation  - Review existing pages for examples

Coding StandardsOverview