Content Contribution Guidelines - Dzaleka Online Services

Thank you for contributing to Dzaleka Online Services! This guide will help you create properly formatted content that integrates seamlessly with the platform.

Getting Started

Choose a Collection

Determine which collection best fits your content. See the Collections Overview for details on each type.

Review the Schema

Check the Schema Reference for required and optional fields for your collection.

Create Your File

Follow the file naming and formatting guidelines below.

Submit Your Content

Submit via pull request or contact the platform administrators.

File Naming Conventions

General Rules

Use lowercase letters
Replace spaces with hyphens (-)
Use descriptive, meaningful names
Avoid special characters except hyphens
Keep names concise but clear

Examples

services/zawadie-solutions.md
events/tumaini-festival-2025.md
jobs/secondary-school-teachers.md
stores/mama-joys-kitchen.md
marketplace/refugee-for-life-book.md

services/Zawadie Solutions.md          # No spaces or capitals
events/event_123.md                    # Not descriptive
jobs/job!!!.md                         # No special characters
stores/store.md                        # Too generic

Collection-Specific Guidelines

Events

Include event name and year:

tumaini-festival-2025.md
refugee-self-advocacy-november-2025.md

Jobs

Use job title or role:

secondary-school-teachers.md
programs-manager.md
digital-archivist.md

Services/Stores

Use business name:

zawadie-solutions.md
mama-joys-kitchen.md
dowa-bakery.md

Marketplace

Use product/service name:

refugee-for-life-book.md
kibebe-baby-products.md

People (Artists, Dancers, Poets)

Use person or group name:

christian-piniero.md
shakers-dance-crew.md

Frontmatter Requirements

Structure

All content files must start with YAML frontmatter between triple dashes:

---
title: Your Title Here
description: Brief description
# ... other fields
---

Your markdown content here...

Required vs Optional Fields

Required fields must be present in every file. Missing required fields will cause validation errors.

Optional fields can be omitted entirely. Don’t include them with empty values unless necessary.

---
title: My Service
description: A great service
category: Education
# logo omitted since we don't have one
---

---
title: My Service
description: A great service
category: Education
logo: ''
featured: 
verified:
---

Field Formatting

Strings

Simple strings can be unquoted:

title: Zawadie Solutions
category: Entrepreneurship & Business

Quote strings with special characters:

title: "Mama Joy's Kitchen"
description: "Restaurant: Traditional & Modern Cuisine"

Dates

Use ISO 8601 format for date-time:

date: 2025-10-30T09:00:00Z
endDate: 2025-11-01T22:00:00Z

Or simple date format:

posted: 2023-05-01
deadline: 2023-05-31

Booleans

featured: true
verified: false

Arrays

tags: ["music", "dance", "arts"]
skills: ["Teaching", "Lesson Planning"]

tags:
  - music
  - dance
  - arts
  
skills:
  - Teaching
  - Lesson Planning
  - Classroom Management

Objects

contact:
  email: info@example.com
  phone: '+265 991 234 567'
  whatsapp: '+265 991 234 567'
  
location:
  address: Ubuntu Office
  city: Dzaleka Refugee Camp, Dowa
  coordinates:
    lat: -13.6628274
    lng: 33.8704301

Arrays of Objects

menu:
  - category: "Main Dishes"
    items:
      - name: "Fufu with Sombe"
        description: "Traditional cassava fufu"
        price: "2,500"
        popular: true
      - name: "Ugali with Fish"
        price: "3,000"
        
panelists:
  - name: "John Doe"
    role: "Keynote Speaker"
    bio: "Expert in refugee rights"
    organization: "UNHCR"
  - name: "Jane Smith"
    role: "Panelist"

Enums (Specific Values)

Some fields only accept specific values. Check the schema for allowed values:

type: full-time
# Allowed: full-time, part-time, contract, volunteer, internship

type: restaurant
# Allowed: restaurant, cafe, bakery, grocery, retail, salon, workshop, other

status: upcoming
# Allowed: upcoming, past

Markdown Content

Basic Formatting

After the frontmatter, write your content in Markdown:

---
title: My Content
---

## Main Heading

Your introduction paragraph...

### Subheading

- List item 1
- List item 2
- List item 3

**Bold text** and *italic text*.

[Link text](https://example.com)

> Blockquote for testimonials or important notes

## Another Section

More content...

Heading Levels

Start with ## (h2) for main sections. The # (h1) level is typically reserved for the page title.

## About Us          (h2 - main sections)
### Our Mission      (h3 - subsections)
#### Details         (h4 - sub-subsections)

Lists

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

First step
Second step
Third step

Links

[Dzaleka Online Services](https://dzaleka.com)
[Visit our website](https://example.com)

Email: <info@example.com>

Emphasis

*italic text* or _italic text_
**bold text** or __bold text__
***bold and italic*** or ___bold and italic___

Blockquotes

Great for testimonials:

> Tumaini Festival brings exceptional hope into the lives of people.

— Skeffa Chimoto, Musician

Code

Inline code: `code here` Code blocks:

```javascript
function hello() {
  console.log("Hello Dzaleka!");
}
```

Image Guidelines

Image Paths

Local Images
External URLs

Store images in the public/images/ directory:

image: /images/my-photo.jpg
logo: /images/logos/company-logo.png

The /images/ path maps to public/images/ in the project.

Use full URLs for externally hosted images:

image: https://example.com/photo.jpg
coverImage: https://images.unsplash.com/photo-123

Image Optimization

File Size

Aim for under 500 KB per image
Use compression tools
Consider WebP format

Dimensions

Logos: 200-400px wide
Thumbnails: 600-800px wide
Cover images: 1200-1600px wide

Format

Photos: JPG/JPEG
Graphics/logos: PNG or WebP
Avoid BMP, TIFF

Naming

Use descriptive names
Lowercase with hyphens
Example: tumaini-festival-2025.jpg

Organizing Images

Create subdirectories for better organization:

public/images/
├── events/
│   ├── tumaini-festival-2025.jpg
│   └── refugee-self-advocacy.jpg
├── services/
│   ├── zawadie-logo.png
│   └── ywam-photo.jpg
├── marketplace/
│   └── products/
│       ├── book-cover.jpg
│       └── handicraft-1.jpg
└── people/
    ├── artists/
    └── dancers/

Then reference:

image: /images/events/tumaini-festival-2025.jpg
logo: /images/services/zawadie-logo.png

Content Best Practices

Writing Style

Write clear, concise descriptions
Use active voice
Be specific and factual
Proofread for spelling and grammar
Use proper capitalization

Accessibility

Write descriptive alt text (coming soon)
Use clear heading hierarchy
Ensure sufficient contrast for images
Make links descriptive (“Visit Zawadie Solutions” not “click here”)

SEO Considerations

Use relevant keywords in titles and descriptions
Keep titles under 60 characters
Keep descriptions under 160 characters
Use descriptive file names for images
Include location information where relevant

Important Privacy Guidelines

Only include photos with proper consent
Verify all contact information is correct
Don’t share sensitive personal information
For minors, ensure guardian consent
Respect cultural sensitivities

Common Examples

Service Listing

---
title: Community Tech Hub
category: Technology
description: Computer training and internet access for refugees
location:
  address: Main Street, Block 5
  city: Dzaleka Refugee Camp, Dowa
contact:
  email: info@techhub.com
  phone: '+265 991 234 567'
  hours: 'Monday-Friday, 9:00 AM - 5:00 PM'
featured: true
verified: true
tags:
  - technology
  - education
  - internet
---

## About Us

We provide technology access and training to empower refugees...

## Services

- Computer basics
- Internet access
- Coding workshops
- Digital literacy

## How to Find Us

Located in Block 5, next to the community center.

Event Listing

---
title: "Youth Tech Workshop 2026"
description: "Three-day intensive coding workshop for young refugees"
date: 2026-06-15T09:00:00Z
endDate: 2026-06-17T17:00:00Z
location: "Ubuntu Office, Dzaleka"
category: "Workshop"
organizer: "Tech for Refugees"
status: "upcoming"
featured: true
contact:
  email: workshops@techforrefugees.org
  whatsapp: '+265 991 234 567'
registration:
  required: true
  url: "https://forms.gle/example"
  deadline: 2026-06-01T23:59:59Z
tags:
  - technology
  - education
  - youth
---

## About the Workshop

Join us for an intensive three-day coding bootcamp...

## What You'll Learn

- HTML & CSS basics
- JavaScript fundamentals
- Building your first website

## Requirements

No prior experience needed! Just bring:
- A laptop (if you have one)
- Enthusiasm to learn
- Notebook and pen

## How to Register

Register by June 1st through the link above. Limited spots available!

Job Posting

---
title: Community Health Worker
organization: Dzaleka Health Initiative
location: Dzaleka Refugee Camp
type: full-time
category: healthcare
salary: "MWK 150,000/month"
posted: 2026-01-15
deadline: 2026-02-15
status: open
featured: true
skills:
  - Healthcare experience
  - Community outreach
  - Multilingual
  - First aid certified
contact:
  email: jobs@dzalekahealth.org
  phone: '+265 991 234 567'
description: "Join our team providing essential health services"
---

## About the Role

We are seeking a dedicated Community Health Worker...

## Responsibilities

- Conduct home visits
- Health education
- Basic medical screening
- Community health promotion

## Requirements

### Essential
- Certificate in Community Health or Nursing
- 2+ years experience in community health
- Fluent in English, French, or Swahili

### Preferred
- First aid certification
- Experience in refugee settings
- Knowledge of local languages

## How to Apply

Send your CV and cover letter to jobs@dzalekahealth.org by February 15, 2026.

Validation & Testing

Before Submitting

Check Required Fields

Ensure all required fields are present for your collection

Validate YAML

Use a YAML validator to check frontmatter syntax

Review Content

Proofread for spelling, grammar, and clarity

Test Links

Verify all URLs are working

Check Images

Ensure image paths are correct and images load

Common Errors

Missing Required Field

Error: Required field missingSolution: Check the schema for required fields and add them to your frontmatter

Invalid Date Format

Error: Invalid dateSolution: Use ISO 8601 format: 2025-10-30T09:00:00Z or simple date: 2025-10-30

Invalid Enum Value

Error: Invalid enum valueSolution: Check allowed values in schema. For example, job type must be one of: full-time, part-time, contract, volunteer, internship

YAML Syntax Error

Error: YAML parsing failedSolution: Check for:

Proper indentation (use spaces, not tabs)
Matching quotes
Correct array/object syntax
No special characters without quotes

Invalid Image Path

Error: Image validation failedSolution: For photos collection, ensure image path starts with /images/ or is a valid URL

Submission Process

Via GitHub

Fork the repository
Create your content file in the appropriate collection folder
Add images to public/images/ if needed
Commit with descriptive message
Submit pull request

Via Email

Send your content file and any images to: content@dzaleka.com Include:

Collection name
Content file (.md)
Images (if any)
Your contact information

Getting Help

Collections Reference

Learn about each collection type

Schema Reference

Detailed field specifications

Example Files

Browse existing content for examples

Contact Support

Email us for assistance

Tips for Success

Start SimpleBegin with required fields only, then add optional fields as needed.

Copy From ExamplesBrowse existing content files in the repository and use them as templates.

Test LocallyIf possible, run the project locally to see how your content appears before submitting.

Ask QuestionsDon’t hesitate to reach out if you’re unsure about formatting or requirements.

Thank You!

Your contributions help build a comprehensive resource for the Dzaleka community. Every story, service, event, and resource you add makes a difference!

​Getting Started

​File Naming Conventions

​General Rules

​Examples

​Collection-Specific Guidelines

​Frontmatter Requirements

​Structure

​Required vs Optional Fields

​Field Formatting

​Strings

​Dates

​Booleans

​Arrays

​Objects

​Arrays of Objects

​Enums (Specific Values)

​Markdown Content

​Basic Formatting

​Heading Levels

​Lists

​Links

​Emphasis

​Blockquotes

​Code

​Image Guidelines

​Image Paths

​Image Optimization

File Size

Dimensions

Format

Naming

​Organizing Images

​Content Best Practices

​Writing Style

​Accessibility

​SEO Considerations

​Privacy & Consent

​Common Examples

​Service Listing

​Event Listing

​Job Posting

​Validation & Testing

​Before Submitting

​Common Errors

​Submission Process

​Via GitHub

​Via Email

​Getting Help

Collections Reference

Schema Reference

Example Files

Contact Support

​Tips for Success

​Thank You!

Getting Started

File Naming Conventions

General Rules

Examples

Collection-Specific Guidelines

Frontmatter Requirements

Structure

Required vs Optional Fields

Field Formatting

Strings

Dates

Booleans

Arrays

Objects

Arrays of Objects

Enums (Specific Values)

Markdown Content

Basic Formatting

Heading Levels

Lists

Links

Emphasis

Blockquotes

Code

Image Guidelines

Image Paths

Image Optimization

Organizing Images

Content Best Practices

Writing Style

Accessibility

SEO Considerations

Privacy & Consent

Common Examples

Service Listing

Event Listing

Job Posting

Validation & Testing

Before Submitting

Common Errors

Submission Process

Via GitHub

Via Email

Getting Help

Tips for Success

Thank You!