> ## Documentation Index
> Fetch the complete documentation index at: https://dos.dzaleka.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Content Contribution Guidelines

> Best practices for creating and formatting content for 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

<Steps>
  <Step title="Choose a Collection">
    Determine which collection best fits your content. See the [Collections Overview](/collections) for details on each type.
  </Step>

  <Step title="Review the Schema">
    Check the [Schema Reference](/schemas) for required and optional fields for your collection.
  </Step>

  <Step title="Create Your File">
    Follow the file naming and formatting guidelines below.
  </Step>

  <Step title="Submit Your Content">
    Submit via pull request or contact the platform administrators.
  </Step>
</Steps>

## File Naming Conventions

### General Rules

<Check>
  * Use lowercase letters
  * Replace spaces with hyphens (`-`)
  * Use descriptive, meaningful names
  * Avoid special characters except hyphens
  * Keep names concise but clear
</Check>

### Examples

<CodeGroup>
  ```bash Good Examples theme={null}
  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
  ```

  ```bash Avoid theme={null}
  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
  ```
</CodeGroup>

### Collection-Specific Guidelines

<AccordionGroup>
  <Accordion title="Events">
    Include event name and year:

    * `tumaini-festival-2025.md`
    * `refugee-self-advocacy-november-2025.md`
  </Accordion>

  <Accordion title="Jobs">
    Use job title or role:

    * `secondary-school-teachers.md`
    * `programs-manager.md`
    * `digital-archivist.md`
  </Accordion>

  <Accordion title="Services/Stores">
    Use business name:

    * `zawadie-solutions.md`
    * `mama-joys-kitchen.md`
    * `dowa-bakery.md`
  </Accordion>

  <Accordion title="Marketplace">
    Use product/service name:

    * `refugee-for-life-book.md`
    * `kibebe-baby-products.md`
  </Accordion>

  <Accordion title="People (Artists, Dancers, Poets)">
    Use person or group name:

    * `christian-piniero.md`
    * `shakers-dance-crew.md`
  </Accordion>
</AccordionGroup>

## Frontmatter Requirements

### Structure

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

```markdown theme={null}
---
title: Your Title Here
description: Brief description
# ... other fields
---

Your markdown content here...
```

### Required vs Optional Fields

<Warning>
  Required fields must be present in every file. Missing required fields will cause validation errors.
</Warning>

<Tip>
  Optional fields can be omitted entirely. Don't include them with empty values unless necessary.
</Tip>

<CodeGroup>
  ```yaml Good - Omit Optional Fields theme={null}
  ---
  title: My Service
  description: A great service
  category: Education
  # logo omitted since we don't have one
  ---
  ```

  ```yaml Avoid - Empty Values theme={null}
  ---
  title: My Service
  description: A great service
  category: Education
  logo: ''
  featured: 
  verified:
  ---
  ```
</CodeGroup>

### Field Formatting

#### Strings

Simple strings can be unquoted:

```yaml theme={null}
title: Zawadie Solutions
category: Entrepreneurship & Business
```

Quote strings with special characters:

```yaml theme={null}
title: "Mama Joy's Kitchen"
description: "Restaurant: Traditional & Modern Cuisine"
```

#### Dates

Use ISO 8601 format for date-time:

```yaml theme={null}
date: 2025-10-30T09:00:00Z
endDate: 2025-11-01T22:00:00Z
```

Or simple date format:

```yaml theme={null}
posted: 2023-05-01
deadline: 2023-05-31
```

#### Booleans

```yaml theme={null}
featured: true
verified: false
```

#### Arrays

<CodeGroup>
  ```yaml Inline Format theme={null}
  tags: ["music", "dance", "arts"]
  skills: ["Teaching", "Lesson Planning"]
  ```

  ```yaml Multi-line Format theme={null}
  tags:
    - music
    - dance
    - arts
    
  skills:
    - Teaching
    - Lesson Planning
    - Classroom Management
  ```
</CodeGroup>

#### Objects

```yaml theme={null}
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

```yaml theme={null}
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:

<CodeGroup>
  ```yaml Jobs Type theme={null}
  type: full-time
  # Allowed: full-time, part-time, contract, volunteer, internship
  ```

  ```yaml Store Type theme={null}
  type: restaurant
  # Allowed: restaurant, cafe, bakery, grocery, retail, salon, workshop, other
  ```

  ```yaml Event Status theme={null}
  status: upcoming
  # Allowed: upcoming, past
  ```
</CodeGroup>

## Markdown Content

### Basic Formatting

After the frontmatter, write your content in Markdown:

```markdown theme={null}
---
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

<Note>
  Start with `##` (h2) for main sections. The `#` (h1) level is typically reserved for the page title.
</Note>

```markdown theme={null}
## About Us          (h2 - main sections)
### Our Mission      (h3 - subsections)
#### Details         (h4 - sub-subsections)
```

### Lists

<CodeGroup>
  ```markdown Unordered Lists theme={null}
  - First item
  - Second item
    - Nested item
    - Another nested item
  - Third item
  ```

  ```markdown Ordered Lists theme={null}
  1. First step
  2. Second step
  3. Third step
  ```
</CodeGroup>

### Links

```markdown theme={null}
[Dzaleka Online Services](https://dzaleka.com)
[Visit our website](https://example.com)

Email: <info@example.com>
```

### Emphasis

```markdown theme={null}
*italic text* or _italic text_
**bold text** or __bold text__
***bold and italic*** or ___bold and italic___
```

### Blockquotes

Great for testimonials:

```markdown theme={null}
> Tumaini Festival brings exceptional hope into the lives of people.

— Skeffa Chimoto, Musician
```

### Code

Inline code: \`code here\`

Code blocks:

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

## Image Guidelines

### Image Paths

<Tabs>
  <Tab title="Local Images">
    Store images in the `public/images/` directory:

    ```yaml theme={null}
    image: /images/my-photo.jpg
    logo: /images/logos/company-logo.png
    ```

    The `/images/` path maps to `public/images/` in the project.
  </Tab>

  <Tab title="External URLs">
    Use full URLs for externally hosted images:

    ```yaml theme={null}
    image: https://example.com/photo.jpg
    coverImage: https://images.unsplash.com/photo-123
    ```
  </Tab>
</Tabs>

### Image Optimization

<CardGroup cols={2}>
  <Card title="File Size" icon="compress">
    * Aim for under 500 KB per image
    * Use compression tools
    * Consider WebP format
  </Card>

  <Card title="Dimensions" icon="ruler">
    * Logos: 200-400px wide
    * Thumbnails: 600-800px wide
    * Cover images: 1200-1600px wide
  </Card>

  <Card title="Format" icon="image">
    * Photos: JPG/JPEG
    * Graphics/logos: PNG or WebP
    * Avoid BMP, TIFF
  </Card>

  <Card title="Naming" icon="tag">
    * Use descriptive names
    * Lowercase with hyphens
    * Example: `tumaini-festival-2025.jpg`
  </Card>
</CardGroup>

### 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:

```yaml theme={null}
image: /images/events/tumaini-festival-2025.jpg
logo: /images/services/zawadie-logo.png
```

## Content Best Practices

### Writing Style

<Check>
  * Write clear, concise descriptions
  * Use active voice
  * Be specific and factual
  * Proofread for spelling and grammar
  * Use proper capitalization
</Check>

### Accessibility

<Check>
  * Write descriptive alt text (coming soon)
  * Use clear heading hierarchy
  * Ensure sufficient contrast for images
  * Make links descriptive ("Visit Zawadie Solutions" not "click here")
</Check>

### SEO Considerations

<Check>
  * 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
</Check>

### Privacy & Consent

<Warning>
  **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
</Warning>

## Common Examples

### Service Listing

```markdown theme={null}
---
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

```markdown theme={null}
---
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

```markdown theme={null}
---
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

<Steps>
  <Step title="Check Required Fields">
    Ensure all required fields are present for your collection
  </Step>

  <Step title="Validate YAML">
    Use a YAML validator to check frontmatter syntax
  </Step>

  <Step title="Review Content">
    Proofread for spelling, grammar, and clarity
  </Step>

  <Step title="Test Links">
    Verify all URLs are working
  </Step>

  <Step title="Check Images">
    Ensure image paths are correct and images load
  </Step>
</Steps>

### Common Errors

<AccordionGroup>
  <Accordion title="Missing Required Field">
    **Error:** `Required field missing`

    **Solution:** Check the schema for required fields and add them to your frontmatter
  </Accordion>

  <Accordion title="Invalid Date Format">
    **Error:** `Invalid date`

    **Solution:** Use ISO 8601 format: `2025-10-30T09:00:00Z` or simple date: `2025-10-30`
  </Accordion>

  <Accordion title="Invalid Enum Value">
    **Error:** `Invalid enum value`

    **Solution:** Check allowed values in schema. For example, job `type` must be one of: full-time, part-time, contract, volunteer, internship
  </Accordion>

  <Accordion title="YAML Syntax Error">
    **Error:** `YAML parsing failed`

    **Solution:** Check for:

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

  <Accordion title="Invalid Image Path">
    **Error:** `Image validation failed`

    **Solution:** For photos collection, ensure image path starts with `/images/` or is a valid URL
  </Accordion>
</AccordionGroup>

## Submission Process

### Via GitHub

1. Fork the repository
2. Create your content file in the appropriate collection folder
3. Add images to `public/images/` if needed
4. Commit with descriptive message
5. Submit pull request

### Via Email

Send your content file and any images to: **[content@dzaleka.com](mailto:content@dzaleka.com)**

Include:

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

## Getting Help

<CardGroup cols={2}>
  <Card title="Collections Reference" icon="folder" href="/collections">
    Learn about each collection type
  </Card>

  <Card title="Schema Reference" icon="database" href="/schemas">
    Detailed field specifications
  </Card>

  <Card title="Example Files" icon="code" href="https://github.com/Dzaleka-Connect/Dzaleka-Online-Services">
    Browse existing content for examples
  </Card>

  <Card title="Contact Support" icon="envelope" href="mailto:support@dzaleka.com">
    Email us for assistance
  </Card>
</CardGroup>

## Tips for Success

<Tip>
  **Start Simple**

  Begin with required fields only, then add optional fields as needed.
</Tip>

<Tip>
  **Copy From Examples**

  Browse existing content files in the repository and use them as templates.
</Tip>

<Tip>
  **Test Locally**

  If possible, run the project locally to see how your content appears before submitting.
</Tip>

<Tip>
  **Ask Questions**

  Don't hesitate to reach out if you're unsure about formatting or requirements.
</Tip>

***

## Thank You!

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