Skip to main content

Contributing

Thank you for your interest in contributing to DPO2U documentation. This guide covers everything you need to set up a local development environment, create new pages, and submit changes.

Prerequisites​

Before you begin, ensure you have the following installed:

  • Node.js 20 or higher
  • npm 10 or higher
  • Git for version control
caution

The documentation site uses Docusaurus 3.9.2 with the Mermaid theme plugin. Ensure your Node.js version meets the minimum requirement to avoid build failures.

Local development​

1. Clone the repository​

git clone https://github.com/dpo2u/docs.git
cd docs

2. Install dependencies​

npm install

3. Start the development server​

npm run start

This starts a local server at http://localhost:3000 with hot-reloading enabled. Most changes reflect instantly without restarting the server.

4. Build for production​

npm run build

The build command validates all internal links and throws an error if any are broken. Always run this before submitting a pull request.

Repository structure​

docs-site/
├── docs/                    # Documentation pages (Markdown/MDX)
│   ├── intro.md
│   ├── architecture.md
│   ├── style-guide.md
│   ├── agents/
│   ├── tokenomics/
│   ├── smart-contracts/
│   └── ...
├── blog/                    # Dev Diaries (blog posts)
├── src/
│   ├── components/          # React components
│   ├── css/                 # Global styles
│   └── pages/               # Standalone pages (homepage)
├── static/                  # Static assets (images, icons)
├── docusaurus.config.js     # Site configuration
└── sidebars.js              # Sidebar navigation structure

Creating a new page​

1. Create the file​

Add a new .md or .mdx file in the appropriate docs/ subdirectory. Use kebab-case for filenames: my-new-page.md.

2. Add frontmatter​

---
sidebar_position: N
---

# Page Title

Introduction paragraph.

3. Register in the sidebar​

Open sidebars.js and add the document ID to the appropriate category:

{
  type: 'category',
  label: 'Category Name',
  items: ['existing-page', 'my-new-page'],
}

4. Write the content​

Follow the Style Guide for voice, tone, formatting, and terminology standards.

Using MDX features​

Admonitions​

:::tip
Your tip content here.
:::

Mermaid diagrams​

```mermaid
graph LR
    A[Start] --> B[End]
```

Tabs (requires .mdx extension)​

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="ts" label="TypeScript" default>
    TypeScript content here.
  </TabItem>
  <TabItem value="js" label="JavaScript">
    JavaScript content here.
  </TabItem>
</Tabs>

Review checklist​

Before submitting your changes, verify the following:

  • Content follows the Style Guide
  • Project-specific terminology matches the current style guide
  • Pages distinguish runtime truth from concept, research, or environment-dependent backend paths
  • Mermaid diagrams render in both light and dark mode
  • Internal links use relative paths (/docs/page, not full URLs)
  • Code blocks specify a language for syntax highlighting
  • npm run build completes with zero errors
  • New pages are registered in sidebars.js