Contributing to Documentation

This section covers how to contribute documentation to Hyperion Docs.

Documentation Structure

Multi-Project Organization

The documentation is organized to support multiple projects:

content/
├── _contributing/                 # Contributing documentation (this section)
│   └── docs/
│       ├── guides/               # Usage guides
│       └── templates/            # Document templates
│
├── project-1/                    # First project
│   ├── docs/                     # MDX documentation
│   │   ├── architecture/
│   │   ├── agreement/
│   │   └── process/
│   ├── diagrams/                 # PlantUML, Mermaid files
│   └── openapi/                  # OpenAPI specs
│
└── project-2/                    # Second project (same structure)

Project Directory Structure

Each project follows this structure:

project-name/
├── docs/
│   ├── index.mdx                 # Project overview
│   ├── architecture/             # Architecture documentation
│   │   ├── adr/                  # Architecture Decision Records
│   │   ├── c4/                   # C4 Model diagrams
│   │   ├── erd/                  # Entity Relationship Diagrams
│   │   ├── solution-designs/     # Feature/solution designs
│   │   ├── sequence/             # Sequence diagrams
│   │   └── strategy/             # Strategic documents
│   │
│   ├── agreement/                # Technical agreements & standards
│   └── process/                  # Process documentation
│
├── diagrams/                     # Diagram source files
│   ├── architecture/             # Match docs structure
│   └── themes/                   # PlantUML themes
│
└── openapi/                      # OpenAPI spec files

File Placement Conventions

• ADRs: Architecture Decision Records in docs/architecture/adr/
• Solution Designs: Feature designs with test designs in docs/architecture/solution-designs/{number}/
• Sequence Diagrams: Organized by client in docs/architecture/sequence/{client}/
• Agreements: Technical standards in docs/agreement/
• Process: Workflow documentation in docs/process/
• Index files: Each subdirectory should have an index.mdx as the overview page

File Naming Conventions

MDX Files

• Use kebab-case: my-document.mdx
• Use descriptive names: create-customer.mdx not create.mdx
• Index files: Always named index.mdx

Diagram Files

• Use kebab-case: system-architecture.puml
• Include descriptive names: processing-flow.puml not flow.puml
• Extensions:
  • PlantUML: .puml
  • Graphviz: .dot

Subdirectories

• Use kebab-case: solution-design/, seq/
• Use descriptive names

Frontmatter Standards

Every MDX file must include frontmatter:

Required Fields

---
title: Page Title
description: Brief description of the page content
---

Optional Fields

---
title: Page Title
description: Brief description of the page content
icon: IconName # Lucide icon name (e.g., Book, Network, Code)
---

Guidelines

• Title: Use title case, concise and descriptive
• Description: One sentence summary, plain text
• Icon: Use Lucide React icon names when applicable

Navigation Configuration

Navigation is configured using meta.json files in each directory. If mdx file is not added to meta.json, it's not displayed in PageTree sidebar.

Structure

{
  "title": "Section Title",
  "pages": [
    "page-filename",
    "---Section Separator---",
    "another-page",
    "subdirectory"
  ]
}

Guidelines

• title: The section title displayed in navigation
• pages: Array of page filenames (without .mdx) and separators
• Separators: Use "---Text---" format for visual separators
• Order: Pages appear in the order listed
• Subdirectories: Include directory names to link to nested sections

MDX Components

Diagram Component

External Diagram Files (PlantUML, Graphviz, C4)

<Diagram
  lang="plantuml"
  path="project-name/relative/path/to/diagram.puml"
  alt="Descriptive alt text"
/>

Parameters:

• lang: Diagram language (plantuml, puml, graphviz, dot, c4plantuml)
• path: Path from /content directory with project prefix
• alt: Accessibility text describing the diagram

Inline Diagrams (Mermaid)

<Diagram
  lang="mermaid"
  chart="
graph TD;
  A[Start] --> B[Process];
  B --> C[End];
  "
/>

See Diagram Guide for detailed diagram usage.

OpenAPI Integration

File Location

Place OpenAPI specification files in your project's openapi/ directory:

content/project-name/openapi/
└── {resource}.yaml

Build Process

pnpm build:openapi

This scans all projects and generates MDX files in each project's docs folder.

Security Guidelines

Diagram Files

• Size Limits: Maximum 256 KB per file (after includes)
• Path Validation: All paths must be within /content directory
• Language Allowlist: Only supported diagram types accepted

Content Guidelines

• Never include API keys, tokens, or credentials
• Use placeholder values in examples
• Sanitize any data before including in documentation

Common Commands

# Start development
pnpm dev

# Generate OpenAPI docs
pnpm build:openapi

# Type checking
pnpm typecheck

# Linting
pnpm lint