How to Upload Documentation to ReadMe

Overview

Sports Stack documentation can be uploaded to ReadMe using several methods. This guide covers all available options for syncing your documentation.

Prerequisites

1. ReadMe Account: Access to https://sportsstack.readme.io
2. API Key: ReadMe API key (get from ReadMe dashboard → API Keys)
3. Project ID: 66c91312acd5eb00618a62dd (Sports Stack project)

Method 1: Manual Upload via ReadMe UI (Recommended for Guides)

For Guides and Custom Pages

1. Log in to ReadMe:

   • Go to https://sportsstack.readme.io
   • Log in with your account

2. Navigate to Your Project:

   • Select the Sports Stack project

3. Create a New Page:

   • Click "+" or "New Page"
   • Choose "Guide" or "Reference" based on content type

4. Copy Content:

   • Open your markdown file (e.g., docs/guides/webhooks_guide.md)
   • Copy the entire content
   • Paste into ReadMe editor

5. Configure Page:

   • Title: Set page title
   • Category: Select appropriate category (e.g., "Guides" or "API Reference")
   • Slug: Auto-generated from title (can customize)
   • Hidden: Uncheck if you want it visible

6. Format Content:

   • ReadMe supports Markdown and MDX
   • Code blocks will be automatically formatted
   • Mermaid diagrams will render automatically

7. Save and Publish:

   • Click "Save"
   • Page is immediately live

Recommended Structure

Guides/
├── Webhooks Guide (from docs/guides/webhooks_guide.md)
└── Data Sync Guide

API Reference/
└── Webhooks/
    ├── Configuration
    ├── Payload Schema (from docs/reference/webhooks_api_reference.md)
    └── Verification

Method 2: GitHub Sync (Recommended for Ongoing Updates)

Setup GitHub Integration

1. Connect GitHub Repository:

   • In ReadMe dashboard, go to Settings → GitHub
   • Click "Connect GitHub"
   • Authorize ReadMe to access your repository
   • Select repository: sports_stack

2. Configure Sync:

   • Sync Type: Choose "Bi-directional" or "ReadMe → GitHub"
   • Branch: Select branch (usually main or master)
   • Path: Set to docs/ (or specific subdirectory)

3. Enable Auto-Sync:

   • ReadMe will automatically sync changes from GitHub
   • Updates happen on push to selected branch

Using GitHub Sync

1. Make Changes:

   Bash

   # Edit your markdown files
   vim docs/guides/webhooks_guide.md

2. Commit and Push:

   Bash

   git add docs/guides/webhooks_guide.md
   git commit -m "Update webhooks guide"
   git push origin main

3. ReadMe Auto-Syncs:

   • ReadMe detects changes
   • Pages are automatically updated
   • Usually takes 1-2 minutes

GitHub Sync Best Practices

• File Structure: Keep same structure in docs/ as ReadMe categories
• Frontmatter: Use YAML frontmatter for metadata:
  Markdown

  ---
  title: "Webhooks Guide"
  category: "Guides"
  hidden: false
  ---

• Naming: Use descriptive filenames that match page titles

Method 3: ReadMe CLI (rdme) (Recommended for API Reference)

Installation

# Install rdme CLI globally
npm install -g rdme

# Or use npx (no installation needed)
npx rdme

Authentication

# Set API key as environment variable
export README_API_KEY="your-api-key-here"

# Or pass via --key flag
rdme openapi openapi.json --key="your-api-key" --id=66c91312acd5eb00618a62dd

Upload OpenAPI Spec

# Generate OpenAPI spec first
mix openapi.gen

# Upload to ReadMe
rdme openapi openapi.json \
  --key="$README_API_KEY" \
  --id=66c91312acd5eb00618a62dd

Upload Markdown Files

# Upload a single markdown file
rdme docs docs/guides/webhooks_guide.md \
  --key="$README_API_KEY" \
  --id=66c91312acd5eb00618a62dd

# Upload entire directory
rdme docs docs/guides/ \
  --key="$README_API_KEY" \
  --id=66c91312acd5eb00618a62dd

CLI Options

# Dry run (preview changes without applying)
rdme docs docs/guides/webhooks_guide.md --dry-run

# Create new page (don't update existing)
rdme docs docs/guides/webhooks_guide.md --create

# Update existing page
rdme docs docs/guides/webhooks_guide.md --update

# Delete page
rdme docs docs/guides/webhooks_guide.md --delete

Method 4: GitHub Actions (Automated)

Create GitHub Actions Workflow

Create .github/workflows/sync-readme.yml:

name: Sync to ReadMe

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'openapi.json'
  workflow_dispatch: # Manual trigger

jobs:
  sync-readme:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install rdme CLI
        run: npm install -g rdme

      - name: Sync OpenAPI Spec
        run: |
          rdme openapi openapi.json \
            --key="${{ secrets.README_API_KEY }}" \
            --id=66c91312acd5eb00618a62dd
        if: contains(github.event.head_commit.modified, 'openapi.json')

      - name: Sync Documentation
        run: |
          rdme docs docs/guides/ \
            --key="${{ secrets.README_API_KEY }}" \
            --id=66c91312acd5eb00618a62dd
        if: contains(github.event.head_commit.modified, 'docs/')

Setup Secrets

1. Get ReadMe API Key:

   • ReadMe Dashboard → API Keys
   • Create new API key or use existing

2. Add to GitHub Secrets:

   • Repository → Settings → Secrets and variables → Actions
   • Click "New repository secret"
   • Name: README_API_KEY
   • Value: Your ReadMe API key
   • Click "Add secret"

Manual Trigger

# Trigger workflow manually via GitHub UI
# Actions → Sync to ReadMe → Run workflow

Uploading Webhook Documentation

Step-by-Step Guide

1. Upload Webhooks Guide:

   Bash

   # Using CLI
   rdme docs docs/guides/webhooks_guide.md \
     --key="$README_API_KEY" \
     --id=66c91312acd5eb00618a62dd \
     --create

   Or manually:

   • ReadMe → Guides → New Page
   • Copy content from docs/guides/webhooks_guide.md
   • Paste and save

2. Create Webhooks API Reference Category:

   • ReadMe → API Reference → New Category
   • Name: "Webhooks"
   • Description: "Webhook configuration and payloads"

3. Upload Payload Schema Page:

   Bash

   rdme docs docs/reference/webhooks_api_reference.md \
     --key="$README_API_KEY" \
     --id=66c91312acd5eb00618a62dd \
     --create

   Or manually:

   • ReadMe → API Reference → Webhooks → New Page
   • Title: "Webhook Payload Schema"
   • Copy content from docs/reference/webhooks_api_reference.md

4. Create Sub-pages:

   • Configuration (extract from API reference)
   • Verification (extract from API reference)
   • Examples (extract from guide)

Recommended Workflow

For New Documentation

1. Write Documentation Locally:

   • Create/edit markdown files in docs/
   • Test formatting locally
   • Commit to git

2. Upload to ReadMe:

   • Option A: Use GitHub sync (if configured)
   • Option B: Use CLI for quick upload
   • Option C: Manual upload for complex formatting

3. Verify:

   • Check ReadMe page renders correctly
   • Test links and code examples
   • Verify formatting

For Updates

1. Edit Locally:

   Bash

   vim docs/guides/webhooks_guide.md

2. Commit Changes:

   Bash

   git add docs/guides/webhooks_guide.md
   git commit -m "Update webhooks guide"
   git push origin main

3. Auto-Sync (if GitHub sync enabled):

   • ReadMe automatically updates
   • Or trigger GitHub Actions workflow

Troubleshooting

CLI Authentication Issues

# Verify API key is set
echo $README_API_KEY

# Test authentication
rdme whoami --key="$README_API_KEY"

GitHub Sync Not Working

1. Check Integration:

   • ReadMe → Settings → GitHub
   • Verify repository is connected
   • Check sync settings

2. Verify Branch:

   • Ensure correct branch is selected
   • Check if branch has recent commits

3. Check Permissions:

   • Verify ReadMe has access to repository
   • Check GitHub app permissions

Formatting Issues

1. Markdown Compatibility:

   • ReadMe uses CommonMark
   • Some GitHub Flavored Markdown may not work
   • Test in ReadMe editor

2. Code Blocks:

   • Use triple backticks with language
   • ReadMe auto-formats code blocks

3. Mermaid Diagrams:

   • ReadMe supports Mermaid
   • Use ```mermaid code blocks

Best Practices

1. Version Control

• Always commit documentation to git first
• Use GitHub sync for automatic updates
• Keep docs in sync with code

2. Organization

• Follow ReadMe structure recommendations
• Use consistent naming conventions
• Group related pages together

3. Content Updates

• Update docs when code changes
• Keep examples current
• Remove outdated information

4. Testing

• Preview changes before publishing
• Test all links
• Verify code examples work

Quick Reference

ReadMe Project Info

• URL: https://sportsstack.readme.io
• Project ID: 66c91312acd5eb00618a62dd
• API Key: Get from ReadMe Dashboard → API Keys

Common Commands

# Upload OpenAPI spec
rdme openapi openapi.json --key="$README_API_KEY" --id=66c91312acd5eb00618a62dd

# Upload single markdown file
rdme docs docs/guides/webhooks_guide.md --key="$README_API_KEY" --id=66c91312acd5eb00618a62dd

# Upload directory
rdme docs docs/guides/ --key="$README_API_KEY" --id=66c91312acd5eb00618a62dd

# Dry run (preview)
rdme docs docs/guides/webhooks_guide.md --dry-run --key="$README_API_KEY" --id=66c91312acd5eb00618a62dd

Next Steps

1. Choose Upload Method:

   • Manual for initial setup
   • GitHub sync for ongoing updates
   • CLI for quick uploads

2. Upload Webhook Docs:

   • Webhooks Guide → Guides category
   • API Reference → Webhooks category

3. Set Up Automation:

   • Configure GitHub sync
   • Or create GitHub Actions workflow

4. Verify:

   • Check pages render correctly
   • Test links and examples
   • Get feedback from team

Resources

• ReadMe Documentation
• ReadMe CLI Documentation
• GitHub Sync Guide
• MDX Documentation