Guides
Start typing to search…
  1. getting-started

Documentation Management Guide

Documentation Management Guide

This guide explains how to manage and upload documentation to ReadMe for the Sports Stack API.

Overview

Sports Stack documentation is managed in the readme/ directory and automatically synced to ReadMe via GitHub Actions. This ensures documentation stays in sync with code changes and is version-controlled.

Directory Structure

readme/
├── getting-started/     # Getting Started pages
├── guides/               # User guides
├── api-reference/        # API reference pages
├── recipes/              # Step-by-step recipes
└── changelog/            # Changelog entries

Adding New Documentation

Step 1: Create File in Appropriate Directory

Create a new markdown file in the appropriate readme/ subdirectory:

# For a guide
touch readme/guides/my-new-guide.md

# For API reference
touch readme/api-reference/my-endpoint.md

# For a recipe
touch readme/recipes/my-recipe.md

Step 2: Add Frontmatter

Every file must include YAML frontmatter:

---
title: "Page Title"
category: "Guides"  # Options: "Getting Started", "Guides", "API Reference", "Recipes", "Changelog"
hidden: false
---

# Page Content

Step 3: Write Content

Write your documentation using Markdown:

  • Use standard Markdown syntax
  • Code blocks with language tags
  • Mermaid diagrams supported
  • Tables for structured data

Step 4: Commit and Push

git add readme/guides/my-new-guide.md
git commit -m "Add new guide: My New Guide"
git push origin main

Step 5: Automatic Sync

GitHub Actions automatically syncs changes to ReadMe:

  • Detects changes in readme/ directory
  • Syncs each category separately
  • Updates ReadMe within 1-2 minutes

Using the Migration Script

For migrating existing docs from docs/ to readme/:

# Migrate a guide
./scripts/migrate_docs_to_readme.sh \
  docs/guides/my_guide.md \
  guides \
  "My Guide Title"

# Migrate API reference
./scripts/migrate_docs_to_readme.sh \
  docs/reference/api_doc.md \
  api-reference \
  "API Reference Title"

The script:

  • Copies file to appropriate readme/ directory
  • Adds frontmatter automatically
  • Validates category
  • Provides next steps

File Naming Conventions

Guidelines

  • Use lowercase with hyphens: webhooks-guide.md
  • Be descriptive: setting-up-webhooks-python.md
  • Match ReadMe page titles when possible
  • Keep names consistent across related files

Examples

ReadMe TitleFilename
Webhooks Guidewebhooks-guide.md
Webhook Payload Schemawebhook-payload-schema.md
Setting Up Webhooks in Pythonsetting-up-webhooks-python.md

Frontmatter Reference

Required Fields

---
title: "Page Title"           # Required: Page title in ReadMe
category: "Guides"            # Required: Category name
hidden: false                  # Optional: Hide page (default: false)
---

Category Values

  • Getting Started - For getting-started/ directory
  • Guides - For guides/ directory
  • API Reference - For api-reference/ directory
  • Recipes - For recipes/ directory
  • Changelog - For changelog/ directory

Updating Existing Documentation

Process

  1. Edit file in readme/ directory
  2. Commit changes: 
    git add readme/guides/webhooks-guide.md
git commit -m "Update webhooks guide"
git push origin main
  3. Automatic sync - GitHub Actions syncs to ReadMe
  4. Verify - Check ReadMe to confirm changes

Manual Sync (If Needed)

If automatic sync doesn't work, sync manually:

# Set API key
export README_API_KEY="your-api-key"

# Sync specific file
rdme docs readme/guides/webhooks-guide.md \
  --key="$README_API_KEY" \
  --id=66c91312acd5eb00618a62dd \
  --update

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

Linking Between Pages

Internal Links

Link to other ReadMe pages using relative paths:

# From Guides to API Reference
[Webhook Payload Schema](../../api-reference/webhooks/webhook-payload-schema.md)

# From API Reference to Guides
[Webhooks Guide](../../guides/webhooks-guide.md)

# Within same category
[Another Guide](./another-guide.md)

Cross-Category Links

# From Guides to Getting Started
[Quickstart](../../getting-started/quickstart.md)

# From Getting Started to Guides
[Webhooks Guide](../../guides/webhooks-guide.md)

Best Practices

1. Keep Files Focused

Each file should cover one topic:

  • ✅ webhook-configuration.md - Configuration only
  • ❌ webhooks-everything.md - Too broad

2. Use Consistent Formatting

  • Standard Markdown syntax
  • Code blocks with language tags
  • Tables for structured data
  • Mermaid for diagrams

3. Test Before Committing

  • Check markdown syntax
  • Verify frontmatter format
  • Test internal links
  • Preview formatting

4. Update Related Docs

When updating documentation:

  • Update cross-references
  • Update related guides
  • Update API reference if endpoints change
  • Update changelog for significant changes

GitHub Actions Workflow

Automatic Sync

The .github/workflows/deploy.yml workflow includes:

rdme-docs:
  needs: deploy-api-rest
  runs-on: ubuntu-latest
  if: |
    contains(github.event.head_commit.modified, 'readme/') ||
    contains(github.event.head_commit.added, 'readme/') ||
    github.event_name == 'workflow_dispatch'
  steps:
    - Sync Getting Started docs
    - Sync Guides
    - Sync API Reference
    - Sync Recipes
    - Sync Changelog

Manual Trigger

Trigger sync manually via GitHub Actions:

  1. Go to Actions tab
  2. Select Deploy workflow
  3. Click "Run workflow"
  4. Select branch and click "Run workflow"

Troubleshooting

Sync Not Working

  1. Check GitHub Actions:

    • Go to Actions tab
    • Check if workflow ran
    • Review logs for errors

  2. Verify API Key:

    • Check README_API_KEY secret exists
    • Verify key is valid
    • Test with manual sync

  3. Check File Format:

    • Verify frontmatter syntax
    • Check markdown formatting
    • Ensure file is in correct directory

Pages Not Appearing

  1. Check Category:

    • Verify category exists in ReadMe
    • Check category name matches exactly
    • Ensure category is not hidden

  2. Check Hidden Flag:

    • Set hidden: false in frontmatter
    • Verify page is published in ReadMe

  3. Verify Sync:

    • Check GitHub Actions logs
    • Try manual sync
    • Verify file exists in readme/ directory

Formatting Issues

  1. Markdown Compatibility:

    • Use standard Markdown syntax
    • Test in ReadMe editor
    • Check code block formatting

  2. Mermaid Diagrams:

    • Use ```mermaid code blocks
    • Test diagram syntax
    • Verify ReadMe supports Mermaid

Migration from docs/ to readme/

When to Migrate

Migrate documentation that:

  • Is user-facing (guides, API reference)
  • Should be in ReadMe
  • Is ready for public consumption

Don't migrate:

  • Internal debugging guides
  • Implementation plans
  • Developer-only documentation

Migration Process

  1. Identify files to migrate
  2. Use migration script or manual process
  3. Add frontmatter with title and category
  4. Update links to use ReadMe paths
  5. Test formatting in ReadMe
  6. Commit and push to trigger sync

Related Documentation

Quick Reference

Common Commands

# Migrate a doc
./scripts/migrate_docs_to_readme.sh \
  docs/guides/my_guide.md \
  guides \
  "My Guide"

# Manual sync
rdme docs readme/guides/my-guide.md \
  --key="$README_API_KEY" \
  --id=66c91312acd5eb00618a62dd

# Check sync status
# View GitHub Actions → Deploy workflow

Project Info

Updated 29 days ago