# Cloudflare Pages Setup Guide

> **Purpose:** Host a private GitHub repository as a static website using Cloudflare Pages — accessible from anywhere with a simple URL.

---

## Overview

This guide documents the complete process of connecting a local `learning-content` folder (Obsidian vault) to GitHub and serving it online via Cloudflare Pages.

## What You Achieved

- ✅ Local markdown notes synced to GitHub
- ✅ Private repo hosted as a static website
- ✅ Accessible via: `https://learning-content.pages.dev`
- ✅ Free hosting with no subscription required

---

## Process Flow (Mermaid Diagram)

```mermaid
flowchart TD
    A[Local Folder<br/>C:\Users\HP\Documents\learning-content] -->|git init| B[Local Git Repo]
    B -->|git add + commit| C[Staged Changes]
    C -->|git remote add origin| D[GitHub Repository<br/>Private]
    D -->|git push| E[GitHub Remote]
    E -->|Cloudflare Pages<br/>Connect to Git| F[Cloudflare Pages Project]
    F -->|Auto Deploy| G[Live Website<br/>learning-content.pages.dev]
    
    style A fill:#e1f5fe
    style D fill:#fff3e0
    style G fill:#e8f5e9
```

---

## Step-by-Step Instructions

### Phase 1: Push Local Folder to GitHub

| Step | Command / Action | Notes |
|---|---|---|
| 1 | `git init` | Initialize git in your local folder |
| 2 | `git add -A` | Stage all files |
| 3 | `git commit -m "Initial commit"` | Commit changes |
| 4 | Create repo on GitHub (private) | Name it `learning-content` |
| 5 | `git remote add origin https://github.com/YOURNAME/learning-content.git` | Link local to remote |
| 6 | `git push -u origin main` | Push to GitHub |

> ⚠️ **If you get "submodule errors" on Cloudflare later**, see Troubleshooting below.

---

### Phase 2: Deploy via Cloudflare Pages

| Step | Action | Details |
|---|---|---|
| 1 | Go to [dash.cloudflare.com](https://dash.cloudflare.com) | Log into your account |
| 2 | Click **Workers & Pages** → **Create** → **Pages** | NOT Workers |
| 3 | Select **"Connect to Git"** | Authorize GitHub if needed |
| 4 | Choose your `learning-content` repository | Select from the list |
| 5 | Configure build settings | Leave **Build command** empty |
| 6 | Set **Build output directory** to `.` | Single dot = root folder |
| 7 | Click **"Save and Deploy"** | Wait 1-2 minutes |
| 8 | Done! 🎉 | Site is live at `*.pages.dev` |

---

## Troubleshooting

### Issue: "Failed to load repositories" in Cloudflare
**Cause:** Cloudflare's GitHub App doesn't have permission.

**Fix:**
1. GitHub → Settings → Applications → Cloudflare Pages
2. Configure → Repository access → Select "All repositories" or add `learning-content`
3. Save and retry

---

### Issue: "error occurred while updating repository submodules"
**Cause:** Your repo contains Git submodules (nested `.git` folders inside sub-directories). Cloudflare cannot clone SSH-based submodules.

**Fix:**
```bash
# 1. Remove submodule from git index
git rm --cached "path/to/submodule-folder"

# 2. Delete all nested .git directories
# Find them first:
Get-ChildItem -Recurse -Filter ".git" -Force

# Remove all EXCEPT the root .git:
Remove-Item -Path "path/to/nested/.git" -Recurse -Force

# 3. Stage, commit, and push
git add -A
git commit -m "Remove submodule references"
git push origin main
```

---

### Issue: "Could not detect static files" (Deploy fails)
**Cause:** Project created as **Workers** instead of **Pages**.

**Fix:**
1. Delete the project in Cloudflare
2. Recreate as **Pages** (not Workers)
3. Reconnect the GitHub repo

---

### Issue: GitHub Pages requires paid plan for private repos
**Cause:** GitHub Pages is free for public repos, paid for private ones.

**Workaround:** Use **Cloudflare Pages** instead — it's free for private repos.

---

## Privacy Considerations

Your Cloudflare Pages site gets a **random subdomain** like:
```
https://learning-content.pages.dev
```

To keep it effectively private:
- **Don't share the URL** anywhere public
- **Add `robots.txt`** to block search engines:
  ```
  User-agent: *
  Disallow: /
  ```
- **Optional:** Use Cloudflare Access (Zero Trust) for email-based login wall

---

## Quick Reference: Useful Commands

```bash
# Check git status
git status

# Check for submodules in index
git ls-files --stage | grep "160000"

# View recent commits
git log --oneline -5

# Force push (use with caution)
git push origin main --force

# Pull latest from GitHub
git pull origin main
```

---

## Resources

- [Cloudflare Pages Docs](https://developers.cloudflare.com/pages/)
- [GitHub Pages Docs](https://docs.github.com/en/pages)
- [Git Submodules Guide](https://git-scm.com/book/en/v2/Git-Tools-Submodules)

---

*Created: 2026-05-24*  
*Goal: learning-content folder → GitHub → Cloudflare Pages → Live website*