Adding New Content

This guide shows you how to add new documentation pages, create new clients and sites, and organize content effectively.

---

Adding a New Page to an Existing Site

Step 1: Create the Markdown File

Navigate to the correct directory and create a new .md file:

clients/{client-slug}/{site-slug}/{category}/{new-page}.md

Example: Adding a new "Troubleshooting" page to GSM Outdoors Middleware:

clients/gsm-outdoors/middleware/troubleshooting.md

Step 2: Add Frontmatter

Every markdown file must have frontmatter at the top:

---
sidebar_position: 5
id: troubleshooting
title: Troubleshooting Common Issues
sidebar_label: Troubleshooting
---

# Troubleshooting Common Issues

Content goes here...

Field	Purpose
sidebar_position	Controls order in sidebar (1 = first, 2 = second, etc.)
id	Unique identifier (used for internal links)
title	Full page title (shown in browser tab and H1)
sidebar_label	Short label in sidebar (optional — defaults to title)

Step 3: Add Content

Write your documentation using standard Markdown:

---
sidebar_position: 5
id: troubleshooting
title: Troubleshooting Common Issues
sidebar_label: Troubleshooting
---

# Troubleshooting Common Issues

This page covers common issues and solutions.

---

## Database Connection Errors

If you see connection timeout errors:

```bash
ERROR: Connection timeout to database

Check these settings:

1. Verify database credentials in .env
2. Ensure MySQL is running
3. Check firewall rules

---

API Rate Limiting

The BigCommerce API limits requests to 20,000 per hour.

caution

Exceeding rate limits will result in 429 errors.

Use the X-Rate-Limit-Remaining header to track usage.

### Step 4: Test Locally

Start the dev server:

```powershell
npm run start

Navigate to your new page and verify it appears in the sidebar.

Step 5: Build and Deploy

npm run build      # Verify no broken links
git add .
git commit -m "Add troubleshooting page to middleware docs"
git push

---

Adding a New Category (Folder)

To group multiple pages together, create a subdirectory with a _category_.json file.

Example: Add a "Deployment" Category

# Create the directory
mkdir clients/scottsdale-mint/retail/deployment

# Create the category config file
New-Item clients/scottsdale-mint/retail/deployment/_category_.json

_category_.json:

{
  "label": "🚀 Deployment",
  "position": 6,
  "collapsed": true
}

Field	Purpose
label	Category name shown in sidebar (emojis allowed)
position	Order relative to other categories (1-based)
collapsed	true = collapsed by default, false = expanded

Now add pages inside the directory:

clients/scottsdale-mint/retail/deployment/
├── _category_.json
├── overview.md
├── staging.md
└── production.md

Each page should have its own sidebar_position value.

---

Adding a New Client + Site (Automated)

The fastest way to add a new client and site is using the automated wizard:

.\scripts\create-new-client-site.ps1

This interactive script will:

1. Prompt for client name, slug, and label
2. Prompt for site name, slug, and label
3. Create all necessary directories and files:
   • clients/{client-slug}/index.md (client landing page)
   • clients/{client-slug}/{site-slug}/intro.md (site intro)
   • clients/{client-slug}/{site-slug}/_category_.json (category config)
4. Update src/pages/index.tsx (homepage client cards)
5. Update src/theme/SearchBar/index.tsx (search facet dropdown)
6. Update src/components/HomepageSearch/index.tsx (homepage search dropdown)
7. Add custom label to plugins/docsearch-meta-plugin/index.js (if needed)

Example Run

PS> .\scripts\create-new-client-site.ps1

Enter client slug (e.g., 'new-client'): example-company
Enter client name (e.g., 'New Client'): Example Company
Enter client label (or press Enter to use 'Example Company'):

Adding new site to 'example-company'...

Enter site slug (e.g., 'retail'): website
Enter site name (e.g., 'Retail Site'): Website
Enter site label (or press Enter to use 'Website'):

✓ Created client landing page
✓ Created site intro page
✓ Updated homepage client cards
✓ Updated search bar registry
✓ Updated homepage search registry
✓ Updated meta plugin labels

Success! New client and site created.

Now you can add more pages to clients/example-company/website/.

---

Adding a New Site to an Existing Client (Manual)

If you want to add a site manually without the wizard:

Step 1: Create the Site Directory

mkdir clients/gsm-outdoors/new-site

Step 2: Create _category_.json

{
  "label": "New Site",
  "position": 8,
  "collapsed": true
}

Step 3: Create intro.md

---
sidebar_position: 1
id: intro
title: New Site
sidebar_label: "Intro"
---

# New Site

Overview of this site...

Step 4: Update Client Landing Page

Edit clients/gsm-outdoors/index.md and add the new site to the list:

## Sites

- [Middleware](middleware/intro) — Integration layer
- [StealthCam](stealthcam/intro) — Trail camera e-commerce
- [New Site](new-site/intro) — Description here

Step 5: Update Search Registries

Edit both of these files:

src/theme/SearchBar/index.tsx:

const clientRegistry: ClientRegistry = {
  'gsm-outdoors': {
    label: 'GSM Outdoors',
    sites: {
      'middleware': 'Middleware',
      'stealthcam': 'StealthCam',
      'new-site': 'New Site',  // Add this line
    },
  },
  // ...
};

src/components/HomepageSearch/index.tsx:

const clientRegistry: ClientRegistry = {
  'gsm-outdoors': {
    label: 'GSM Outdoors',
    sites: {
      'middleware': 'Middleware',
      'stealthcam': 'StealthCam',
      'new-site': 'New Site',  // Add this line
    },
  },
  // ...
};

Step 6: Build and Re-scrape

npm run build
.\typesense\scrape.sh    # Re-index for search

---

Example Copilot Prompts for Adding Content

Use these prompts with GitHub Copilot to speed up content creation:

Create a New Documentation Page

Create a new markdown file at clients/scottsdale-mint/retail/inventory-management.md 
with frontmatter (sidebar_position: 4, id: inventory-management, title: "Inventory Management", 
sidebar_label: "Inventory"). Include sections for: Overview, Stock Tracking, Low Stock Alerts, 
and Reordering Process. Use code examples and admonitions where appropriate.

Add a New Category with Multiple Pages

Create a new category at clients/tenpoint-crossbows/retail/shipping/ with _category_.json 
(label: "📦 Shipping", position: 5, collapsed: true). Then create three pages: 
overview.md (shipping methods overview), rates.md (shipping rates and zones), 
and tracking.md (order tracking integration). Each page should have proper frontmatter 
and comprehensive content with code examples.

Create a New Client from Scratch

Run the create-new-client-site.ps1 script to add a new client called "Acme Corp" 
(slug: acme-corp) with a site called "E-Commerce" (slug: ecommerce). After creation, 
populate the intro.md with an overview of the Acme Corp e-commerce platform including 
architecture, tech stack (WordPress + WooCommerce), and key features.

Generate API Reference Documentation

Create a comprehensive API reference page at clients/gsm-outdoors/middleware/api/products.md 
documenting the Products API endpoints. Include: GET /products (list all products with 
pagination), GET /products/{id} (get single product), POST /products (create product), 
PUT /products/{id} (update product), DELETE /products/{id} (delete product). 
Each endpoint should have: description, authentication requirements, request parameters, 
request body examples, response examples, and error codes.

Migrate Documentation from Another Format

Convert the API documentation in Z:\Repos\legacy-docs\api.html to markdown format 
and create new pages in clients/example-company/website/api/. Split into separate 
pages for authentication.md, endpoints.md, webhooks.md, and errors.md. Preserve all 
code examples and add proper Docusaurus frontmatter to each file.

---

File Naming Best Practices

• Use lowercase with hyphens (kebab-case): my-page-name.md
• Be descriptive: payment-gateway.md not payments.md
• Match the id in frontmatter: payment-gateway.md → id: payment-gateway
• Avoid spaces and special characters
• Use intro.md for category landing pages (not index.md)

---

Next Steps

• Editing Content — Modify existing documentation
• Deploy Testing Checklist — Pre/post-deployment verification
• Deployment — Deploy to production