Sync Docs

Prerequisites

1. KB Configuration: Provider credentials and settings in config.yaml
2. Python Environment: KB provider scripts installed
3. Screenshots Captured: For upload mode
4. Documentation Written: For sync mode

Mode 1: Upload Screenshots

When to Use

After screenshots are captured, before creating documentation. You need CloudFront URLs to embed in documentation.

Input

• Feature name
• Screenshots directory (from config.yaml)
• Screenshot filenames

Process

Step 1: Locate Screenshots

Find the captured screenshots:

ls -lh output/screenshots/[feature]-*.png

Verify:

• Screenshots exist
• Filenames are correct
• File sizes are reasonable (not 0 bytes)

Step 2: Upload to KB Provider

Use the generic KB upload script for each screenshot:

cd /path/to/max-doc-ai

# Uses provider from config.yaml
python3 scripts/kb/upload.py \
  --image output/screenshots/[feature]-overview.png \
  --alt "[Feature Name] overview"

# Or specify provider explicitly
python3 scripts/kb/upload.py \
  --provider zendesk \
  --image output/screenshots/[feature]-overview.png \
  --alt "[Feature Name] overview"

For multiple screenshots, upload each one:

# Screenshot 1
python3 scripts/kb/upload.py \
  --image output/screenshots/[feature]-overview.png \
  --alt "[Feature Name] overview"

# Screenshot 2
python3 scripts/kb/upload.py \
  --image output/screenshots/[feature]-detail.png \
  --alt "[Feature Name] detailed view"

# ... continue for all screenshots

Step 3: Collect CDN URLs

The upload script will output CDN URLs like:

📤 Uploading: feature-overview.png
   ✅ Uploaded: https://cdn-url.example.com/attachments/abc123/feature-overview.png

Save all URLs - you'll need them for the documentation.

Note: URL format varies by provider:

• Pylon: CloudFront URLs (https://d...cloudfront.net/...)
• Zendesk: Zendesk CDN URLs
• Confluence: Atlassian media URLs

Step 4: Create URL Mapping

Document the mapping:

## CloudFront URLs for [Feature Name]

1. **[feature]-overview.png**
   - CloudFront URL: https://d1234abcd.cloudfront.net/attachments/abc123/feature-overview.png
   - Alt text: [Feature Name] overview

2. **[feature]-detail.png**
   - CloudFront URL: https://d1234abcd.cloudfront.net/attachments/abc123/feature-detail.png
   - Alt text: [Feature Name] detailed view

[... continue for all screenshots ...]

Step 5: Provide URLs to Next Step

Return the CloudFront URLs so they can be used in documentation:

✅ Screenshot Upload Complete

Uploaded [X] screenshots to Pylon CDN.

CloudFront URLs:
- feature-overview: https://cloudfront.url/1.png
- feature-detail: https://cloudfront.url/2.png
[... list all ...]

These URLs should be used in the documentation markdown.

Mode 2: Sync Documentation

When to Use

After documentation is written with embedded CloudFront URLs. This publishes the documentation to Pylon knowledge base.

Input

• Feature name
• Category (must match config.yaml collections)
• Documentation file path
• Title and slug for the article

Process

Step 1: Verify Documentation File

Check that documentation file exists and is valid:

cat output/features/YYYY-MM-DD_[feature-slug]/[feature-slug].md

Verify:

• File exists
• Valid markdown
• No H1 heading (starts with H2)
• Screenshots use CloudFront URLs
• Content is complete

Step 2: Determine Article Key

Create a unique key for state tracking:

Pattern: [category]-[feature-slug]

Examples:

• features-dashboards
• integrations-slack
• getting-started-quickstart

This key is used to track whether the article already exists in Pylon.

Step 3: Sync to KB Provider

Use the generic KB sync script:

cd /path/to/max-doc-ai

# Uses provider from config.yaml
python3 scripts/kb/sync.py \
  --file output/features/YYYY-MM-DD_[feature-slug]/[feature-slug].md \
  --key [category]-[feature-slug] \
  --title "[Feature Name]" \
  --slug "[feature-slug]" \
  --collection [category]

# Or specify provider explicitly
python3 scripts/kb/sync.py \
  --provider zendesk \
  --file output/features/YYYY-MM-DD_[feature-slug]/[feature-slug].md \
  --key [category]-[feature-slug] \
  --title "[Feature Name]" \
  --slug "[feature-slug]" \
  --collection [category]

Example:

python3 scripts/kb/sync.py \
  --file output/features/2025-12-22_dashboards/dashboards.md \
  --key features-dashboards \
  --title "Dashboards" \
  --slug "dashboards" \
  --collection features

Step 4: Monitor Sync Process

The script will:

1. Read markdown file
2. Convert to HTML
3. Wrap images in React components (required by Pylon)
4. Check if article exists (via state file)
5. Create new or update existing article
6. Set collection_id (CRITICAL: must be set during creation)
7. Return article URLs

Watch for:

📄 Syncing: dashboards.md
🔄 Converting markdown to HTML...
   ✅ 3 images with React wrappers
✨ Creating new article...
   Collection: features (abc-123-collection-id)
   ✅ Created article ID: xyz-789-article-id
💾 State updated: features-dashboards

Step 5: Extract Article URLs

The sync will output:

✅ Article synced successfully!
   Public URL: https://yourproduct-kb.help.usepylon.com/articles/dashboards
   Internal URL: https://app.usepylon.com/docs/[kb-id]/articles/[article-id]

Save both URLs:

• Public URL: For customer-facing announcements
• Internal URL: For editing and management

Step 6: Verify in Pylon

Optional but recommended - verify the article in Pylon:

1. Open the public URL in browser
2. Check that:
   • Article title is correct
   • Content is properly formatted
   • Screenshots are visible and sized correctly
   • Images have React wrappers (inspect HTML if needed)
   • Article is in the correct collection

Step 7: Document Results

Provide a summary:

## Documentation Synced: [Feature Name]

**Article Title:** [Feature Name]
**Slug:** [feature-slug]
**Category/Collection:** [category]
**State Key:** [category]-[feature-slug]

### URLs:

**Public (for announcements):**