Chatwoot Documentation Sync

This directory contains the tools and documentation for syncing the Itinerator plugin's Markdown documentation to the Chatwoot Help Center.

📁 Files

sync-docs.js - Main sync script that processes markdown files and creates/updates articles in Chatwoot
README.md - This documentation file

🚀 Quick Start

Prerequisites

Node.js (version 18+ recommended)
Configuration files in the project root:
- docs-config.json - Chatwoot API configuration
- docs-map.json - Article mapping file (auto-generated)

Running the Sync

# From the project root directory
node docs/sync/sync-docs.js

⚙️ Configuration

`docs-config.json` Structure

{
  "chatwootBaseUrl": "https://chat.tourismo.co",
  "portalSlug": "wordpress-plugin-documentation",
  "apiToken": "your-api-token",
  "accountId": 1,
  "authorId": 14,
  "categories": {
    "collection-blocks": 7,
    "content-blocks": 8,
    "getting-started": 9,
    "general": 10
  }
}

Required Configuration Values

chatwootBaseUrl: Your Chatwoot instance URL
portalSlug: The slug of your Help Center portal
apiToken: Your Chatwoot API token (use API-ACCESS-TOKEN header)
accountId: Your Chatwoot account ID
authorId: The ID of the user who will be listed as the article author
categories: Mapping of category slugs to their Chatwoot IDs

📋 How It Works

Categorization Logic

The sync script automatically categorizes articles based on their file path:

docs/user-guide/blocks/content-blocks/ → Content Blocks category
docs/user-guide/blocks/collection-blocks/ → Collection Blocks category
docs/user-guide/getting-started/ → Getting Started category
docs/user-guide/general/ → General category

Meta Fields Generated

For each article, the script generates:

Title: From front-matter title or generated from filename
Description: SEO-friendly description with category context
Meta Title: SEO-optimized page title
Meta Description: SEO description for search engines
Tags: Automatic tags based on file path and content type

Front-matter Support

You can override defaults using YAML front-matter in your markdown files:

---
title: "Custom Title"
description: "Custom description for the article"
metaTitle: "Custom SEO Title"
metaDescription: "Custom SEO description"
tags: "custom, tags, here"
---

🔄 Sync Process

Scan: Recursively finds all .md files in the docs/ directory
Parse: Extracts front-matter and content from each file
Categorize: Determines category and generates metadata
Check: Looks up existing article in docs-map.json
Create/Update:
- If article exists: Updates with PATCH request
- If new article: Creates with POST request
Track: Updates docs-map.json with article mappings

📊 Output

The script provides detailed progress information:

🚀 Starting enhanced Chatwoot docs sync...

📁 Found 25 markdown files

🆕 Creating: user-guide/blocks/content-blocks/title.md
✅ Created: user-guide/blocks/content-blocks/title.md (ID: 48)

📝 Updating: user-guide/blocks/content-blocks/description.md
✅ Updated: user-guide/blocks/content-blocks/description.md (ID: 49)

📊 Sync Summary:
✅ Created: 20 articles
📝 Updated: 5 articles
❌ Errors: 0 articles

💾 Updated docs-map.json with article mappings

📋 Category Distribution:
  - Content Blocks: 12 articles
  - Collection Blocks: 8 articles
  - Getting Started: 3 articles
  - General: 2 articles

🛠️ Troubleshooting

Common Issues

401 Unauthorized Error

Check your API token in docs-config.json
Ensure token uses API-ACCESS-TOKEN header format
Verify token has proper permissions

404 Not Found Error

Check portalSlug in configuration
Verify portal exists in your Chatwoot instance
Ensure account ID is correct

Category Not Found

Run the category setup script to create required categories
Check category IDs in docs-config.json

Getting Help

Check the console output for specific error messages
Verify your docs-config.json settings

Test API access with a simple curl command:

curl -H "API-ACCESS-TOKEN: your-token" \
     https://chat.tourismo.co/api/v1/accounts/1/portals/wordpress-plugin-documentation/articles

🔧 Maintenance

Regular Updates

Run the sync script whenever you update documentation
The script only updates changed files (based on docs-map.json)
New files are automatically detected and created

Adding New Categories

Create the category in Chatwoot admin
Add the category mapping to docs-config.json
Update the categorization logic in sync-docs.js if needed

Cleaning Up

The docs-map.json file tracks all synced articles
To remove an article from Chatwoot, delete it manually and remove the entry from docs-map.json

📝 Notes

Articles are created as "published" by default
The script preserves existing article IDs for updates
All articles include SEO-optimized meta fields
Tags provide virtual categorization beyond the main categories
The sync is idempotent - safe to run multiple times

README