fix: require VITE_CONVEX_URL env var for edge functions and clarify publishing workflow

- Add VITE_CONVEX_URL requirement to Netlify env vars for edge function runtime
- Improve error messages in edge functions when Convex URL is missing
- Add "How publishing works" explanation to README, setup guide, and docs
- Update deployment instructions across all documentation

README.md

@@ -2,6 +2,8 @@
 
 A minimalist markdown site built with React, Convex, and Vite. Optimized for SEO, AI agents, and LLM discovery.
 
+**How publishing works:** Write posts in markdown, run `npm run sync`, and they appear on your live site immediately. No rebuild or redeploy needed. Convex handles real-time data sync, so all connected browsers update automatically.
+
 ## Features
 
 - Markdown-based blog posts with frontmatter
@@ -196,14 +198,17 @@ For detailed setup, see the [Convex Netlify Deployment Guide](https://docs.conve
 npx convex deploy
 ```
 
+Note the production URL (e.g., `https://your-deployment.convex.cloud`).
+
 2. Connect your repository to Netlify
 3. Configure build settings:
    - Build command: `npm ci --include=dev && npx convex deploy --cmd 'npm run build'`
    - Publish directory: `dist`
-4. Add environment variable:
+4. Add environment variables in Netlify dashboard:
    - `CONVEX_DEPLOY_KEY` - Generate from [Convex Dashboard](https://dashboard.convex.dev) > Project Settings > Deploy Key
+   - `VITE_CONVEX_URL` - Your production Convex URL (e.g., `https://your-deployment.convex.cloud`)
 
-The `CONVEX_DEPLOY_KEY` lets Netlify automatically deploy functions and set `VITE_CONVEX_URL` on each build. Edge functions dynamically proxy RSS, sitemap, and API requests to your Convex HTTP endpoints.
+The `CONVEX_DEPLOY_KEY` deploys functions at build time. The `VITE_CONVEX_URL` is required for edge functions (RSS, sitemap, API) to proxy requests at runtime.
 
 **Build issues?** Netlify sets `NODE_ENV=production` which skips devDependencies. The `--include=dev` flag fixes this. See [netlify-deploy-fix.md](./netlify-deploy-fix.md) for detailed troubleshooting.
 

content/blog/setup-guide.md

@@ -12,6 +12,8 @@ readTime: "8 min read"
 
 This guide walks you through forking [this markdown site](https://github.com/waynesutton/markdown-site), setting up your Convex backend, and deploying to Netlify. The entire process takes about 10 minutes.
 
+**How publishing works:** Once deployed, you write posts in markdown, run `npm run sync`, and they appear on your live site immediately. No rebuild or redeploy needed. Convex handles real-time data sync, so all connected browsers update automatically.
+
 ## Table of Contents
 
 - [Fork and Deploy Your Own Markdown Blog](#fork-and-deploy-your-own-markdown-blog)
@@ -208,9 +210,10 @@ npm run deploy
    - Publish directory: `dist`
 5. Add environment variables:
    - `CONVEX_DEPLOY_KEY`: Generate from [Convex Dashboard](https://dashboard.convex.dev) > Project Settings > Deploy Key
+   - `VITE_CONVEX_URL`: Your production Convex URL (e.g., `https://your-deployment.convex.cloud`)
 6. Click "Deploy site"
 
-The `CONVEX_DEPLOY_KEY` allows Netlify to automatically deploy your Convex functions and set the correct `VITE_CONVEX_URL` on each build.
+The `CONVEX_DEPLOY_KEY` deploys functions at build time. The `VITE_CONVEX_URL` is required for edge functions to proxy RSS, sitemap, and API requests at runtime.
 
 ### Netlify Build Configuration
 

content/pages/docs.md

@@ -7,6 +7,8 @@ order: 0
 
 Reference documentation for setting up, customizing, and deploying this markdown site.
 
+**How publishing works:** Write posts in markdown, run `npm run sync`, and they appear on your live site immediately. No rebuild or redeploy needed. Convex handles real-time data sync, so connected browsers update automatically.
+
 ## Quick start
 
 ```bash
@@ -194,9 +196,11 @@ body {
 1. Connect GitHub repo to Netlify
 2. Build command: `npm ci --include=dev && npx convex deploy --cmd 'npm run build'`
 3. Publish directory: `dist`
-4. Add env variable: `CONVEX_DEPLOY_KEY` (from Convex Dashboard)
+4. Add env variables:
+   - `CONVEX_DEPLOY_KEY` (from Convex Dashboard > Project Settings > Deploy Key)
+   - `VITE_CONVEX_URL` (your production Convex URL, e.g., `https://your-deployment.convex.cloud`)
 
-The build automatically sets `VITE_CONVEX_URL` from the deploy key.
+Both are required: deploy key for builds, URL for edge function runtime.
 
 ### Convex production
 

netlify/edge-functions/api.ts

@@ -10,11 +10,11 @@ export default async function handler(
 
   if (!convexUrl) {
     return new Response(
-      JSON.stringify({ error: "Configuration error: Missing Convex URL" }),
-      {
-        status: 500,
-        headers: { "Content-Type": "application/json" },
-      },
+      JSON.stringify({
+        error:
+          "VITE_CONVEX_URL not set. Add it to Netlify environment variables.",
+      }),
+      { status: 500, headers: { "Content-Type": "application/json" } },
     );
   }
 

netlify/edge-functions/rss.ts

@@ -9,9 +9,10 @@ export default async function handler(
     Deno.env.get("VITE_CONVEX_URL") || Deno.env.get("CONVEX_URL");
 
   if (!convexUrl) {
-    return new Response("Configuration error: Missing Convex URL", {
-      status: 500,
-    });
+    return new Response(
+      "Configuration error: VITE_CONVEX_URL not set. Add it to Netlify environment variables.",
+      { status: 500, headers: { "Content-Type": "text/plain" } },
+    );
   }
 
   // Construct the Convex site URL for the HTTP endpoint

netlify/edge-functions/sitemap.ts

@@ -9,9 +9,10 @@ export default async function handler(
     Deno.env.get("VITE_CONVEX_URL") || Deno.env.get("CONVEX_URL");
 
   if (!convexUrl) {
-    return new Response("Configuration error: Missing Convex URL", {
-      status: 500,
-    });
+    return new Response(
+      "Configuration error: VITE_CONVEX_URL not set. Add it to Netlify environment variables.",
+      { status: 500, headers: { "Content-Type": "text/plain" } },
+    );
   }
 
   // Construct the Convex site URL for the HTTP endpoint

src/pages/Home.tsx

@@ -22,7 +22,7 @@ const siteConfig = {
       , customize it, ship it.
     </>
   ),
-  bio: `Write in markdown, sync to a real-time database, and deploy in minutes. Built with React, TypeScript, and Convex for instant updates without rebuilds.`,
+  bio: `Write in markdown, sync to a real-time database, and deploy in minutes. Every time you sync new posts, they appear immediately without redeploying. Built with React, TypeScript, and Convex for instant updates.`,
   featuredEssays: [
     { title: "Setup Guide", slug: "setup-guide" },
     { title: "How to Publish", slug: "how-to-publish" },