# How to Upload Documentation to ReadMe

# 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](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](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

```bash
# Install rdme CLI globally
npm install -g rdme

# Or use npx (no installation needed)
npx rdme
```

### Authentication

```bash
# 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

```bash
# Generate OpenAPI spec first
mix openapi.gen

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

### Upload Markdown Files

```bash
# 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

```bash
# 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`:

```yaml
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

```bash
# 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

```bash
# 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](https://sportsstack.readme.io)
* **Project ID**: `66c91312acd5eb00618a62dd`
* **API Key**: Get from ReadMe Dashboard → API Keys

### Common Commands

```bash
# 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](https://docs.readme.com/main/docs/about-readme)
* [ReadMe CLI Documentation](https://docs.readme.com/main/docs/syncing-docs-via-cli-github-action)
* [GitHub Sync Guide](https://docs.readme.com/main/docs/sync-with-github)
* [MDX Documentation](https://docs.readme.com/main/docs/mdx)