Skip to content

HOW-IT-WORKS.md

Latest commit

 

History

History
190 lines (142 loc) · 4.74 KB

HOW-IT-WORKS.md

File metadata and controls

190 lines (142 loc) · 4.74 KB

How Documentation Syncing Works

The Problem We Solved

GitHub was showing documentation folders (ai-sdk, astro, convex, effectts) as external links (submodules) instead of browsable folders. This happened because each folder had its own .git directory.

The Solution

We set up a hybrid approach:

On GitHub (Browsable)

  • All 2,316 documentation files are visible and clickable
  • No submodules, just regular folders
  • Perfect for browsing docs directly on GitHub

Locally (Syncable)

  • .git directories preserved in each documentation folder
  • sync.sh script still works to pull upstream changes
  • Can run local git operations in each folder

How It Works

1. .gitignore Configuration

# Git directories in subfolders (keep local for syncing, exclude from GitHub)
ai-sdk/.git/
astro/.git/
convex/.git/
effectts/.git/

This tells Git to:

  • ✅ Track all documentation files
  • ❌ Ignore .git directories (don't push them to GitHub)

2. Local Syncing

The sync.sh script works because:

  • .git directories exist locally (not pushed to GitHub)
  • Each folder can run git pull to get upstream updates
  • Documentation files are then committed to the main docs repo

3. GitHub Display

On GitHub you see:

  • ✅ ai-sdk/ folder with 810 browsable files
  • ✅ astro/ folder with 795 browsable files
  • ✅ convex/ folder with 434 browsable files
  • ✅ effectts/ folder with 276 browsable files

Keeping Docs Updated

Run Sync Locally

cd /Users/toc/Server/ONE/docs

# Test first (dry run)
./sync.sh --dry-run

# Run sync
./sync.sh

# Commit and push updates
git add -A
git commit -m "docs: sync upstream documentation sources"
git push origin main

What Happens

  1. sync.sh pulls latest changes from upstream repos into local folders
  2. You review the changes with git status
  3. You commit the file changes (not .git directories)
  4. You push to GitHub
  5. All docs remain browsable on GitHub

Documentation Sources

Folder Upstream Repository Local .git GitHub Files
ai-sdk/ https://github.com/vercel/ai ✅ Syncs ✅ Browsable
astro/ https://github.com/withastro/docs ✅ Syncs ✅ Browsable
convex/ https://github.com/get-convex/convex-backend ✅ Syncs ✅ Browsable
effectts/ https://github.com/Effect-TS/website ✅ Syncs ✅ Browsable
claude-code/ Maintained directly N/A ✅ Browsable

File Counts

  • AI SDK: 810 files
  • Astro: 795 files
  • Convex: 434 files
  • Effect TS: 276 files
  • Total: 2,315 documentation files + README, sync scripts

Benefits

✅ All docs browsable on GitHub

  • No submodule links
  • Click through folders and files
  • Read docs directly on GitHub

✅ Easy local syncing

  • Run ./sync.sh to update all docs
  • Automatic upstream tracking
  • No manual work needed

✅ Version controlled

  • Full git history
  • Can revert changes
  • Track upstream updates

Commands Reference

# View current status
git status

# Sync all documentation
./sync.sh

# Sync with dry-run (preview only)
./sync.sh --dry-run

# Manual sync individual folder
cd ai-sdk && git pull origin main

# Commit docs updates
git add -A
git commit -m "docs: sync upstream documentation sources"
git push origin main

Troubleshooting

Issue: sync.sh not working

Check .git directories exist locally:

ls -la ai-sdk/.git astro/.git convex/.git effectts/.git

If missing, the .git directories were accidentally pushed. Contact for help.

Issue: Files showing as submodules on GitHub

The .git directories should NOT be pushed. They should be in .gitignore:

cat .gitignore | grep ".git/"

Should show:

ai-sdk/.git/
astro/.git/
convex/.git/
effectts/.git/

Architecture Diagram

GitHub Repository (one-ie/docs)
├── README.md (browsable)
├── SYNC-GUIDE.md (browsable)
├── sync.sh (browsable)
├── ai-sdk/ (browsable folder)
│   ├── docs/ (browsable)
│   ├── cookbook/ (browsable)
│   └── [.git/ - local only, ignored by GitHub]
├── astro/ (browsable folder)
│   └── [.git/ - local only, ignored by GitHub]
├── convex/ (browsable folder)
│   └── [.git/ - local only, ignored by GitHub]
└── effectts/ (browsable folder)
    └── [.git/ - local only, ignored by GitHub]

Local Machine
├── .git/ (main repo)
└── docs/
    ├── ai-sdk/.git/ ← tracks vercel/ai
    ├── astro/.git/ ← tracks withastro/docs
    ├── convex/.git/ ← tracks get-convex/convex-backend
    └── effectts/.git/ ← tracks Effect-TS/website

Result: Best of both worlds - browsable docs on GitHub + local sync capability! 🎉