Skip to main content

Contributing to Nexus Documentation

This guide explains how to add, edit, and regenerate Nexus documentation.

Directory structure​

docs-site/
  docs/              ← All documentation content (Markdown)
    overview/        ← Product overview pages
    concepts/        ← Data model and object definitions
    guides/how-to/   ← Step-by-step task guides
    integrations/    ← Per-integration documentation
    api/             ← API reference pages
    reference/
      database/      ← Auto-generated table pages
      functions/     ← Edge Functions reference
    faq/             ← Frequently asked questions
    _generated/      ← Auto-generated JSON data (do not edit)
    glossary.md      ← Term definitions
  static/            ← Static files (llms.txt, openapi.yaml)
  docusaurus.config.ts
  sidebars.ts

scripts/docs-gen/    ← Generation scripts
  config.ts          ← Shared configuration and canonical page list
  introspect_db.ts   ← Database schema introspection
  render_db_docs.ts  ← Generates Markdown from db-schema.json
  introspect_edge_functions.ts ← Scans Edge Functions
  render_llms.ts     ← Generates llms.txt and llms-full.txt

public/              ← Vite public assets (served at site root)
  llms.txt
  llms-full.txt
  openapi.yaml

Adding a new documentation page​

  1. Create a new .md file in the appropriate directory under docs-site/docs/.
  2. Add frontmatter with title and sidebar_position: 
    ---
    sidebar_position: 5
    title: My New Page
    ---
  3. If the page should appear in the sidebar, add its ID to docs-site/sidebars.ts.
  4. Follow the writing style guide below.

Adding a new guide​

Use this template for how-to guides:

---
sidebar_position: N
title: Guide Title
---

# Guide Title

## Goal
What the user will accomplish.

## Preconditions
What must be true before starting.

## Steps
1. Step one...
2. Step two...

## Expected result
What success looks like.

## Common issues
| Issue | Resolution |
|-------|-----------|
| ... | ... |

## Related docs
- [Link](./path)

Regenerating auto-generated docs​

# Regenerate all (DB schema, functions, llms.txt)
npm run docs:gen

# Individual scripts (from repo root)
npx tsx scripts/docs-gen/introspect_db.ts
npx tsx scripts/docs-gen/render_db_docs.ts
npx tsx scripts/docs-gen/introspect_edge_functions.ts
npx tsx scripts/docs-gen/render_llms.ts

Database reference​

Requires DOCS_DB_URL environment variable pointing to a read-only PostgreSQL connection string:

export DOCS_DB_URL="postgresql://docs_reader:password@host:5432/nexus"
npm run docs:gen

Without DOCS_DB_URL, the DB introspection is skipped and previously generated files are preserved.

Updating the OpenAPI spec​

  1. Edit public/openapi.yaml.
  2. Validate: npm run openapi:validate.
  3. The spec is copied to docs-site/static/ during npm run docs:gen.

Updating llms.txt​

  1. Edit the CANONICAL_PAGES array in scripts/docs-gen/config.ts.
  2. Run npm run docs:gen to regenerate.

Building and previewing docs​

# Install docs-site dependencies (first time)
cd docs-site && npm install && cd ..

# Dev server
npm run docs:dev

# Production build
npm run docs:build

Writing style guide​

  • Agent-friendly: Use explicit nouns. Say "the Contact record" not "it" or "the record".
  • Consistent terminology: Use terms from the Glossary. Prefer "Contact" over "Customer" in docs (even though the DB table is customers).
  • No ambiguity: Avoid words like "simply", "just", "easily". Be precise about what to click and where.
  • Synthetic examples only: Never use real customer data, names, phone numbers, or email addresses. Use clearly synthetic examples (e.g., fatima@example.com, +201234567890).
  • No secrets: Never include API keys, tokens, passwords, or internal URLs in documentation.
  • Consistent formatting: Use tables for structured data. Use code blocks for commands and identifiers. Use headings for scannability.