Documentation Application

The documentation application is built with Nextra, a Next.js-based documentation framework, to provide comprehensive platform documentation.

Overview

Package Name: @sustentus/docs Framework: Nextra (Next.js 15) Port: 3003 Path: apps/docs/

Purpose

This is the application you’re currently viewing! It provides:

Developer documentation
Architecture guides
API references
Tutorials and guides
Component documentation

Technology Stack

Core

Next.js 15: React framework
Nextra: Documentation framework
nextra-theme-docs: Documentation theme
React 19: UI library
TypeScript: Type safety

Features

Pagefind: Static search functionality
Vercel Analytics: Performance monitoring
MDX: Write docs with JSX components

Directory Structure


docs/
├── app/
│   ├── layout.tsx              # Nextra layout wrapper
│   ├── page.mdx                # Home page
│   ├── globals.css             # Global styles
│   ├── getting-started/        # Getting started docs
│   ├── architecture/           # Architecture docs
│   ├── applications/           # Application docs
│   ├── packages/               # Package docs
│   ├── development/            # Development guides
│   └── deployment/             # Deployment guides
├── public/
│   └── _pagefind/              # Search index (generated)
├── mdx-components.tsx          # Custom MDX components
├── next.config.ts              # Next.js + Nextra config
└── package.json

Key features

File-based routing: each .mdx file becomes a page; nested folders create the navigation hierarchy and sidebar automatically.
MDX: standard Markdown plus React components and syntax-highlighted code blocks.
Built-in search: Pagefind indexes all content during the build for fast, offline, dependency-free search.
Theme: nextra-theme-docs provides dark/light mode, responsive layout, automatic navigation, table of contents, and breadcrumbs.

Development

Running the App


# From root
pnpm docs:dev
 
# From docs directory
cd apps/docs
pnpm dev

The app runs on http://localhost:3003.

Building


# From root
pnpm docs:build
 
# From docs directory
cd apps/docs
pnpm build

The build runs next build, then a postbuild script runs Pagefind to generate the search index.

Configuration

`next.config.ts`

Minimal Nextra configuration:


import nextra from "nextra";
 
const withNextra = nextra({});
 
export default withNextra({});

`app/layout.tsx`

Nextra layout wrapper:


import { Footer, Layout, Navbar } from "nextra-theme-docs";
import { getPageMap } from "nextra/page-map";
 
const navbar = <Navbar logo={<b>Sustentus Docs</b>} />;
const footer = <Footer>MIT {new Date().getFullYear()} © Sustentus.</Footer>;
 
const RootLayout = async ({ children }) => (
  <html lang="en-GB" dir="ltr" suppressHydrationWarning>
    <body>
      <Layout navbar={navbar} pageMap={await getPageMap()} footer={footer}>
        {children}
      </Layout>
    </body>
  </html>
);

`mdx-components.tsx`

Custom MDX component overrides (currently empty but can be extended):


import type { MDXComponents } from "mdx/types";
 
export const useMDXComponents = (components: MDXComponents): MDXComponents => ({
  ...components,
  CustomComponent: (props) => <div {...props} />,
});

Writing Documentation

Create a .mdx file in the appropriate directory under app/ and it automatically appears in navigation. Use folders to create hierarchy — a page.mdx is the section landing page (e.g. app/guides/page.mdx → /guides, app/guides/advanced/page.mdx → /guides/advanced).

Link between pages with relative or absolute paths:


See the [Architecture](/technical/architecture) for more details.

The search index in public/_pagefind/ is regenerated automatically on every pnpm build:


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