Skip to main content

Documentation System

This repository uses a centralized documentation system built with Docusaurus and TypeDoc. It automatically aggregates documentation and API references from all packages in the monorepo into a single static site.

Technology Stack​

  • Documentation Framework: Docusaurus 3
  • API Documentation: TypeDoc with TypeDoc Plugin Markdown
  • Build System: Nx for orchestration
  • Component Docs: Storybook (embedded in docs site)
  • Languages: TypeScript, MDX (Markdown with JSX)

Overview​

  • Docs App: Located in apps/docs. This is the Docusaurus application that builds the site.
  • Automatic Discovery: The system scans the packages/ directory.
  • Convention-over-Configuration: Documentation is included based on the presence of specific files in each package.

How it Works​

The apps/docs/docusaurus.config.ts file dynamically generates configuration by scanning packages/*.

1. Markdown Documentation​

If a package contains a docs/ folder (e.g., packages/my-lib/docs), it is automatically added as a section in the documentation site.

  • The URL will be /<package-name>/.
  • The sidebar is auto-generated from the file structure in docs/.

2. API Reference (TypeDoc)​

If a package contains src/index.ts and tsconfig.json, API documentation is automatically generated from the TypeScript source code.

  • The output is placed in packages/<package-name>/docs/api.
  • It is accessible via the documentation sidebar under "API Reference" (or linked from your index page).

Adding Documentation for a Package​

To add documentation for a package (e.g., packages/shared-components):

  1. Create the docs folder:

    mkdir packages/shared-components/docs

  2. Add an index page: Create packages/shared-components/docs/index.md:

    ---
    sidebar_position: 1
    ---

    # Shared Components

    Welcome to the documentation for Shared Components.

    ## API Reference

    See the [API Reference](./api/).

  3. Ensure Exports: Make sure your src/index.ts exports the components or functions you want documented.

Running the Docs​

To start the documentation site locally:

nx serve docs

The site will be available at http://localhost:3000.

Run the docs server with automatic reloading when dependencies change:

nx run docs:dev

This command:

  • Watches the docs project and all its dependencies for changes
  • Automatically restarts the docs server when changes are detected
  • Rebuilds dirty dependencies before restarting

Documentation Structure​

The documentation follows this structure:

substrate/
├── README.md              # Root README (overview, navigation)
│
├── apps/
│   ├── docs/
│   │   ├── README.md      # Contributor guide for docs app
│   │   ├── docs/          # Core documentation (not package-specific)
│   │   │   ├── component-architecture.md
│   │   │   ├── documentation.md
│   │   │   └── ...
│   │   └── src/           # Docusaurus source
│   │
│   ├── placeholder/
│   │   └── README.md      # Contributor guide for placeholder app
│   │
│   └── web/
│       └── README.md      # Contributor guide for web app
│
└── packages/
    ├── shared-components/
    │   ├── README.md      # Contributor guide
    │   └── docs/          # User documentation (built to docs site)
    │
    ├── shared-db/
    │   ├── README.md      # Contributor guide
    │   └── docs/          # User documentation (built to docs site)
    │
    └── [other packages...]
        ├── README.md      # Contributor guide
        └── docs/          # User documentation (built to docs site)

Documentation Guidelines​

README.md Files (For Contributors)​

README files are for contributors. They should include:

  1. Brief overview of the package/app
  2. Link to detailed docs site (if applicable)
  3. Commands for building, testing, linting
  4. Environment variables and configuration
  5. Development workflow and guidelines
  6. Cross-references to related READMEs

Example structure:

# Package Name

Brief description and link to docs site.

## Contributing

### Prerequisites

- Required tools and knowledge

### Commands

```bash
# Common development commands
```

Environment Variables​

VariableDescriptionDefault
VAR_NAMEDescriptionvalue

Project Structure​

Brief overview of key directories

  • Links to other READMEs

### docs/ Folders (For Users)

Documentation in `docs/` folders is for **users** of the package. It should include:

1. Overview of features and capabilities
2. Usage examples and code snippets
3. API documentation (link to generated API docs)
4. Best practices and patterns
5. Migration guides (if applicable)

## Building the Docs Site

```bash
# Build the complete documentation site
nx build docs

# The output will be in `dist/docs`