Contribution

This guide will help you understand how to contribute to our Docusaurus-based documentation website. Whether you're adding new content, fixing typos, or improving existing documentation, this guide covers everything you need to know.

📋 Table of Contents

Getting Started
Project Structure
Writing Documentation
Best Practices
Adding New Pages
Working with Categories
Code Examples
Assets and Images
Local Development
Submission Guidelines

🚀 Getting Started

Prerequisites

Node.js 18+
Git
Text editor (VS Code recommended)

Setup

Clone the repository
```
git clone <repository-url>
cd my-website
```
Install dependencies
```
npm install
```
Start development server
```
npm start
```

The site will be available at http://localhost:3000 with hot reloading enabled.

📁 Project Structure

Our documentation follows this structure:

docs/
├── index.md                    # Homepage content
├── contribution.md             # This file
├── be/                        # Backend documentation
│   ├── _category_.json        # Category configuration
│   └── golang/               # Go-specific docs
├── db/                       # Database documentation
├── de/                       # DevOps/Deployment docs
├── fe/                       # Frontend documentation
│   └── react/               # React-specific docs
└── qa/                       # Quality Assurance docs

Key Files

docusaurus.config.ts - Main configuration file
sidebars.ts - Navigation structure
package.json - Dependencies and scripts
static/ - Static assets (images, files)
src/ - Custom components and pages

✍️ Writing Documentation

Markdown Basics

All documentation is written in Markdown with MDX support. Here are the essentials:

Headers

# H1 - Page Title
## H2 - Major Section
### H3 - Subsection
#### H4 - Minor Section

Text Formatting

**Bold text**
*Italic text*
`Inline code`
~~Strikethrough~~

Lists

- Unordered list item
- Another item
  - Nested item

1. Ordered list item
2. Second item
   1. Nested ordered item

Links

[Internal link](./other-page.md)
[External link](https://example.com)
[Link with title](https://example.com "Tooltip text")

Docusaurus-Specific Features

Front Matter

Every document should start with front matter:

---
title: Page Title
description: Brief description for SEO
sidebar_position: 1
tags: [tag1, tag2]
---

# Page Content Starts Here

Admonitions

Use these for important information:

:::note
This is a note admonition.
:::

:::tip
This is a tip admonition.
:::

:::warning
This is a warning admonition.
:::

:::danger
This is a danger admonition.
:::

:::info
This is an info admonition.
:::

Code Blocks with Syntax Highlighting

```javascript title="example.js"
function greet(name) {
  return `Hello, ${name}!`;
}

Tabs

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

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

📝 Best Practices

Writing Style

Use clear, concise language
- Write for your audience's technical level
- Avoid jargon when possible
- Define technical terms when first used
Structure your content
- Use descriptive headers
- Keep paragraphs short (3-4 sentences)
- Use bullet points and numbered lists
Be consistent
- Follow existing naming conventions
- Use the same terminology throughout
- Match the tone of existing documentation

Technical Guidelines

Code examples should be
- Complete and runnable
- Well-commented
- Follow language-specific conventions
- Include error handling where appropriate
Always include
- Prerequisites
- Step-by-step instructions
- Expected outcomes
- Troubleshooting tips

📄 Adding New Pages

1. Create the Markdown File

Create a new .md file in the appropriate directory:

# For a new React guide
touch docs/fe/react/new-guide.md

2. Add Front Matter

---
title: Your Page Title
description: Brief description of the page content
sidebar_position: 3
tags: [react, frontend, tutorial]
---

# Your Page Title

Page content goes here...

If you want the page to appear in a specific order, update the sidebar_position in the front matter or modify sidebars.ts.

📂 Working with Categories

Creating a New Category

Create the directory
```
mkdir docs/new-category
```

Add category configuration

docs/new-category/_category_.json
{
  "label": "New Category",
  "position": 5,
  "link": {
    "type": "generated-index",
    "description": "Description of this category"
  }
}

Category Configuration Options

{
  "label": "Display Name",           // Shown in sidebar
  "position": 1,                    // Order in sidebar
  "collapsed": false,               // Initially expanded
  "collapsible": true,             // Can be collapsed
  "className": "custom-category",   // CSS class
  "link": {
    "type": "generated-index",      // Auto-generate index
    "description": "Category description"
  }
}

💻 Code Examples

Inline Code Snippets

For file paths, commands, or short code: npm install

Code Blocks

docusaurus.config.ts
const config: Config = {
  title: 'My Documentation',
  url: 'https://my-docs.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.ts',
        },
      },
    ],
  ],
};

Interactive Examples

For live code examples, consider using CodeSandbox or similar:

<iframe src="https://codesandbox.io/embed/..."
        style={{width:"100%", height:"500px", border:"0", borderRadius: "4px", overflow:"hidden"}}
        title="Example">
</iframe>

🖼️ Assets and Images

Adding Images

Place images in static/img/

static/img/
├── screenshots/
├── diagrams/
└── icons/

Reference in markdown

![Alt text](/img/screenshot.png)

<!-- With caption -->
![Architecture diagram](/img/diagrams/architecture.png "System Architecture")

Using assets with import

import MyImage from '/img/my-image.png';

<img src={MyImage} alt="Description" width="500" />

Image Best Practices

Use descriptive alt text
Optimize file sizes (use WebP when possible)
Use consistent naming conventions
Organize images in folders by category

🔧 Local Development

Development Workflow

Start the development server
```
npm start
```
Make your changes
- Edit markdown files
- Add new pages or assets
- Update configurations
Preview changes
- Changes auto-reload in browser
- Check navigation and formatting
- Test all links
Build for production (optional)
```
npm run build
npm run serve
```

Common Commands

# Start development server
npm start

# Build static site
npm run build

# Serve built site locally
npm run serve

# Clear cache
npm run clear

# Type checking
npm run typecheck

# Generate heading IDs
npm run write-heading-ids

Troubleshooting

Broken links: Check the console for broken link warnings and fix them.

Build failures: Run npm run build to catch issues before deployment.

Cache issues: Run npm run clear to clear Docusaurus cache.

📋 Submission Guidelines

Before Submitting

Test locally
- Run npm start and verify your changes
- Check all links work
- Ensure images load correctly
Follow conventions
- Use consistent formatting
- Follow existing file naming patterns
- Add appropriate front matter
Review content
- Check spelling and grammar
- Verify technical accuracy
- Ensure clarity and completeness

Pull Request Process

Create a feature branch
```
git checkout -b docs/your-feature-name
```

Make your changes

git add .
git commit -m "docs: add guide for X feature"

Push and create PR
```
git push origin docs/your-feature-name
```
Fill out PR template
- Describe what you changed
- Link to any related issues
- Add screenshots if relevant

Commit Message Format

docs: brief description of change

- Add new section about X
- Fix typo in Y
- Update screenshots for Z

Review Process

All changes require review
Documentation team will check for accuracy
Changes may be requested before merge
Once approved, changes will be deployed automatically

🎯 Quality Standards

Content Quality

Accuracy: All information must be correct and up-to-date
Completeness: Cover all necessary steps and information
Clarity: Use simple, clear language
Consistency: Follow established patterns and conventions

Technical Quality

Working examples: All code must work as shown
Cross-platform: Consider different operating systems
Version compatibility: Specify version requirements
Error handling: Include common troubleshooting

🤝 Getting Help

Resources

Contact

Technical questions: Open an issue in the repository
Content questions: Tag the documentation team
Urgent issues: Contact the maintainers directly

Thank you for contributing to our documentation! Your efforts help make our project more accessible and useful for everyone. 🙏

📋 Table of Contents​

🚀 Getting Started​

Prerequisites​

Setup​

📁 Project Structure​

Key Files​

✍️ Writing Documentation​

Markdown Basics​

Headers​

Text Formatting​

Lists​

Links​

Docusaurus-Specific Features​

Front Matter​

Admonitions​

Code Blocks with Syntax Highlighting​

Tabs​

📝 Best Practices​

Writing Style​

Technical Guidelines​

📄 Adding New Pages​

1. Create the Markdown File​

2. Add Front Matter​

3. Update Navigation (if needed)​

📂 Working with Categories​

Creating a New Category​

Category Configuration Options​

💻 Code Examples​

Inline Code Snippets​

Code Blocks​

Interactive Examples​

🖼️ Assets and Images​

Adding Images​

Image Best Practices​

🔧 Local Development​

Development Workflow​

Common Commands​

Troubleshooting​

📋 Submission Guidelines​

Before Submitting​

Pull Request Process​

Commit Message Format​

Review Process​

🎯 Quality Standards​

Content Quality​

Technical Quality​

🤝 Getting Help​

Resources​

Contact​