Skip to content
This repository was archived by the owner on Jun 13, 2026. It is now read-only.

CONTRIBUTING.md

Latest commit

 

History

History
191 lines (145 loc) · 6.23 KB

CONTRIBUTING.md

File metadata and controls

191 lines (145 loc) · 6.23 KB
Raw

Contributing to Radio-Actief Documentation

Thank you for your interest in contributing to the Radio-Actief documentation platform! This guide will help you understand how to work with our Docusaurus-based documentation site.

Quick Start

  1. Fork and clone the repository
  2. Navigate to project directory: cd radio-actief/
  3. Install dependencies: npm install
  4. Start development server: npm start
  5. Test full build locally (optional but recommended):
    • Run npm run build to create a production build
    • Run npm run serve to preview the production build locally
    • Note: All npm commands must be run from the radio-actief/ directory
  6. Read the guides below to understand our workflow

Documentation Structure

Language Priority

  • Default Language: Dutch (Flemish) - nl - ALWAYS START HERE
  • Supported Languages: Dutch (nl), English (en), French (fr)

File Locations

  • Dutch documentation: radio-actief/docs/{category}/{filename}.mdx
  • English translations: radio-actief/i18n/en/docusaurus-plugin-content-docs/current/{category}/{filename}.mdx
  • French translations: radio-actief/i18n/fr/docusaurus-plugin-content-docs/current/{category}/{filename}.mdx

Documentation Categories

  • CB Radio (docs/cb/) - Citizens Band documentation
  • PMR446 / Walkietalkies (docs/pmr446/) - PMR446 / Walkie-talkies documentation
  • MeshCore (docs/meshcore/) - MeshCore networking documentation
  • Hardware (docs/hardware/) - Hardware documentation
  • HAM / Shortwave (docs/ham/) - HAM / Shortwave radio documentation

Workflow Rules

⚠️ CRITICAL: Sequential Translation Workflow

MANDATORY SEQUENCE:

  1. ✅ Step 1: Create complete Dutch version first
  2. ✅ Step 2: If ready and having a final version, translate to English and French (only after Dutch is complete)

Why This Matters

  • Ensures quality and consistency
  • Prevents incomplete translations
  • Makes review process manageable
  • Maintains technical accuracy

File Format

  • Always use .mdx extension for new documentation files
  • MDX supports Markdown + React components
  • Use .md only if you have a specific reason

Adding New Documentation

Step 1: Create Dutch Version

  1. Navigate to the appropriate category folder: radio-actief/docs/{category}/
  2. Create file with .mdx extension
  3. Add frontmatter at the top: 
    ---
sidebar_position: 2
---
  4. Write complete content in Dutch (Flemish)
  5. Review and finalize before proceeding

Step 2: Translate to English and French

Prerequisite: Dutch version must be complete, reviewed, and finalized.

Once you have a final Dutch version, you can translate to both English and French:

For English:

  1. Navigate to: radio-actief/i18n/en/docusaurus-plugin-content-docs/current/
  2. Mirror the folder structure from Dutch version
  3. Copy frontmatter exactly (must be identical)
  4. Translate all content accurately from Dutch
  5. Preserve structure, headings, and code blocks

For French:

  1. Navigate to: radio-actief/i18n/fr/docusaurus-plugin-content-docs/current/
  2. Mirror the folder structure
  3. Copy frontmatter exactly (must be identical)
  4. Translate from Dutch to French
  5. Preserve structure, headings, and code blocks

Note: English and French translations can be done in parallel after Dutch is complete, or sequentially - whichever works best for you.

Frontmatter Guidelines

Frontmatter must be identical across all three language versions. Only the content differs.

---
sidebar_position: 2          # Number: Lower = appears first
title: "Page Title"          # String: Override H1 title
sidebar_label: "Short Name"  # String: Custom sidebar label
description: "SEO summary"   # String: Brief description
tags:                        # Array: For categorization
  - tag1
  - tag2
---

Blog Posts

Blog posts follow a similar workflow but use different frontmatter:

Code of Conduct

  • Write in clear, accessible language
  • Maintain technical accuracy
  • Follow existing documentation style
  • Keep code examples identical across languages (don't translate code)
  • Use proper Markdown/MDX formatting

Review Process

Before submitting:

  • Dutch version is complete and reviewed
  • English version is complete and reviewed (if applicable)
  • French version is complete and reviewed (if applicable)
  • All frontmatter is identical across languages
  • File structure matches existing patterns
  • Links are valid and use relative paths
  • Code blocks are identical across all languages

Getting Help

Docusaurus Rules

File Naming

  • Use .mdx for all new documentation files
  • Blog posts: YYYY-MM-DD-slug.mdx
  • Category indexes: index.mdx (not intro.mdx)

Sidebar Configuration

  • Sidebar is configured in sidebars.js
  • Use sidebar_position in frontmatter to control order
  • Category headers link to index.mdx pages

Links

  • Internal: /docs/category/page
  • External: Full URLs with https://

Images

  • Place in static/img/
  • Reference as /img/filename.png

Admonitions (Callouts)

:::tip
Helpful tip
:::

:::warning
Warning message
:::

:::info
Informational content
:::

Project Structure

radio-actief/
├── docs/              # Dutch documentation (default)
├── blog/              # Blog posts
├── i18n/              # Translations (en, fr)
├── src/               # React components
├── static/             # Static assets
├── docusaurus.config.js
└── sidebars.js

Thank You!

Your contributions help make Radio-Actief documentation better for everyone. Thank you for taking the time to follow these guidelines!