Template Project - How to Add a New Project

This template folder (template-project) contains the structure and files needed to create a new project documentation. Follow these steps to add a new project to the documentation.

Quick Start

1. Copy the template folder:

   cp -r docs/template-project docs/your-project-name

2. Replace placeholders in all files:

   • Replace [Project Name] with your actual project name
   • Replace [package-name] with your actual package name
   • Replace [brief description] with your project description
   • Update all example code and configurations

3. Update the sidebar in sidebars.js (see instructions below)

4. Test your documentation:

   npm run start

Step-by-Step Instructions

Step 1: Create Project Folder

Create a new folder in docs/ with your project name (use kebab-case):

# Example: for "Project Gamma"
cp -r docs/template-project docs/project-gamma

Naming Convention:

• Use lowercase
• Use hyphens for spaces (kebab-case)
• Keep it short and descriptive
• Examples: project-gamma, api-service, mobile-app

Step 2: Update File Contents

Edit each file in your new project folder and replace:

Placeholder	Replace With
[Project Name]	Your project's display name
[package-name]	Your npm package name
[brief description]	One-line project description
[Component Name]	Actual component names
[Technology]	Actual technologies used

Files to update:

• overview.md - Project overview and introduction
• getting-started.md - Setup and installation guide
• architecture.md - System architecture and design
• api.md - API reference documentation

Step 3: Update Sidebar

Open sidebars.js and add your project to the sidebar structure:

const sidebars = {
  docsSidebar: [
    {
      type: 'category',
      label: 'Projects',
      items: [
        {
          type: 'category',
          label: 'Project Alpha',
          items: ['project-alpha/overview', 'project-alpha/setup', 'project-alpha/features'],
        },
        {
          type: 'category',
          label: 'Project Beta',
          items: ['project-beta/overview', 'project-beta/setup', 'project-beta/features'],
        },
        // Add your new project here
        {
          type: 'category',
          label: 'Project Gamma', // Your project name
          items: [
            'project-gamma/overview',
            'project-gamma/getting-started',
            'project-gamma/architecture',
            'project-gamma/api',
          ],
        },
      ],
    },
  ],
};

Step 4: Customize Content

1. Overview (overview.md):

   • Update the project description
   • List key features
   • Add a quick start example
   • Include architecture diagram if needed

2. Getting Started (getting-started.md):

   • Update installation steps
   • Add configuration examples
   • Include verification steps
   • Add troubleshooting section

3. Architecture (architecture.md):

   • Update architecture diagrams
   • Describe core components
   • Document design decisions
   • List technology stack

4. API (api.md):

   • Document all API endpoints
   • Include request/response examples
   • Add error codes
   • Include SDK examples

Step 5: Add Custom Files (Optional)

You can add additional files to your project folder:

• examples.md - Code examples and use cases
• troubleshooting.md - Common issues and solutions
• changelog.md - Version history
• contributing.md - Contribution guidelines

Remember to add these files to the sidebar in sidebars.js.

File Structure

Your project folder should follow this structure:

docs/
  your-project-name/
    overview.md          # Required: Project overview
    getting-started.md   # Required: Setup guide
    architecture.md      # Required: Architecture docs
    api.md              # Required: API reference
    [optional-files]    # Any additional documentation

Best Practices

1. Consistency: Follow the same structure and style as existing projects
2. Examples: Include code examples in all relevant sections
3. Diagrams: Use Mermaid diagrams for visual explanations
4. Callouts: Use the Callout component for important information
5. Code Blocks: Always include language tags for syntax highlighting
6. Links: Link between related documents
7. Testing: Test all code examples before publishing

Using Components

This boilerplate includes reusable components. Use them in your markdown:

Callout

import Callout from '@site/src/components/Callout';

<Callout type="info">
  This is an informational callout.
</Callout>

<Callout type="warning">
  This is a warning callout.
</Callout>

<Callout type="success">
  This is a success callout.
</Callout>

<Callout type="error">
  This is an error callout.
</Callout>

Badge

import Badge from '@site/src/components/Badge';

<Badge text="New" color="blue" />
<Badge text="Beta" color="orange" />
<Badge text="Stable" color="green" />

Highlight

import Highlight from '@site/src/components/Highlight';

<Highlight color="yellow">
  This text is highlighted.
</Highlight>

Mermaid Diagrams

You can use Mermaid diagrams in your markdown:

```mermaid
graph TB
    A[Start] --> B[Process]
    B --> C[End]
```

Tabs

Use tabs for multiple code examples:

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

<Tabs>
  <TabItem value="js" label="JavaScript">
    ```javascript
    console.log('Hello');
    ```
  </TabItem>
  <TabItem value="py" label="Python">
    ```python
    print('Hello')
    ```
  </TabItem>
</Tabs>

Checklist

Before considering your project documentation complete:

• All placeholders replaced with actual content
• Sidebar updated in sidebars.js
• All code examples tested and working
• Links between documents verified
• Mermaid diagrams render correctly
• Components used appropriately
• Documentation reviewed for clarity
• Local server tested (npm run start)

Need Help?

• Check existing projects (project-alpha, project-beta) for examples
• Review the main README.md for project structure guidelines
• Consult Docusaurus documentation: https://docusaurus.io/docs

Summary

Adding a new project is simple:

1. Copy _template-project folder
2. Rename to your project name
3. Replace placeholders in files
4. Update sidebars.js
5. Test and customize

That's it! Your new project documentation is ready.