Adding Reviews to the Vendor System

This guide explains how to add new customer reviews to the verified vendor cards in the Gray Guide documentation system.

Overview

Reviews are stored in a JSON file and automatically displayed on vendor cards. The system supports features like:

• Star ratings (1-5 stars)
• Text content with automatic truncation
• Reviewer information with avatars
• Source attribution (all reviews show as "Telegram")
• Featured reviews that appear first
• Automatic average rating calculation

File Location

Reviews are stored in:

docusaurus/src/data/reviews.json

Review Data Structure

Complete Review Object

{
  "id": "review-9",
  "vendorId": "reseller",
  "rating": 5,
  "content": "Excellent service and fast shipping. Alex was very responsive to all my questions and provided tracking information promptly. The product arrived exactly as described and I'm very satisfied with my purchase.",
  "reviewer": {
    "displayName": "John D",
    "avatarInitials": "JD"
  },
  "date": "2024-08-16T14:30:00Z",
  "source": "telegram",
  "reactions": {
    "heart": 3,
    "thumbsUp": 7
  }
}

Required Fields

Field	Type	Description	Example
id	string	Unique identifier for the review	"review-9"
vendorId	string	Must match a vendor ID from vendors.json	"reseller"
rating	number	Star rating from 1-5	5
content	string	The review text content	"Great experience..."
reviewer.displayName	string	Public name/alias of reviewer	"John D"
date	string	ISO 8601 formatted date	"2024-08-16T14:30:00Z"

Optional Fields

Field	Type	Description	Example
reviewer.avatarInitials	string	1-3 characters for avatar display	"JD"
source	string	Original source (not displayed)	"telegram"
reactions.heart	number	Heart reaction count	3
reactions.thumbsUp	number	Thumbs up reaction count	7

Adding a New Review

Step 1: Open the Reviews File

Edit docusaurus/src/data/reviews.json

Step 2: Add Your Review Object

Add your new review to the reviews array. Make sure to:

1. Use a unique ID: Follow the pattern review-X where X is the next number
2. Match vendor ID: Use the exact id from a vendor in vendors.json
3. Format the date: Use ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ)
4. Keep content readable: Write natural, helpful review content

Step 3: Example Addition

{
  "reviews": [
    // ... existing reviews ...
    {
      "id": "review-10",
      "vendorId": "reseller",
      "rating": 4,
      "content": "Good communication throughout the process. Shipping took about 2 weeks as expected. Product quality seems good and packaging was secure. Would order again.",
      "reviewer": {
        "displayName": "Sarah K",
        "avatarInitials": "SK"
      },
      "date": "2024-08-17T09:15:00Z",
      "source": "telegram",
      "reactions": {
        "heart": 2,
        "thumbsUp": 5
      }
    }
  ]
}

Vendor IDs

Current available vendor IDs (from vendors.json):

• "reseller" - Alex Wu

To add reviews for other vendors, use their exact id field from the vendors data.

Date Formatting

Always use ISO 8601 format for dates:

• Format: YYYY-MM-DDTHH:mm:ssZ
• Example: "2024-08-17T14:30:00Z"
• Use UTC timezone (Z suffix)

Rating Guidelines

• Use whole numbers from 1-5
• 5 = Excellent
• 4 = Good
• 3 = Average
• 2 = Poor
• 1 = Very Poor

Content Guidelines

Length

• Short reviews: 1-2 sentences (50-100 characters)
• Medium reviews: 1-2 paragraphs (100-300 characters)
• Long reviews: Multiple paragraphs (300+ characters)

Style

• Write in first person ("I ordered...", "My experience...")
• Include specific details (shipping time, communication, product quality)
• Be honest and balanced
• Avoid personal information beyond what's already public

Featured Reviews

The system automatically features the review with ID "review-6" (Lauren Holder's review). This review:

• Always appears first in the list
• Has special golden styling
• Shows a "Featured Review" badge

To change the featured review, update the review.id === 'review-6' condition in:

• ReviewsSection.jsx (line ~20 and ~80)

Display Behavior

Automatic Features

• Reviews are sorted with featured review first, then by date (newest first)
• Average rating is calculated automatically
• Long content is truncated with "Read more" expansion
• All reviews show "Telegram" as source with link to: https://t.me/c/2845301475/3

Show More Functionality

• Initially shows 2 reviews
• "Show more" button reveals 3 additional reviews at a time
• Continues until all reviews are visible

Testing Your Changes

After adding reviews:

1. Save the file - Hot reload will pick up changes automatically
2. Check the browser - Navigate to the verified vendors page
3. Verify display - Ensure your review appears correctly
4. Test interactions - Try "Read more" and "Show more" buttons

Common Issues

Review Not Appearing

• Check that vendorId exactly matches a vendor ID in vendors.json
• Ensure JSON syntax is valid (no trailing commas, proper quotes)
• Verify the file saved correctly

Display Issues

• Check date format is valid ISO 8601
• Ensure rating is a number between 1-5
• Verify all required fields are present

JSON Validation

Use a JSON validator to check syntax before saving:

• https://jsonlint.com/
• VS Code will show syntax errors inline

File Structure Reference

docusaurus/
├── src/
│   ├── data/
│   │   ├── reviews.json          ← Add reviews here
│   │   └── vendors.json          ← Check vendor IDs here
│   └── components/
│       └── VendorTable/
│           ├── ReviewsSection.jsx ← Main reviews component
│           ├── ReviewItem.jsx     ← Individual review display
│           └── styles.module.css  ← Review styling
└── docs/
    └── development/
        └── adding-reviews.md      ← This documentation

By Mr Fox

Published April 17, 2025