- {/* ... existing page rendering ... */}
-
- );
-}
-```
-
-### Step 8: Unsubscribe Page
-
-**File:** `src/pages/Unsubscribe.tsx`Create unsubscribe page:
-
-```typescript
-import { useSearchParams, useNavigate } from "react-router-dom";
+import { useState } from "react";
import { useMutation } from "convex/react";
import { api } from "../../convex/_generated/api";
-import { useState, useEffect } from "react";
+import siteConfig from "../config/siteConfig";
-export default function Unsubscribe() {
- const [searchParams] = useSearchParams();
- const navigate = useNavigate();
- const email = searchParams.get("email");
- const token = searchParams.get("token");
- const unsubscribeMutation = useMutation(api.newsletter.unsubscribe);
- const [status, setStatus] = useState<"loading" | "success" | "error" | "idle">("idle");
+interface NewsletterSignupProps {
+ source: "home" | "blog-page" | "post";
+ postSlug?: string; // For tracking which post they subscribed from
+ title?: string;
+ description?: string;
+}
+
+export default function NewsletterSignup({
+ source,
+ postSlug,
+ title,
+ description,
+}: NewsletterSignupProps) {
+ const [email, setEmail] = useState("");
+ const [status, setStatus] = useState<"idle" | "loading" | "success" | "error">("idle");
const [message, setMessage] = useState("");
- useEffect(() => {
- if (email && token) {
- handleUnsubscribe();
- }
- }, [email, token]);
+ const subscribe = useMutation(api.newsletter.subscribe);
- const handleUnsubscribe = async () => {
- if (!email || !token) {
+ // Check if newsletter is enabled
+ if (!siteConfig.newsletter?.enabled) return null;
+
+ // Get config for this placement
+ const config = source === "home"
+ ? siteConfig.newsletter.signup.home
+ : source === "blog-page"
+ ? siteConfig.newsletter.signup.blogPage
+ : siteConfig.newsletter.signup.posts;
+
+ if (!config.enabled) return null;
+
+ const displayTitle = title || config.title;
+ const displayDescription = description || config.description;
+
+ const handleSubmit = async (e: React.FormEvent) => {
+ e.preventDefault();
+
+ if (!email.trim()) {
setStatus("error");
- setMessage("Invalid unsubscribe link.");
+ setMessage("Please enter your email.");
return;
}
setStatus("loading");
+
try {
- const result = await unsubscribeMutation({ email, token });
- setStatus(result.success ? "success" : "error");
- setMessage(result.message);
- } catch (error) {
+ const sourceValue = postSlug ? `post:${postSlug}` : source;
+ const result = await subscribe({ email, source: sourceValue });
+
+ if (result.success) {
+ setStatus("success");
+ setMessage(result.message);
+ setEmail("");
+ } else {
+ setStatus("error");
+ setMessage(result.message);
+ }
+ } catch {
setStatus("error");
- setMessage("An error occurred. Please try again.");
+ setMessage("Something went wrong. Please try again.");
}
};
return (
-
-
+ Unsubscribe
- {status === "loading" &&Processing...
} - {status === "success" && ( - <> -{message}
- - - )} - {status === "error" &&{message}
} - {status === "idle" && ( -Use the unsubscribe link from your email to unsubscribe.
- )} -
+
+ {displayTitle}
+ {displayDescription && ( +{displayDescription}
+ )} + + {status === "success" ? ( +{message}
+ ) : ( + + )} + + {status === "error" && ( +{message}
+ )} +
+
+ );
+}
+```
+
+#### 1E.2: Add Route
+
+**File:** `src/App.tsx`
+
+```typescript
+import Unsubscribe from "./pages/Unsubscribe";
+
+// Add route
+Unsubscribe
+ + {status === "loading" &&Processing...
} + + {status === "success" && ( + <> +{message}
+ Back to home + + )} + + {status === "error" && ( +{message}
+ )} + + {status === "idle" && !email && !token && ( +Use the unsubscribe link from your email.
+ )} +${post.title}
+${post.description}
+ ++
+ Unsubscribe +
+ `; + + try { + await fetch("https://api.agentmail.to/v1/emails", { + method: "POST", + headers: { + Authorization: `Bearer ${apiKey}`, + "Content-Type": "application/json", + }, + body: JSON.stringify({ + from: { email: inbox }, + to: [{ email: subscriber.email }], + subject: `New: ${post.title}`, + html, + }), + }); + sentCount++; + } catch (error) { + console.error(`Failed to send to ${subscriber.email}:`, error); + } + } + + // Record sent + await ctx.runMutation(internal.newsletter.recordPostSent, { + postSlug: args.postSlug, + sentCount, + }); + + return { + success: true, + sentCount, + message: `Sent to ${sentCount} subscribers.`, + }; + }, +}); +``` + +### 2.3: CLI Send Script + +**File:** `scripts/send-newsletter.ts` + +```typescript +import { ConvexHttpClient } from "convex/browser"; +import { internal } from "../convex/_generated/api"; +import dotenv from "dotenv"; + +dotenv.config({ path: ".env.local" }); + +const client = new ConvexHttpClient(process.env.VITE_CONVEX_URL!); + +const postSlug = process.argv[2]; +const siteUrl = process.env.SITE_URL || "https://markdown.fast"; + +if (!postSlug) { + console.error("Usage: npm run newsletter:send
+
+
+
+ `;
+
+ // Plain text version
+ const text = `New Contact Form Submission\n\nFrom: ${args.name}\nEmail: ${args.email}\nSource: ${args.source}\n\nMessage:\n${args.message}`;
+
+ try {
+ // Initialize AgentMail client with API key
+ const client = new AgentMailClient({ apiKey });
+
+ // Send email using official SDK
+ // https://docs.agentmail.to/sending-receiving-email
+ await client.inboxes.messages.send(inbox, {
+ to: recipientEmail,
+ subject: `Contact: ${args.name} via ${args.source}`,
+ text,
+ html,
+ });
+
+ // Mark email as sent in database
+ await ctx.runMutation(internal.contact.markEmailSent, {
+ messageId: args.messageId,
+ });
+ } catch {
+ // Silently fail on error
+ }
+
+ return null;
+ },
+});
+
+// Helper function to escape HTML entities
+function escapeHtml(text: string): string {
+ return text
+ .replace(/&/g, "&")
+ .replace(//g, ">")
+ .replace(/"/g, """)
+ .replace(/'/g, "'");
+}
diff --git a/convex/crons.ts b/convex/crons.ts
index 84a6de9..14de24d 100644
--- a/convex/crons.ts
+++ b/convex/crons.ts
@@ -11,5 +11,29 @@ crons.interval(
{}
);
+// Weekly digest: Send every Sunday at 9:00 AM UTC
+// Posts from the last 7 days are included
+// To disable, set weeklyDigest.enabled: false in siteConfig.ts
+crons.cron(
+ "weekly newsletter digest",
+ "0 9 * * 0", // 9:00 AM UTC on Sundays
+ internal.newsletterActions.sendWeeklyDigest,
+ {
+ siteUrl: process.env.SITE_URL || "https://example.com",
+ siteName: process.env.SITE_NAME || "Newsletter",
+ }
+);
+
+// Weekly stats summary: Send every Monday at 9:00 AM UTC
+// Includes subscriber count, new subscribers, newsletters sent
+crons.cron(
+ "weekly stats summary",
+ "0 9 * * 1", // 9:00 AM UTC on Mondays
+ internal.newsletterActions.sendWeeklyStatsSummary,
+ {
+ siteName: process.env.SITE_NAME || "Newsletter",
+ }
+);
+
export default crons;
diff --git a/convex/http.ts b/convex/http.ts
index ef9a22b..46c9609 100644
--- a/convex/http.ts
+++ b/convex/http.ts
@@ -41,7 +41,7 @@ http.route({
`,
// All posts
...posts.map(
- (post) => ` New Contact Form Submission
+| From: | +${escapeHtml(args.name)} | +
| Email: | +${escapeHtml(args.email)} | +
| Source: | +${escapeHtml(args.source)} | +
Message:
+${escapeHtml(args.message)}
+ $1
') + .replace(/^## (.+)$/gm, '$1
') + .replace(/^# (.+)$/gm, '$1
') + // Bold and italic + .replace(/\*\*(.+?)\*\*/g, '$1') + .replace(/\*(.+?)\*/g, '$1') + .replace(/__(.+?)__/g, '$1') + .replace(/_(.+?)_/g, '$1') + // Links + .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '$1') + // Unordered lists + .replace(/^- (.+)$/gm, '- $&
')
+ // Single line breaks
+ .replace(/\n/g, '
');
+
+ // Wrap in paragraph if not starting with a block element
+ if (!html.startsWith('
+
+
+ `;
+
+ // Plain text version
+ const text = `${post.title}\n\n${post.description}\n\nRead more: ${postUrl}\n\n---\nUnsubscribe: ${unsubscribeUrl}`;
+
+ // Send email using AgentMail SDK
+ try {
+ await client.inboxes.messages.send(inbox, {
+ to: subscriber.email,
+ subject: `New: ${post.title}`,
+ html,
+ text,
+ });
+ sentCount++;
+ } catch (error) {
+ const errorMessage =
+ error instanceof Error ? error.message : "Unknown error";
+ errors.push(`${subscriber.email}: ${errorMessage}`);
+ }
+ }
+
+ // Record sent if at least one email was sent
+ if (sentCount > 0) {
+ await ctx.runMutation(internal.newsletter.recordPostSent, {
+ postSlug: args.postSlug,
+ sentCount,
+ });
+ }
+
+ // Build result message
+ let resultMessage: string = `Sent to ${sentCount} of ${subscribers.length} subscribers.`;
+ if (errors.length > 0) {
+ resultMessage += ` ${errors.length} failed.`;
+ }
+
+ return { success: sentCount > 0, sentCount, message: resultMessage };
+ },
+});
+
+// Helper function to escape HTML entities
+function escapeHtml(text: string): string {
+ return text
+ .replace(/&/g, "&")
+ .replace(//g, ">")
+ .replace(/"/g, """)
+ .replace(/'/g, "'");
+}
+
+// Send weekly digest email to all active subscribers
+// Includes all posts published in the last 7 days
+export const sendWeeklyDigest = internalAction({
+ args: {
+ siteUrl: v.string(),
+ siteName: v.optional(v.string()),
+ },
+ returns: v.object({
+ success: v.boolean(),
+ sentCount: v.number(),
+ postCount: v.number(),
+ message: v.string(),
+ }),
+ handler: async (ctx, args) => {
+ // Get subscribers
+ const subscribers: Array<{ email: string; unsubscribeToken: string }> =
+ await ctx.runQuery(internal.newsletter.getActiveSubscribers);
+
+ if (subscribers.length === 0) {
+ return {
+ success: false,
+ sentCount: 0,
+ postCount: 0,
+ message: "No subscribers.",
+ };
+ }
+
+ // Get posts from last 7 days
+ const sevenDaysAgo = new Date();
+ sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);
+ const cutoffDate = sevenDaysAgo.toISOString().split("T")[0];
+
+ const recentPosts: Array<{
+ slug: string;
+ title: string;
+ description: string;
+ date: string;
+ excerpt?: string;
+ }> = await ctx.runQuery(internal.posts.getRecentPostsInternal, {
+ since: cutoffDate,
+ });
+
+ if (recentPosts.length === 0) {
+ return {
+ success: true,
+ sentCount: 0,
+ postCount: 0,
+ message: "No new posts in the last 7 days.",
+ };
+ }
+
+ // Get API key and inbox from environment
+ const apiKey = process.env.AGENTMAIL_API_KEY;
+ const inbox = process.env.AGENTMAIL_INBOX;
+
+ if (!apiKey || !inbox) {
+ return {
+ success: false,
+ sentCount: 0,
+ postCount: 0,
+ message: ENV_VAR_ERROR_MESSAGE,
+ };
+ }
+
+ const siteName = args.siteName || "Newsletter";
+ let sentCount = 0;
+ const errors: Array${escapeHtml(post.title)}
+${escapeHtml(post.description)}
+ ${post.excerpt ? `${escapeHtml(post.excerpt)}
` : ""} ++ Read more +
++
+ You received this email because you subscribed to ${escapeHtml(siteName)}.
+ Unsubscribe
+
+
+
+ `;
+
+ const text = `Weekly Digest - ${recentPosts.length} new post${recentPosts.length > 1 ? "s" : ""}\n\n${postsText}\n\n---\nUnsubscribe: ${unsubscribeUrl}`;
+
+ try {
+ await client.inboxes.messages.send(inbox, {
+ to: subscriber.email,
+ subject: `Weekly Digest: ${recentPosts.length} new post${recentPosts.length > 1 ? "s" : ""}`,
+ html,
+ text,
+ });
+ sentCount++;
+ } catch (error) {
+ const errorMessage =
+ error instanceof Error ? error.message : "Unknown error";
+ errors.push(`${subscriber.email}: ${errorMessage}`);
+ }
+ }
+
+ let resultMessage: string = `Sent ${recentPosts.length} post${recentPosts.length > 1 ? "s" : ""} to ${sentCount} of ${subscribers.length} subscribers.`;
+ if (errors.length > 0) {
+ resultMessage += ` ${errors.length} failed.`;
+ }
+
+ return {
+ success: sentCount > 0,
+ sentCount,
+ postCount: recentPosts.length,
+ message: resultMessage,
+ };
+ },
+});
+
+// Send new subscriber notification to developer
+// Called when a new subscriber signs up
+export const notifyNewSubscriber = internalAction({
+ args: {
+ email: v.string(),
+ source: v.string(),
+ siteName: v.optional(v.string()),
+ },
+ returns: v.object({
+ success: v.boolean(),
+ message: v.string(),
+ }),
+ handler: async (_ctx, args) => {
+ // Get API key and inbox from environment
+ const apiKey = process.env.AGENTMAIL_API_KEY;
+ const inbox = process.env.AGENTMAIL_INBOX;
+ const contactEmail = process.env.AGENTMAIL_CONTACT_EMAIL || inbox;
+
+ if (!apiKey || !contactEmail) {
+ return {
+ success: false,
+ message: ENV_VAR_ERROR_MESSAGE,
+ };
+ }
+
+ const siteName = args.siteName || "Your Site";
+ const timestamp = new Date().toLocaleString("en-US", {
+ dateStyle: "medium",
+ timeStyle: "short",
+ });
+
+ const client = new AgentMailClient({ apiKey });
+
+ try {
+ await client.inboxes.messages.send(inbox!, {
+ to: contactEmail,
+ subject: `New subscriber: ${args.email}`,
+ html: `
+ Weekly Digest
+${recentPosts.length} new post${recentPosts.length > 1 ? "s" : ""} from ${escapeHtml(siteName)}
+ ${postsHtml} ++
+ You received this email because you subscribed to ${escapeHtml(siteName)}.
+ Unsubscribe
+
+
+
+ `,
+ text: `New Newsletter Subscriber\n\nEmail: ${args.email}\nSource: ${args.source}\nTime: ${timestamp}`,
+ });
+
+ return { success: true, message: "Notification sent." };
+ } catch (error) {
+ const errorMessage =
+ error instanceof Error ? error.message : "Unknown error";
+ return { success: false, message: errorMessage };
+ }
+ },
+});
+
+// Send weekly stats summary to developer
+// Includes subscriber count, new subscribers, newsletters sent
+export const sendWeeklyStatsSummary = internalAction({
+ args: {
+ siteName: v.optional(v.string()),
+ },
+ returns: v.object({
+ success: v.boolean(),
+ message: v.string(),
+ }),
+ handler: async (ctx, args) => {
+ // Get API key and inbox from environment
+ const apiKey = process.env.AGENTMAIL_API_KEY;
+ const inbox = process.env.AGENTMAIL_INBOX;
+ const contactEmail = process.env.AGENTMAIL_CONTACT_EMAIL || inbox;
+
+ if (!apiKey || !contactEmail) {
+ return { success: false, message: ENV_VAR_ERROR_MESSAGE };
+ }
+
+ const siteName = args.siteName || "Your Site";
+
+ // Get stats from database
+ const stats = await ctx.runQuery(internal.newsletter.getStatsForSummary);
+
+ const client = new AgentMailClient({ apiKey });
+
+ try {
+ await client.inboxes.messages.send(inbox!, {
+ to: contactEmail,
+ subject: `Weekly Stats: ${stats.activeSubscribers} subscribers`,
+ html: `
+ New Newsletter Subscriber
+
+ Email: ${escapeHtml(args.email)}
+ Source: ${escapeHtml(args.source)}
+ Time: ${timestamp}
+
+
+ This is an automated notification from ${escapeHtml(siteName)}. +
+
+
+
+ `,
+ text: `Weekly Newsletter Stats\n\nActive Subscribers: ${stats.activeSubscribers}\nTotal Subscribers: ${stats.totalSubscribers}\nNew This Week: ${stats.newThisWeek}\nUnsubscribed: ${stats.unsubscribedCount}\nNewsletters Sent: ${stats.totalNewslettersSent}`,
+ });
+
+ return { success: true, message: "Stats summary sent." };
+ } catch (error) {
+ const errorMessage =
+ error instanceof Error ? error.message : "Unknown error";
+ return { success: false, message: errorMessage };
+ }
+ },
+});
+
+// Send custom newsletter email to all active subscribers
+// Supports markdown content that gets converted to HTML
+export const sendCustomNewsletter = internalAction({
+ args: {
+ subject: v.string(),
+ content: v.string(), // Markdown content
+ siteUrl: v.string(),
+ siteName: v.optional(v.string()),
+ },
+ returns: v.object({
+ success: v.boolean(),
+ sentCount: v.number(),
+ message: v.string(),
+ }),
+ handler: async (ctx, args) => {
+ // Get subscribers
+ const subscribers: Array<{ email: string; unsubscribeToken: string }> =
+ await ctx.runQuery(internal.newsletter.getActiveSubscribers);
+
+ if (subscribers.length === 0) {
+ return { success: false, sentCount: 0, message: "No subscribers." };
+ }
+
+ // Get API key and inbox from environment
+ const apiKey = process.env.AGENTMAIL_API_KEY;
+ const inbox = process.env.AGENTMAIL_INBOX;
+
+ if (!apiKey || !inbox) {
+ return {
+ success: false,
+ sentCount: 0,
+ message: ENV_VAR_ERROR_MESSAGE,
+ };
+ }
+
+ const siteName = args.siteName || "Newsletter";
+ let sentCount = 0;
+ const errors: ArrayWeekly Newsletter Stats
+
+
+
+ Active Subscribers: ${stats.activeSubscribers}
+ Total Subscribers: ${stats.totalSubscribers}
+ New This Week: ${stats.newThisWeek}
+ Unsubscribed: ${stats.unsubscribedCount}
+ Newsletters Sent: ${stats.totalNewslettersSent}
+
+
+ This is an automated weekly summary from ${escapeHtml(siteName)}. +
+
+ ${contentHtml}
+
+
+ `;
+
+ const text = `${contentText}\n\n---\nUnsubscribe: ${unsubscribeUrl}`;
+
+ try {
+ await client.inboxes.messages.send(inbox, {
+ to: subscriber.email,
+ subject: args.subject,
+ html,
+ text,
+ });
+ sentCount++;
+ } catch (error) {
+ const errorMessage =
+ error instanceof Error ? error.message : "Unknown error";
+ errors.push(`${subscriber.email}: ${errorMessage}`);
+ }
+ }
+
+ // Record custom email send if at least one email was sent
+ if (sentCount > 0) {
+ await ctx.runMutation(internal.newsletter.recordCustomSent, {
+ subject: args.subject,
+ sentCount,
+ });
+ }
+
+ let resultMessage: string = `Sent to ${sentCount} of ${subscribers.length} subscribers.`;
+ if (errors.length > 0) {
+ resultMessage += ` ${errors.length} failed.`;
+ }
+
+ return { success: sentCount > 0, sentCount, message: resultMessage };
+ },
+});
+
diff --git a/convex/pages.ts b/convex/pages.ts
index 821a31b..d7d7faa 100644
--- a/convex/pages.ts
+++ b/convex/pages.ts
@@ -128,7 +128,10 @@ export const getPageBySlug = query({
rightSidebar: v.optional(v.boolean()),
showFooter: v.optional(v.boolean()),
footer: v.optional(v.string()),
+ showSocialFooter: v.optional(v.boolean()),
aiChat: v.optional(v.boolean()),
+ contactForm: v.optional(v.boolean()),
+ newsletter: v.optional(v.boolean()),
}),
v.null(),
),
@@ -161,7 +164,10 @@ export const getPageBySlug = query({
rightSidebar: page.rightSidebar,
showFooter: page.showFooter,
footer: page.footer,
+ showSocialFooter: page.showSocialFooter,
aiChat: page.aiChat,
+ contactForm: page.contactForm,
+ newsletter: page.newsletter,
};
},
});
@@ -188,7 +194,10 @@ export const syncPagesPublic = mutation({
rightSidebar: v.optional(v.boolean()),
showFooter: v.optional(v.boolean()),
footer: v.optional(v.string()),
+ showSocialFooter: v.optional(v.boolean()),
aiChat: v.optional(v.boolean()),
+ contactForm: v.optional(v.boolean()),
+ newsletter: v.optional(v.boolean()),
}),
),
},
@@ -232,7 +241,10 @@ export const syncPagesPublic = mutation({
rightSidebar: page.rightSidebar,
showFooter: page.showFooter,
footer: page.footer,
+ showSocialFooter: page.showSocialFooter,
aiChat: page.aiChat,
+ contactForm: page.contactForm,
+ newsletter: page.newsletter,
lastSyncedAt: now,
});
updated++;
diff --git a/convex/posts.ts b/convex/posts.ts
index ef00afd..a7af0db 100644
--- a/convex/posts.ts
+++ b/convex/posts.ts
@@ -1,4 +1,4 @@
-import { query, mutation, internalMutation } from "./_generated/server";
+import { query, mutation, internalMutation, internalQuery } from "./_generated/server";
import { v } from "convex/values";
// Get all published posts, sorted by date descending
@@ -179,7 +179,10 @@ export const getPostBySlug = query({
rightSidebar: v.optional(v.boolean()),
showFooter: v.optional(v.boolean()),
footer: v.optional(v.string()),
+ showSocialFooter: v.optional(v.boolean()),
aiChat: v.optional(v.boolean()),
+ newsletter: v.optional(v.boolean()),
+ contactForm: v.optional(v.boolean()),
}),
v.null(),
),
@@ -215,11 +218,87 @@ export const getPostBySlug = query({
rightSidebar: post.rightSidebar,
showFooter: post.showFooter,
footer: post.footer,
+ showSocialFooter: post.showSocialFooter,
aiChat: post.aiChat,
+ newsletter: post.newsletter,
+ contactForm: post.contactForm,
};
},
});
+// Internal query to get post by slug (for newsletter sending)
+// Returns post details needed for newsletter content
+export const getPostBySlugInternal = internalQuery({
+ args: {
+ slug: v.string(),
+ },
+ returns: v.union(
+ v.object({
+ slug: v.string(),
+ title: v.string(),
+ description: v.string(),
+ content: v.string(),
+ excerpt: v.optional(v.string()),
+ }),
+ v.null(),
+ ),
+ handler: async (ctx, args) => {
+ const post = await ctx.db
+ .query("posts")
+ .withIndex("by_slug", (q) => q.eq("slug", args.slug))
+ .first();
+
+ if (!post || !post.published) {
+ return null;
+ }
+
+ return {
+ slug: post.slug,
+ title: post.title,
+ description: post.description,
+ content: post.content,
+ excerpt: post.excerpt,
+ };
+ },
+});
+
+// Internal query to get recent posts (for weekly digest)
+// Returns published posts with date >= since parameter
+export const getRecentPostsInternal = internalQuery({
+ args: {
+ since: v.string(), // Date string in YYYY-MM-DD format
+ },
+ returns: v.array(
+ v.object({
+ slug: v.string(),
+ title: v.string(),
+ description: v.string(),
+ date: v.string(),
+ excerpt: v.optional(v.string()),
+ })
+ ),
+ handler: async (ctx, args) => {
+ const posts = await ctx.db
+ .query("posts")
+ .withIndex("by_published", (q) => q.eq("published", true))
+ .collect();
+
+ // Filter posts by date and sort descending
+ const recentPosts = posts
+ .filter((post) => post.date >= args.since)
+ .sort((a, b) => b.date.localeCompare(a.date))
+ .map((post) => ({
+ slug: post.slug,
+ title: post.title,
+ description: post.description,
+ date: post.date,
+ excerpt: post.excerpt,
+ }));
+
+ return recentPosts;
+ },
+});
+
// Internal mutation for syncing posts from markdown files
export const syncPosts = internalMutation({
args: {
@@ -244,8 +323,11 @@ export const syncPosts = internalMutation({
rightSidebar: v.optional(v.boolean()),
showFooter: v.optional(v.boolean()),
footer: v.optional(v.string()),
+ showSocialFooter: v.optional(v.boolean()),
aiChat: v.optional(v.boolean()),
blogFeatured: v.optional(v.boolean()),
+ newsletter: v.optional(v.boolean()),
+ contactForm: v.optional(v.boolean()),
}),
),
},
@@ -291,8 +373,11 @@ export const syncPosts = internalMutation({
rightSidebar: post.rightSidebar,
showFooter: post.showFooter,
footer: post.footer,
+ showSocialFooter: post.showSocialFooter,
aiChat: post.aiChat,
blogFeatured: post.blogFeatured,
+ newsletter: post.newsletter,
+ contactForm: post.contactForm,
lastSyncedAt: now,
});
updated++;
@@ -342,8 +427,11 @@ export const syncPostsPublic = mutation({
rightSidebar: v.optional(v.boolean()),
showFooter: v.optional(v.boolean()),
footer: v.optional(v.string()),
+ showSocialFooter: v.optional(v.boolean()),
aiChat: v.optional(v.boolean()),
blogFeatured: v.optional(v.boolean()),
+ newsletter: v.optional(v.boolean()),
+ contactForm: v.optional(v.boolean()),
}),
),
},
@@ -389,8 +477,11 @@ export const syncPostsPublic = mutation({
rightSidebar: post.rightSidebar,
showFooter: post.showFooter,
footer: post.footer,
+ showSocialFooter: post.showSocialFooter,
aiChat: post.aiChat,
blogFeatured: post.blogFeatured,
+ newsletter: post.newsletter,
+ contactForm: post.contactForm,
lastSyncedAt: now,
});
updated++;
diff --git a/convex/rss.ts b/convex/rss.ts
index ea37904..44775d0 100644
--- a/convex/rss.ts
+++ b/convex/rss.ts
@@ -106,7 +106,7 @@ export const rssFeed = httpAction(async (ctx) => {
const posts = await ctx.runQuery(api.posts.getAllPosts);
const xml = generateRssXml(
- posts.map((post) => ({
+ posts.map((post: { title: string; description: string; slug: string; date: string }) => ({
title: post.title,
description: post.description,
slug: post.slug,
@@ -128,7 +128,7 @@ export const rssFullFeed = httpAction(async (ctx) => {
// Fetch full content for each post
const fullPosts = await Promise.all(
- posts.map(async (post) => {
+ posts.map(async (post: { title: string; description: string; slug: string; date: string; readTime?: string; tags: string[] }) => {
const fullPost = await ctx.runQuery(api.posts.getPostBySlug, {
slug: post.slug,
});
diff --git a/convex/schema.ts b/convex/schema.ts
index 9c8942e..ae41880 100644
--- a/convex/schema.ts
+++ b/convex/schema.ts
@@ -23,8 +23,11 @@ export default defineSchema({
rightSidebar: v.optional(v.boolean()), // Enable right sidebar with CopyPageDropdown
showFooter: v.optional(v.boolean()), // Show footer on this post (overrides siteConfig default)
footer: v.optional(v.string()), // Footer markdown content (overrides siteConfig defaultContent)
+ showSocialFooter: v.optional(v.boolean()), // Show social footer on this post (overrides siteConfig default)
aiChat: v.optional(v.boolean()), // Enable AI chat in right sidebar
blogFeatured: v.optional(v.boolean()), // Show as hero featured post on /blog page
+ newsletter: v.optional(v.boolean()), // Override newsletter signup display (true/false)
+ contactForm: v.optional(v.boolean()), // Enable contact form on this post
lastSyncedAt: v.number(),
})
.index("by_slug", ["slug"])
@@ -60,7 +63,10 @@ export default defineSchema({
rightSidebar: v.optional(v.boolean()), // Enable right sidebar with CopyPageDropdown
showFooter: v.optional(v.boolean()), // Show footer on this page (overrides siteConfig default)
footer: v.optional(v.string()), // Footer markdown content (overrides siteConfig defaultContent)
+ showSocialFooter: v.optional(v.boolean()), // Show social footer on this page (overrides siteConfig default)
aiChat: v.optional(v.boolean()), // Enable AI chat in right sidebar
+ contactForm: v.optional(v.boolean()), // Enable contact form on this page
+ newsletter: v.optional(v.boolean()), // Override newsletter signup display (true/false)
lastSyncedAt: v.number(),
})
.index("by_slug", ["slug"])
@@ -139,4 +145,40 @@ export default defineSchema({
})
.index("by_session_and_context", ["sessionId", "contextId"])
.index("by_session", ["sessionId"]),
+
+ // Newsletter subscribers table
+ // Stores email subscriptions with unsubscribe tokens
+ newsletterSubscribers: defineTable({
+ email: v.string(), // Subscriber email address (lowercase, trimmed)
+ subscribed: v.boolean(), // Current subscription status
+ subscribedAt: v.number(), // Timestamp when subscribed
+ unsubscribedAt: v.optional(v.number()), // Timestamp when unsubscribed (if applicable)
+ source: v.string(), // Where they signed up: "home", "blog-page", "post", or "post:slug-name"
+ unsubscribeToken: v.string(), // Secure token for unsubscribe links
+ })
+ .index("by_email", ["email"])
+ .index("by_subscribed", ["subscribed"]),
+
+ // Newsletter sent tracking (posts and custom emails)
+ // Tracks what has been sent to prevent duplicate newsletters
+ newsletterSentPosts: defineTable({
+ postSlug: v.string(), // Slug of the post or custom email identifier
+ sentAt: v.number(), // Timestamp when the newsletter was sent
+ sentCount: v.number(), // Number of subscribers it was sent to
+ type: v.optional(v.string()), // "post" or "custom" (default "post" for backwards compat)
+ subject: v.optional(v.string()), // Subject line for custom emails
+ })
+ .index("by_postSlug", ["postSlug"])
+ .index("by_sentAt", ["sentAt"]),
+
+ // Contact form messages
+ // Stores messages submitted via contact forms on posts/pages
+ contactMessages: defineTable({
+ name: v.string(), // Sender's name
+ email: v.string(), // Sender's email address
+ message: v.string(), // Message content
+ source: v.string(), // Where submitted from: "page:slug" or "post:slug"
+ createdAt: v.number(), // Timestamp when submitted
+ emailSentAt: v.optional(v.number()), // Timestamp when email was sent (if applicable)
+ }).index("by_createdAt", ["createdAt"]),
});
diff --git a/files.md b/files.md
index 9d80c08..32dc4ab 100644
--- a/files.md
+++ b/files.md
@@ -33,7 +33,7 @@ A brief description of each file in the codebase.
| File | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `siteConfig.ts` | Centralized site configuration (name, logo, blog page, posts display with homepage post limit and read more link, GitHub contributions, nav order, inner page logo settings, hardcoded navigation items for React routes, GitHub repository config for AI service raw URLs, font family configuration, right sidebar configuration, footer configuration, homepage configuration, AI chat configuration) |
+| `siteConfig.ts` | Centralized site configuration (name, logo, blog page, posts display with homepage post limit and read more link, GitHub contributions, nav order, inner page logo settings, hardcoded navigation items for React routes, GitHub repository config for AI service raw URLs, font family configuration, right sidebar configuration, footer configuration, social footer configuration, homepage configuration, AI chat configuration, newsletter configuration, contact form configuration) |
### Pages (`src/pages/`)
@@ -45,6 +45,7 @@ A brief description of each file in the codebase.
| `Stats.tsx` | Real-time analytics dashboard with visitor stats and GitHub stars |
| `TagPage.tsx` | Tag archive page displaying posts filtered by a specific tag. Includes view mode toggle (list/cards) with localStorage persistence |
| `Write.tsx` | Three-column markdown writing page with Cursor docs-style UI, frontmatter reference with copy buttons, theme toggle, font switcher (serif/sans/monospace), localStorage persistence, and optional AI Agent mode (toggleable via siteConfig.aiChat.enabledOnWritePage). When enabled, Agent replaces the textarea with AIChatView component. Includes scroll prevention when switching to Agent mode to prevent page jump. Title changes to "Agent" when in AI chat mode. |
+| `NewsletterAdmin.tsx` | Three-column newsletter admin page for managing subscribers and sending newsletters. Left sidebar with navigation and stats, main area with searchable subscriber list, right sidebar with send newsletter panel and recent sends. Access at /newsletter-admin, configurable via siteConfig.newsletterAdmin. |
### Components (`src/components/`)
@@ -67,6 +68,9 @@ A brief description of each file in the codebase.
| `PageSidebar.tsx` | Collapsible table of contents sidebar for pages/posts with sidebar layout, extracts headings (H1-H6), active heading highlighting, smooth scroll navigation, localStorage persistence for expanded/collapsed state |
| `RightSidebar.tsx` | Right sidebar component that displays CopyPageDropdown or AI chat on posts/pages at 1135px+ viewport width, controlled by siteConfig.rightSidebar.enabled and frontmatter rightSidebar/aiChat fields |
| `AIChatView.tsx` | AI chat interface component (Agent) using Anthropic Claude API. Supports per-page chat history, page content context, markdown rendering, and copy functionality. Used in Write page (replaces textarea when enabled) and optionally in RightSidebar. Requires ANTHROPIC_API_KEY environment variable in Convex. System prompt configurable via CLAUDE_PROMPT_STYLE, CLAUDE_PROMPT_COMMUNITY, CLAUDE_PROMPT_RULES, or CLAUDE_SYSTEM_PROMPT environment variables. Includes error handling for missing API keys. |
+| `NewsletterSignup.tsx` | Newsletter signup form component for email-only subscriptions. Displays configurable title/description, validates email, and submits to Convex. Shows on home, blog page, and posts based on siteConfig.newsletter settings. Supports frontmatter override via newsletter: true/false. |
+| `ContactForm.tsx` | Contact form component with name, email, and message fields. Displays when contactForm: true in frontmatter. Submits to Convex which sends email via AgentMail to configured recipient. |
+| `SocialFooter.tsx` | Social footer component with social icons on left (GitHub, Twitter/X, LinkedIn, etc.) and copyright on right. Configurable via siteConfig.socialFooter. Shows below main footer on homepage, blog posts, and pages. Supports frontmatter override via showSocialFooter: true/false. |
### Context (`src/context/`)
@@ -98,16 +102,19 @@ A brief description of each file in the codebase.
| File | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
-| `schema.ts` | Database schema (posts, pages, viewCounts, pageViews, activeSessions, aiChats) with indexes for tag and AI queries |
+| `schema.ts` | Database schema (posts, pages, viewCounts, pageViews, activeSessions, aiChats, newsletterSubscribers, newsletterSentPosts, contactMessages) with indexes for tag and AI queries. Posts and pages include showSocialFooter field for frontmatter control. |
| `posts.ts` | Queries and mutations for blog posts, view counts, getAllTags, getPostsByTag, and getRelatedPosts |
| `pages.ts` | Queries and mutations for static pages |
| `search.ts` | Full text search queries across posts and pages |
| `stats.ts` | Real-time stats with aggregate component for O(log n) counts, page view recording, session heartbeat |
-| `crons.ts` | Cron job for stale session cleanup |
+| `crons.ts` | Cron jobs for stale session cleanup, weekly newsletter digest (Sundays 9am UTC), and weekly stats summary (Mondays 9am UTC) |
| `http.ts` | HTTP endpoints: sitemap, API (update SITE_URL/SITE_NAME when forking, uses www.markdown.fast) |
| `rss.ts` | RSS feed generation (update SITE_URL/SITE_TITLE when forking, uses www.markdown.fast) |
| `aiChats.ts` | Queries and mutations for AI chat history (per-session, per-context storage). Handles anonymous session IDs, per-page chat contexts, and message history management. Supports page content as context for AI responses. |
| `aiChatActions.ts` | Anthropic Claude API integration action for AI chat responses. Requires ANTHROPIC_API_KEY environment variable in Convex. Uses claude-sonnet-3-5-20240620 model. System prompt configurable via environment variables (CLAUDE_PROMPT_STYLE, CLAUDE_PROMPT_COMMUNITY, CLAUDE_PROMPT_RULES, or CLAUDE_SYSTEM_PROMPT). Includes error handling for missing API keys with user-friendly error messages. Supports page content context and chat history (last 20 messages). |
+| `newsletter.ts` | Newsletter mutations and queries: subscribe, unsubscribe, getSubscriberCount, getActiveSubscribers, getAllSubscribers (admin), deleteSubscriber (admin), getNewsletterStats, getPostsForNewsletter, wasPostSent, recordPostSent. |
+| `newsletterActions.ts` | Newsletter actions (Node.js runtime): sendPostNewsletter, sendWeeklyDigest, notifyNewSubscriber, sendWeeklyStatsSummary. Uses AgentMail SDK for email delivery. |
+| `contact.ts` | Contact form mutations and actions: submitContact, sendContactEmail (AgentMail API), markEmailSent. |
| `convex.config.ts` | Convex app configuration with aggregate component registrations (pageViewsByPath, totalPageViews, uniqueVisitors) |
| `tsconfig.json` | Convex TypeScript configuration |
@@ -151,7 +158,11 @@ Markdown files with frontmatter for blog posts. Each file becomes a blog post.
| `rightSidebar` | Enable right sidebar with CopyPageDropdown (optional) |
| `showFooter` | Show footer on this post (optional, overrides siteConfig default) |
| `footer` | Footer markdown content (optional, overrides siteConfig.defaultContent) |
-| `aiChat` | Enable AI Agent chat in right sidebar (optional, requires rightSidebar: true and siteConfig.aiChat.enabledOnContent: true) |
+| `showSocialFooter` | Show social footer on this post (optional, overrides siteConfig default) |
+| `aiChat` | Enable AI Agent chat in right sidebar (optional). Set `true` to enable (requires `rightSidebar: true` and `siteConfig.aiChat.enabledOnContent: true`). Set `false` to explicitly hide even if global config is enabled. |
+| `blogFeatured` | Show as featured on blog page (optional, first becomes hero, rest in 2-column row) |
+| `newsletter` | Override newsletter signup display (optional, true/false) |
+| `contactForm` | Enable contact form on this post (optional) |
## Static Pages (`content/pages/`)
@@ -174,7 +185,10 @@ Markdown files for static pages like About, Projects, Contact, Changelog.
| `rightSidebar` | Enable right sidebar with CopyPageDropdown (optional) |
| `showFooter` | Show footer on this page (optional, overrides siteConfig default) |
| `footer` | Footer markdown content (optional, overrides siteConfig.defaultContent) |
-| `aiChat` | Enable AI Agent chat in right sidebar (optional, requires rightSidebar: true and siteConfig.aiChat.enabledOnContent: true) |
+| `showSocialFooter` | Show social footer on this page (optional, overrides siteConfig default) |
+| `aiChat` | Enable AI Agent chat in right sidebar (optional). Set `true` to enable (requires `rightSidebar: true` and `siteConfig.aiChat.enabledOnContent: true`). Set `false` to explicitly hide even if global config is enabled. |
+| `newsletter` | Override newsletter signup display (optional, true/false) |
+| `contactForm` | Enable contact form on this page (optional) |
## Scripts (`scripts/`)
@@ -184,6 +198,8 @@ Markdown files for static pages like About, Projects, Contact, Changelog.
| `sync-discovery-files.ts` | Updates AGENTS.md and llms.txt with current app data |
| `import-url.ts` | Imports external URLs as markdown posts (Firecrawl) |
| `configure-fork.ts` | Automated fork configuration (reads fork-config.json) |
+| `send-newsletter.ts` | CLI tool for sending newsletter posts (npm run newsletter:send +
+ You received this email because you subscribed to ${escapeHtml(siteName)}.
+ Unsubscribe
+
+ {match && {match[1]}}
+
+ {codeString}
+
+
+ );
+ },
+ img({ src, alt }) {
+ return (
+
+ {children}+ ); + }, + h1({ children }) { + const id = generateSlug(getTextContent(children)); + return ( +
+
+ );
+ },
+ h2({ children }) {
+ const id = generateSlug(getTextContent(children));
+ return (
+
+
+ );
+ },
+ h3({ children }) {
+ const id = generateSlug(getTextContent(children));
+ return (
+
+
+ );
+ },
+ h4({ children }) {
+ const id = generateSlug(getTextContent(children));
+ return (
+
+
+ );
+ },
+ h5({ children }) {
+ const id = generateSlug(getTextContent(children));
+ return (
+
+
+ );
+ },
+ h6({ children }) {
+ const id = generateSlug(getTextContent(children));
+ return (
+
+
+ );
+ },
+ ul({ children }) {
+ return - {children}
- {children}
; + }, + // Table components for GitHub-style tables + table({ children }) { + return ( +
+ {children}
+
+ );
+ },
+ thead({ children }) {
+ return {children};
+ },
+ tbody({ children }) {
+ return {children};
+ },
+ tr({ children }) {
+ return
+
{displayTitle}
+ {displayDescription && ( +{displayDescription}
+ )} + + {status === "success" ? ( +
+
+ ) : (
+ {statusMessage}
+ +