create-next-mdx-blog-app 2.2.1 → 2.2.3

package/README.md

@@ -1,416 +1,427 @@
-# 🌟 Next-MDX-Blog-Starter
-## 📖 Introduction
-This project is inspired by the elegant design and functionality of **Lovable**. It leverages the **Claude Sonnet 4.6** model for development, ensuring a robust and efficient coding experience.
-
-The goal of this repository is to serve as a comprehensive starter kit for working with static and dynamic content using MDX, React, and Next.js (more specifically the App Router).
-
-### 🚀 SSG-Compliant Architecture
-This starter kit is built with **Static Site Generation (SSG)** compliance at its core, ensuring optimal performance and SEO benefits:
-
-- **Pre-rendered Pages**: All blog posts and content pages are statically generated at build time for lightning-fast loading
-- **Optimized Assets**: Images, fonts, and other assets are optimized for static delivery
-- **SEO-Ready**: Meta tags, structured data, and semantic HTML are generated statically for better search engine visibility
-- **CDN-Friendly**: Static output can be easily deployed to any CDN or static hosting provider
-- **Zero Runtime Dependencies**: Core content rendering requires no client-side JavaScript, ensuring accessibility and performance
-
-## ⚙️ Project Setup
-
-### Prerequisites
-- **Node.js**: Ensure you have Node.js installed (version 18.17.0 or later).
-- **NPM**: Node Package Manager comes with Node.js.
-
-### Installation
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/CodingAbdullah/Next-MDX-Blog-Starter.git
-   cd mdx-medium-blog-post-provider
-   ```
-
-2. Install dependencies:
-   ```bash
-   npm install
-   ```
-
-3. Configure environment variables:
-   ```bash
-   cp .env.example .env.local
-   # Fill in SUPABASE_URL, SUPABASE_ANON_KEY, ANTHROPIC_API_KEY, and others in .env.local
-   ```
-
-4. Start the development server:
-   ```bash
-   npm run dev
-   ```
-
-If you want, you can also run this project using the following command:
-   ```bash
-   npx create-next-mdx-blog-app .
-   ```
-This will clone the repository, install dependencies, and guide you through environment setup automatically.
-
-## ![NPM](https://img.shields.io/badge/NPM-CB3837?style=for-the-badge&logo=npm&logoColor=white) Package
-
-### Quick Start
-
-**`npx create-next-mdx-blog-app .`**
-
-```bash
-npx create-next-mdx-blog-app .
-```
-
-### Package Information
-
-- **Package Name**: `create-next-mdx-blog-app`
-- **Version**: `2.2.1`
-- **License**: MIT
-- **Homepage**: [https://www.npmjs.com/package/create-next-mdx-blog-app](https://www.npmjs.com/package/create-next-mdx-blog-app/)
-
-## 🛠️ Tools
-### AI Tools
-- **Cursor**: An AI-powered coding assistant that enhances productivity and code quality.
-- **Lovable**: A design inspiration that emphasizes user-friendly interfaces and experiences.
-- **Claude Sonnet 4.6**: A model that aids in development, providing intelligent suggestions and optimizations.
-
-### Common NPM Libraries
-- **mdx**: A markdown format that allows you to write JSX in your markdown files, enabling rich content.
-- **Supabase**: An open-source Firebase alternative that provides a backend as a service, including database and authentication.
-- **shadcn/ui**: A collection of UI components designed for building modern web applications.
-- **lucide-react**: A set of customizable icons for React applications, enhancing visual appeal.
-- **gray-matter**: A library for parsing front matter from markdown files, useful for managing metadata.
-- **react**: A JavaScript library for building user interfaces, allowing for the creation of reusable UI components.
-- **react-syntax-highlighter**: A library for syntax highlighting in React applications, making code snippets more readable.
-- **tsx**: Run TypeScript code without worrying about configuration! Run the `article-manager.ts` for manually working with published articles.
-- **@codesandbox/sandpack-react**: Powers the in-browser JavaScript/TypeScript code execution environment, running code entirely client-side with no server required.
-- **ai** (Vercel AI SDK): Provides streaming AI response primitives and transport utilities (`TextStreamChatTransport`, `streamText`, tool support) used by both the interactive chatbot and the AI article summarizer.
-- **@ai-sdk/anthropic**: Anthropic provider for the Vercel AI SDK, used to connect to Claude models.
-- **@ai-sdk/react**: React hooks (`useChat`) for building streaming AI chat interfaces.
-- **zod**: TypeScript-first schema validation library used to define and validate AI tool parameters.
-- **sonner**: Lightweight toast notification library used for user feedback across the Code Sandbox, the `CodeBlock` copy button, and the GitHub Gist copy button.
-
-## 🌐 Static/Dynamic Rendering with MDX
-This project utilizes MDX for both static and dynamic rendering of blog posts. The two MDX files included in the project serve as examples of how to structure your content.
-
-- **Static MDX**: Pre-rendered at build time (<b>route</b>: `/app/sample-blog-post-page`, <b>article content</b>: `/markdown/ArticleContent.mdx`).
-- **Dynamic MDX**: Rendered on the server at request time (<b>route</b>: `/app/dynamic`, <b>article content</b>: `/markdown/DynamicArticleContent.mdx`).
-
-### Article Metadata
-`.mdx` files can contain useful information that can be thought of as metadata for the file itself. This is called frontmatter and it is stored at the top of the file using this `---` opening and closing syntax.
-
-A helpful package known as `gray-matter` is used to format and separate frontmatter from the article content which is useful when fetching and rendering dynamic MDX content.
-
-Dynamic MDX content is rendered with the help of the `next-mdx-remote` package and utilizing the `MDXRemote` custom component.
-
-## 🖼️ MDX Components File
-The `mdx-components.tsx` file located in the root, integrates styling for built-in HTML elements as well as optimizing built-in elements such as `<a>` and `<img>` using the built-in components provided by Next.js (`<Image>` and `<Link>`).
-
-For more details on what this file is and how it is utilized in a Next.js application, you can refer to the official docs <a href="https://nextjs.org/docs/app/api-reference/file-conventions/mdx-components">here</a>.
-
-## 🧩 Custom React Components
-Custom React components are created for enhanced functionality when working with MDX. The following are located in the `customMDXComponents` directory inside the `components` directory of the project.
-
-### Syntax Highlighting
-The project includes a custom `CodeBlock` component for syntax highlighting code blocks using the `react-syntax-highlighter` package.
-
-Default theme is set to the `vscDarkPlus` theme. Feel free to modify the theme and even add your own syntax highlighting library if you so choose.
-
-A **copy button** is rendered in the top-right corner of every code block. Clicking it writes the code to the clipboard and triggers a sonner toast notification confirming success or failure.
-
-You can read more about the library used in this project <a href="https://react-syntax-highlighter.github.io/react-syntax-highlighter/demo/">here.</a>
-
-### GitHub Gists
-GitHub Gists can be embedded directly in MDX files using the `<GitHubGist>` custom component. The component fetches gist content live from the **GitHub REST API** at render time and caches the result for one hour via Next.js ISR (`next: { revalidate: 3600 }`).
-
-```mdx
-<GitHubGist id="your-gist-id" figCaptionText="Caption shown below the gist" />
-```
-
-#### How it works
-1. `GitHubGist` calls `https://api.github.com/gists/<id>` to retrieve metadata (file name, detected language).
-2. It then fetches the raw file content from the `raw_url` returned by the API.
-3. The language is mapped to a Prism-compatible token using the built-in `GITHUB_GIST_LANGUAGE_MAP` constant (70+ languages supported — see `src/utils/constants/GitHubGistConstants.ts`).
-4. The code is rendered via `GistCodeBlock` (syntax-highlighted with `react-syntax-highlighter`) inside a scrollable container with a custom green scrollbar (`scrollbar-gist`).
-
-#### mdxgists.net
-Each rendered gist includes a header bar with:
-- The detected **language badge**
-- A **Copy** button that writes the raw content to clipboard with a sonner toast confirmation
-- A **mdxgists.net** link that opens the gist on [mdxgists.net](https://mdxgists.net) — a companion site for browsing and sharing MDX-ready gists
-
-The mdxgists.net URL is constructed as `<GIST_BASE_URL>/<GITHUB_USERNAME>/<gist-id>` using values from `GitHubGistConstants.ts`. Both values can be overridden via environment variables (see below).
-
-#### Components
-- `src/components/customMDXComponents/GitHubGist.tsx` — async Server Component; fetches from GitHub API, resolves language, builds the mdxgists.net URL, renders the full gist UI
-- `src/components/customMDXComponents/GistCodeBlock.tsx` — syntax-highlighted code display using `react-syntax-highlighter`
-- `src/components/customMDXComponents/GistCopyButton.tsx` — `"use client"` component; copy-to-clipboard with sonner toast + mdxgists.net external link
-
-#### Language Detection
-The `GITHUB_GIST_LANGUAGE_MAP` in `src/utils/constants/GitHubGistConstants.ts` maps GitHub's reported language names to Prism-compatible identifiers. Over 70 languages are supported out of the box including TypeScript, Python, Rust, Go, Solidity, YAML, SQL, and more. If a language is not in the map, the component falls back to `language.toLowerCase()`. If no language is detected, it falls back to `text`.
-
-#### GitHub OAuth Token (optional but recommended)
-Unauthenticated requests to the GitHub API are rate-limited to **60 requests per hour** per IP. For production use, set a `GITHUB_TOKEN` environment variable to increase this to **5,000 requests per hour**:
-
-```bash
-# .env.local
-GITHUB_TOKEN=ghp_your_personal_access_token
-```
-
-To generate a token: GitHub → Settings → Developer settings → Personal access tokens → Generate new token. The token only needs the **read-only** `gist` scope (or no scopes at all for public gists).
-
-> Only **public** gists are supported by default. The component can be modified to support private gists by adding the appropriate scopes to the token.
-
-### MDX Images
-The project comes with its own `MDXImage` component that utilizes the Next.js built-in `Image` component as well as the built-in `figure` and `figcaption` elements to integrate imaging and captions seamlessly.
-
-Images are displayed inside a styled container with a **green glow border** and a **hover scale effect** consistent with the rest of the matrix-green design system.
-
-### Article Header Actions
-A **Copy Link** button (`src/components/CopyLinkButton.tsx`) is rendered in the article header, writing the current page URL to the clipboard on click and displaying a brief "Copied!" confirmation via icon swap. **Social Share** buttons (`src/components/SocialShareButtons.tsx`) sit alongside it, opening pre-filled share dialogs for X (Twitter), LinkedIn, and Reddit in a new tab using the article title and URL.
-
-### Reading Progress Bar
-A thin green bar (`src/components/ReadingProgressBar.tsx`) is fixed to the top of the viewport on all article pages, growing from left to right as the reader scrolls through the article. It uses a passive scroll listener for zero performance impact and includes `role="progressbar"` ARIA attributes for accessibility.
-
-### Back to Top Button
-A floating circular button (`src/components/BackToTopButton.tsx`) appears in the bottom-right corner of the screen once the reader has scrolled more than 400px down the page. Clicking it smoothly scrolls back to the top. The button is hidden when not needed and matches the green colour scheme of the rest of the UI.
-
-### Light / Dark Mode Toggle
-A theme toggle button (`src/components/ThemeToggle.tsx`) is rendered in the site header, allowing readers to switch between **dark** (default) and **light** modes. Theme state is managed by `next-themes` via the `ThemeProvider` wrapper (`src/components/ThemeProvider.tsx`) mounted in the root layout. The active theme is persisted to `localStorage` automatically. Toast notifications use `ThemedToaster` (`src/components/ThemedToaster.tsx`), a thin wrapper around `sonner` that picks the correct Sonner theme to match the active colour scheme.
-
-### View Counter
-Each article page displays a live view count stored in a dedicated `view_counts` Supabase table, incremented atomically via the `increment_view_count` RPC function. Dynamic pages increment server-side at render time; static pages use a `ViewCounter` client component that calls the `/api/views/[slug]` Route Handler after hydration.
-
-## 🖥️ Code Sandbox
-The project includes an interactive in-browser code execution environment powered by **Sandpack** (<b>route</b>: `/code-sandbox`).
-
-### Features
-- **JavaScript & TypeScript runtimes**: Switch between JS and TS with a single click. The editor reloads with a language-appropriate default snippet.
-- **Quick Examples**: Pre-loaded snippets covering Fibonacci, Async/Await, Data Structures (JS) and Types & Interfaces, Generics, Classes & OOP (TS) — load any with one click.
-- **Sandpack Editor**: Full code editor with line numbers, inline TypeScript errors, and a matrix-green custom theme (`JetBrains Mono`).
-- **Toolbar**: Run, Copy to clipboard, Download file, and Reset to default — all accessible from above the editor.
-- **Console Panel**: Live console output displayed side-by-side with the editor. Execution is entirely in-browser — no code reaches the server.
-- **Features Section**: Highlights Secure Sandbox, Instant Execution, Easy Copy, and JS & TypeScript support.
-
-### Components
-- `src/components/SandpackEditor.tsx` — Sandpack provider, matrix-themed editor, toolbar, and console panel.
-- `src/components/CodeSandboxFeaturesSection.tsx` — Feature highlights grid displayed below the editor.
-
-## 🤖 Blog Assistant Chatbot
-The project includes an interactive AI-powered chatbot optimised for readers of this technical blog (<b>route</b>: `/chat`).
-
-### Features
-- **Streaming responses**: Powered by the Vercel AI SDK (`TextStreamChatTransport`) and Anthropic's Claude Haiku model via an edge API route (`/api/chat`).
-- **Blog-focused tools**: Three tools are available to the model during a conversation:
-  - `searchBlogTopics` — searches a curated list of topics covered by this blog (JS, TS, React, Next.js, MDX, Docker, AWS, etc.)
-  - `getCodeExample` — signals the model to generate a runnable code example for a given concept and language.
-  - `explainConcept` — signals the model to produce a brief or detailed technical explanation.
-- **No persistence**: Conversations are ephemeral — nothing is stored on a server or in a database. A "New Chat" button clears the session.
-- **Matrix-green styling**: Consistent with the Code Sandbox, the chat UI uses the same dark/neon-green palette and `JetBrains Mono` font.
-- **Tool result display**: Each tool call and its result is rendered inline in the message thread via the `ChatToolResult` component.
-
-### Configuration
-- `src/utils/constants/AiChatConfig.ts` — Model name (`claude-haiku-4-5-20251001`), temperature, max tokens, and the blog-focused system prompt.
-- `src/utils/constants/ToolConfig.ts` — Icon, label, and colour mappings for each tool displayed in the UI.
-
-### Components
-- `src/components/chat/chat-interface.tsx` — Top-level client component; owns `useChat` state, "New Chat" handler, and layout.
-- `src/components/chat/chat-messages.tsx` — Message thread with auto-scroll, empty state, loading indicator, and error display.
-- `src/components/chat/chat-input.tsx` — Textarea + send button; supports `Enter` to send and `Shift+Enter` for newlines.
-- `src/components/chat/chat-tool-result.tsx` — Renders tool call and tool result states inline in the message thread.
-
-### API Route
-`src/app/api/chat/route.ts` — Next.js edge route. Accepts the `UIMessages` array, converts it to `CoreMessages` via `convertToModelMessages`, streams a response using `streamText` with the three blog tools, and returns `result.toTextStreamResponse()`.
-
-## ✨ AI Article Summarizer
-A **Generate TL;DR** button above every dynamic article streams a short Claude Haiku summary into a collapsible green panel. The slug is the only thing sent over the wire — `src/app/api/summarize/[slug]/route.ts` (edge) fetches the article server-side, applies an origin allow-list (`NEXT_PUBLIC_SITE_URL`) + per-IP rate limit (10/min) + 1-hour in-memory cache, then calls `streamText` and writes the final text to cache via `after()`. The client (`src/components/ArticleSummarizer.tsx`) uses `AbortController` to cancel in-flight requests on close/unmount. Model and prompt live in `src/utils/constants/AiSummaryConfig.ts`.
-
-## 👥 Author Profile Pages
-A `/authors` index lists every distinct contributor pulled from the Supabase `Article` table, with per-author profile routes at `/authors/[slug]` showing their bio, avatar, and every article they've published.
-
-## 📬 Newsletter Subscription
-The project ships with an integrated **newsletter signup form** powered by [Resend](https://resend.com). Visitors can subscribe from the home page or from the bottom of any article; new subscribers are added to a Resend **Audience** and immediately receive a welcome email.
-
-### Components & Routes
-- `src/components/NewsletterSignup.tsx` — reusable client component with `matrix` (article pages, glass-card + green) and `neutral` (home page, white/black/silver shadcn) visual variants.
-- `src/app/api/newsletter/subscribe/route.ts` — Node-runtime POST handler; validates the email with Zod and forwards it to the Resend SDK.
-- `src/utils/functions/newsletter/subscribeToNewsletter.ts` — server-side helper that adds the contact to your Resend Audience and triggers the welcome email.
-- `src/utils/functions/newsletter/welcomeEmailTemplate.ts` — builds the subject + HTML/text bodies for the confirmation email.
-- `src/utils/functions/resend_client/ResendClient.ts` — server-only Resend client factory.
-
-### Setup Steps
-1. Create a Resend account at [resend.com](https://resend.com).
-2. **API Key** — go to **API Keys → Create API Key** and grant it access to **Sending** and **Audiences**. Copy the key into `RESEND_API_KEY` in `.env.local`.
-3. **Audience** — go to **Audiences → Create Audience**, give it a name, and copy the generated UUID into `RESEND_AUDIENCE_ID` in `.env.local`.
-4. Restart `npm run dev` after editing `.env.local` so Next.js picks up the new variables.
-
-### Environment Variables
-| Variable | Required for |
-|---|---|
-| `RESEND_API_KEY` | Authenticating with the Resend API |
-| `RESEND_AUDIENCE_ID` | The Resend Audience that new subscribers are added to |
-
-### ⚠️ ***Important: A verified sending domain on Resend is required for the email-sending feature to fully work.***
-Out of the box the welcome email is sent from **`onboarding@resend.dev`**, which is Resend's sandbox sender. **`onboarding@resend.dev` is only allowed to deliver to the email address that owns your Resend account** — sending to any other recipient will be rejected by Resend.
-
-> 🚨 ***You MUST set up and verify your own sending domain on Resend (Resend dashboard → Domains → Add Domain, then complete the SPF / DKIM DNS records) before the newsletter can deliver welcome emails to real subscribers.*** Once your domain is verified, update the `WELCOME_EMAIL_FROM` constant in `src/utils/functions/newsletter/subscribeToNewsletter.ts` to an address on that domain (for example `newsletter@yourdomain.com`).
-
-If the domain step is skipped, the contact will still be added to your Resend Audience, but the welcome email will silently fail (the failure is logged to the server console as `[newsletter] Resend emails.send returned an error: ...`).
-
-## 🧩 Constants, Functions, & Types
-In this project, you will find custom constants, functions, and types in the `/src/utils/` directory. Certain constants serve as placeholders in this demo application.
-
-While functions and data types are integral to the function of this web application, feel free to check them out.
-
-## 🗄️ Supabase Database Setup
-The project uses Supabase for database management. The `SupabaseClient` module is configured to interact with your Supabase instance. The instance is located in `/src/utils/functions/supabase_client`.
-
-**Ensure that the policies of the Supabase database enable you to perform the desired CRUD actions against your tables. You can modify these in the Supabase console.**
-
-### Environment Variables & Credentials
-A `.env.example` file is provided at the root of the project listing all required environment variable keys with empty placeholders. Copy it to `.env.local` and fill in your values:
-
-```bash
-cp .env.example .env.local
-```
-
-| Variable | Required for |
-|---|---|
-| `SUPABASE_URL` | Dynamic blog post fetching (Supabase client) |
-| `SUPABASE_ANON_KEY` | Dynamic blog post fetching (Supabase client) |
-| `ANTHROPIC_API_KEY` | Blog Assistant chatbot (`/api/chat` edge route) |
-| `GITHUB_TOKEN` | GitHub API authentication for `<GitHubGist>` — optional but raises rate limit from 60 to 5,000 req/hr |
-| `GITHUB_USERNAME` | Your GitHub username, used to construct the mdxgists.net URL (defaults to `CodingAbdullah`) |
-| `GIST_BASE_URL` | Base URL for mdxgists.net links (defaults to `https://mdxgists.net`) |
-| `RESEND_API_KEY` | Newsletter signup — authenticates with the Resend API (see the **Newsletter Subscription** section below) |
-| `RESEND_AUDIENCE_ID` | Newsletter signup — the Resend Audience that new subscribers are added to |
-
-```
-# .env.local
-SUPABASE_URL=
-SUPABASE_ANON_KEY=
-ANTHROPIC_API_KEY=
-GITHUB_TOKEN=
-GITHUB_USERNAME=
-GIST_BASE_URL=
-RESEND_API_KEY=
-RESEND_AUDIENCE_ID=
-```
-
-## 🌩️ AWS
-This application utilizes the AWS S3 service for the storage of images. You can find the external URL used to access these objects in the `next.config.ts` file. Feel free to use another service or modify the URL to point to a S3 bucket of your own.
-
-Images are used in the `.mdx` files and utilized via the custom `MDXImage` component covered earlier.
-
-## 🐳 Docker
-This application can be containerized using Docker.
-
-To build an image, utilize the Dockerfile located in the root location of the repository and run the following commands to run this web application in a standalone container (passing in the credentials as well):
-
-``
-docker build -t mdx-medium-blog .
-``
-
-``
-docker run -e SUPABASE_URL=your_supabase_url \ -e SUPABASE_ANON_KEY=your_supabase_anon_key \ -e ANTHROPIC_API_KEY=your_anthropic_api_key \ -e GITHUB_TOKEN=your_github_token \ -e GITHUB_USERNAME=your_github_username \ -e GIST_BASE_URL=https://mdxgists.net \ -e RESEND_API_KEY=your_resend_api_key \ -e RESEND_AUDIENCE_ID=your_resend_audience_id \ -p 3000:3000 mdx-medium-blog
-``
-
-## 🔄 CRUD Operations and Supabase Actions
-Implementation of the CRUD operation functions is stored in the `/src/utils/functions/crud` directory. This includes functions for creating, reading, updating, and deleting articles in the Supabase database. Supabase RPC functions (such as `incrementViewCount`) are kept separately in `/src/utils/functions/rpc`.
-
-The `article-manager.ts` file utilizes these CRUD functions to successfully perform the desired actions.
-
-## 📜 Scripts for Setting Up Project
-The `/scripts` folder contains various scripts to help set up the project and database.
-
-### Setup Scripts
-- **SQL Scripts**: DDL and DML statements for initializing and populating the database.
-- **Powershell Script**: Script for setting up project on Windows.
-- **Bash Shell Script**: Script for setting up project on Linux, Mac, etc.
-
-### GitHub Gist Fetcher
-> **Note:** This script is no longer required for rendering gists in MDX. The `<GitHubGist>` component now fetches content live from the GitHub API at render time. This script is retained for offline inspection or local caching workflows.
-
-**Location**: `/scripts/github-gist-fetcher/fetch-github-gist.ts`
-
-**Usage**:
-```bash
-npx tsx scripts/github-gist-fetcher/fetch-github-gist.ts <gist-id>
-```
-
-**Features**:
-- Fetches public GitHub Gist content using the GitHub API
-- Exports the raw content from the fetch call to `/src/github_gists/<gist-id>.txt`
-- Automatically creates the output directory if it does not exist
-- Provides clear error handling and status messages
-
-This project directly integrates Supabase in the front-end using React Server components which removes the need for custom back-end APIs.
-
-## 🛠️ Compiling TypeScript and Testing Locally
-The `article-manager.ts` file (located in `/scripts/action-script`) utilizes the `tsx` package to perform the different actions (CRUD operations) on articles stored locally.
-
-You can use this handy script for testing MDX and article functionality locally.
-
-The following codeblock highlights the different command prompts that can be used with this file:
-
-    - Insert an Article into Supabase
-    npx tsx article-manager.ts insert article-slug
-
-    - Delete an Article from Supabase
-    npx tsx article-manager.ts delete article-slug
-
-    - Update an Article in Supabase
-    npx tsx article-manager.ts update article-slug new-article-file
-
-    - Fetch a Single Article from Supabase
-    npx tsx article-manager.ts fetch article-slug
-
-    - Fetch all Articles from Supabase
-    npx tsx article-manager.ts fetchAll
-
-The article slug is the name of the markdown file located in the `/src/markdown` directory minus the extension, `.mdx`.
-
-The update statement takes in an additional parameter which is also the same thing (file name minus the `.mdx` extension located in the `/src/markdown` directory).
-
-## 📱 Mobile Responsiveness
-All components in the starter kit are built mobile-first using Tailwind CSS responsive prefixes (`sm:`, `md:`, `lg:`).
-
-Key responsive behaviours:
-
-| Component | Mobile behaviour |
-|---|---|
-| `ArticleHeader` | Title scales from `text-2xl` → `text-4xl`; author row stacks vertically on small screens |
-| `ArticleAuthorBio` | Avatar and text stack vertically; button goes full-width; text is center-aligned on mobile |
-| `GitHubGist` | Header wraps via `flex-wrap`; code area scrolls horizontally with a styled green scrollbar |
-| `CodeBlock` | Copy button is absolutely positioned and does not interfere with code flow |
-| `MDXImage` | Image container scales inline; hover effect applies on capable devices |
-| Chat & Code Sandbox | Responsive padding and height calculations across all breakpoints |
-
-The root layout exports a `viewport` configuration (via Next.js `Viewport` type) ensuring correct scaling on all mobile browsers:
-
-```ts
-export const viewport: Viewport = {
-  width: 'device-width',
-  initialScale: 1,
-};
-```
-
-## 📊 Analytics
-Integrated in this setup project is Vercel Analytics (`@vercel/analytics`) to track user interactions and performance metrics of the blog.
-
-## 🗺️ Sitemap & Robots
-A `sitemap.xml` is auto-generated at build time via `src/app/sitemap.ts`, covering all static routes and every dynamic article slug fetched from Supabase. A companion `robots.txt` is served from `src/app/robots.ts`, permitting all crawlers and pointing them to the generated sitemap for full search engine discoverability.
-
-## ⚙️ Next.js Configuration
-The `next.config.ts` file is set up for working with AWS S3 and includes MDX extensions for enhanced functionality. Feel free to modify and add your own custom links to access storage and setting up other configurations.
-
-## 🔗 Useful Links
-- [Next.js Documentation](https://nextjs.org/docs)
-- [MDX Documentation](https://mdxjs.com/docs/)
-- [Lee Robinson's Next.js + MDX Tutorial Video](https://www.youtube.com/watch?v=34bRv6cQezo&ab_channel=leerob)
-- [MDX Playground](https://mdxjs.com/playground/)
-- [React Documentation](https://reactjs.org/docs/getting-started.html)
-- [Supabase Documentation](https://supabase.com/docs)
-- [Docker Documentation](https://docs.docker.com/)
-- [React Syntax Highlighter Package](https://github.com/react-syntax-highlighter/react-syntax-highlighter)
-- [Sandpack Documentation](https://sandpack.codesandbox.io/docs)
-- [Vercel AI SDK Documentation](https://sdk.vercel.ai/docs)
-- [Anthropic AI SDK Provider](https://sdk.vercel.ai/providers/ai-sdk-providers/anthropic)
-- [Zod Documentation](https://zod.dev)
+# 🌟 Next-MDX-Blog-Starter
+
+A production-ready technical blog starter kit built with **Next.js (App Router)**, **MDX**, **Supabase**, and **TypeScript strict mode**. SSG-first for performance and SEO, with AI-powered reader features, an in-browser code sandbox, and a full content-management toolchain.
+
+**Live demo**: [next-mdx-blog-starter-sigma.vercel.app](https://next-mdx-blog-starter-sigma.vercel.app/)
+
+This project was developed with the help of **Claude** (Anthropic) and **Cursor**, with design inspiration from **Lovable**.
+
+## 📑 Table of Contents
+
+- [Quick Start](#%EF%B8%8F-quick-start)
+- [Environment Variables](#-environment-variables)
+- [Architecture & Core Stack](#%EF%B8%8F-architecture--core-stack)
+- [MDX Content System](#-mdx-content-system)
+- [Custom MDX Components](#-custom-mdx-components)
+- [Reader Experience Features](#-reader-experience-features)
+- [AI Features](#-ai-features)
+- [Code Sandbox](#%EF%B8%8F-code-sandbox)
+- [Author Profile Pages](#-author-profile-pages)
+- [Search](#-search)
+- [Newsletter Subscription](#-newsletter-subscription)
+- [Supabase Database](#%EF%B8%8F-supabase-database)
+- [Article Manager CLI](#%EF%B8%8F-article-manager-cli)
+- [Project Scripts](#-project-scripts)
+- [AWS S3 Image Storage](#%EF%B8%8F-aws-s3-image-storage)
+- [SEO: Sitemap & Robots](#%EF%B8%8F-seo-sitemap--robots)
+- [Mobile Responsiveness](#-mobile-responsiveness)
+- [Analytics](#-analytics)
+- [Docker](#-docker)
+- [Useful Links](#-useful-links)
+
+## ⚙️ Quick Start
+
+### Prerequisites
+- **Node.js** 18.17.0 or later (NPM included)
+
+### Option 1 — NPM installer (recommended)
+
+Scaffold the blog into an empty directory:
+
+```bash
+npx create-next-mdx-blog-app .
+```
+
+The installer ([`create-next-mdx-blog-app`](https://www.npmjs.com/package/create-next-mdx-blog-app/), v2.2.3, MIT) clones the app, installs dependencies, and prints the environment setup steps.
+
+### Option 2 — Manual clone
+
+```bash
+git clone https://github.com/CodingAbdullah/Next-MDX-Blog-Starter.git
+cd Next-MDX-Blog-Starter/mdx-medium-blog-post-provider
+npm install
+```
+
+### Configure and run
+
+```bash
+cp .env.example .env.local   # fill in your credentials (see table below)
+npm run dev
+```
+
+## 🔐 Environment Variables
+
+A `.env.example` file at the project root lists every key. Copy it to `.env.local` and fill in your values:
+
+```bash
+cp .env.example .env.local
+```
+
+```bash
+# .env.local
+
+# Supabase — dynamic blog post fetching
+SUPABASE_URL=
+SUPABASE_ANON_KEY=
+
+# Anthropic — Blog Assistant chatbot + AI Article Summarizer
+ANTHROPIC_API_KEY=
+
+# Site — public base URL (sitemap, robots.txt, summarizer origin allow-list)
+NEXT_PUBLIC_SITE_URL=
+
+# GitHub — optional, for the <GitHubGist> component
+GITHUB_TOKEN=
+GITHUB_USERNAME=
+GIST_BASE_URL=
+
+# Resend — newsletter signup
+RESEND_API_KEY=
+RESEND_AUDIENCE_ID=
+```
+
+### Required
+
+| Variable | Used by |
+|---|---|
+| `SUPABASE_URL` | Dynamic blog post fetching (Supabase client) |
+| `SUPABASE_ANON_KEY` | Dynamic blog post fetching (Supabase client) |
+| `ANTHROPIC_API_KEY` | Blog Assistant chatbot (`/api/chat`) and AI Article Summarizer (`/api/summarize/[slug]`) |
+| `RESEND_API_KEY` | Newsletter signup — authenticates with the Resend API |
+| `RESEND_AUDIENCE_ID` | Newsletter signup — the Resend Audience new subscribers are added to |
+
+### Optional (sensible defaults)
+
+| Variable | Used by | Default |
+|---|---|---|
+| `NEXT_PUBLIC_SITE_URL` | Sitemap, robots.txt, summarizer origin allow-list | `http://localhost:3000` |
+| `GITHUB_TOKEN` | `<GitHubGist>` GitHub API auth — raises rate limit from 60 to 5,000 req/hr | unauthenticated |
+| `GITHUB_USERNAME` | mdxgists.net URL construction | `CodingAbdullah` |
+| `GIST_BASE_URL` | mdxgists.net link base URL | `https://mdxgists.net` |
+
+> 🔒 **Never commit `.env` files.** They are git-ignored and excluded from Docker images via `.dockerignore`. Server-only secrets (Supabase keys, Anthropic and Resend API keys, GitHub token) are read exclusively in Server Components and Route Handlers — only `NEXT_PUBLIC_SITE_URL` is exposed to the browser.
+
+## 🏗️ Architecture & Core Stack
+
+This starter kit is **SSG-first**: Static Site Generation is preferred everywhere, with dynamic rendering used only where required.
+
+- **Pre-rendered pages**: Blog posts and content pages are statically generated at build time
+- **Server Components first**: Supabase is queried directly from React Server Components — no custom backend APIs
+- **SEO-ready**: Meta tags, structured data, and semantic HTML generated statically
+- **CDN-friendly**: Static output deploys to any CDN or static host
+- **Minimal client JS**: Core content rendering requires no client-side JavaScript
+
+| Layer | Technology |
+|---|---|
+| Framework | Next.js (App Router), React, TypeScript (strict mode) |
+| Content | MDX, `gray-matter`, `next-mdx-remote` |
+| Database | Supabase (`@supabase/supabase-js`) |
+| Image storage | AWS S3 (via Next `<Image>`) |
+| Styling / UI | Tailwind CSS, shadcn/ui, `lucide-react`, `class-variance-authority` |
+| AI | Vercel AI SDK (`ai`, `@ai-sdk/anthropic`, `@ai-sdk/react`), `zod` |
+| Code sandbox | `@codesandbox/sandpack-react` |
+| Syntax highlighting | `react-syntax-highlighter` |
+| Email | Resend (`resend`) |
+| Notifications | `sonner` toasts |
+| Theming | `next-themes` |
+| Tooling | Docker, Vercel Analytics, `tsx`, `react-doctor` (`npm run doctor`) |
+
+## 🌐 MDX Content System
+
+This project renders blog posts from `.mdx` files in two modes, each with an included example:
+
+- **Static MDX** — pre-rendered at build time. Route: `/sample-blog-post-page`, content: `src/markdown/ArticleContent.mdx`
+- **Dynamic MDX** — rendered on the server at request time via `next-mdx-remote`'s `MDXRemote` component. Route: `/dynamic/[dynamic_blog_post]`, content: `src/markdown/DynamicArticleContent.mdx`
+
+### Frontmatter (article metadata)
+
+Each `.mdx` file carries metadata at the top of the file between `---` delimiters, parsed with `gray-matter`:
+
+```yaml
+---
+title: string
+description: string
+publishedAt: string
+author: string
+tags: string[]
+image: string
+---
+```
+
+### The `mdx-components.tsx` file
+
+`mdx-components.tsx` at the project root styles built-in HTML elements and swaps `<img>` and `<a>` for the optimized Next.js `<Image>` and `<Link>` components. See the [Next.js docs](https://nextjs.org/docs/app/api-reference/file-conventions/mdx-components) for how this file convention works.
+
+## 🧩 Custom MDX Components
+
+Custom components for MDX content live in `src/components/customMDXComponents/`.
+
+### CodeBlock — syntax highlighting
+
+Highlights code blocks with `react-syntax-highlighter` (default theme: `vscDarkPlus` — [demo of available themes](https://react-syntax-highlighter.github.io/react-syntax-highlighter/demo/)). A **copy button** in the top-right corner writes the code to the clipboard and confirms via a sonner toast.
+
+### GitHubGist — live gist embeds
+
+Embed public GitHub Gists directly in MDX:
+
+```mdx
+<GitHubGist id="your-gist-id" figCaptionText="Caption shown below the gist" />
+```
+
+**How it works:**
+1. `GitHubGist` (an async Server Component) calls `https://api.github.com/gists/<id>` for metadata (file name, detected language), then fetches the raw content from the returned `raw_url`. Results are cached for one hour via Next.js ISR (`next: { revalidate: 3600 }`).
+2. The language is mapped to a Prism-compatible token via `GITHUB_GIST_LANGUAGE_MAP` (`src/utils/constants/GitHubGistConstants.ts`) — 70+ languages supported, with sensible fallbacks (`language.toLowerCase()`, then `text`).
+3. The code renders through `GistCodeBlock` inside a scrollable container with a custom green scrollbar.
+
+**Each gist header includes:** a language badge, a **Copy** button (with toast confirmation), and a link to the gist on [mdxgists.net](https://mdxgists.net) — a companion site for browsing and sharing MDX-ready gists. The URL is built as `<GIST_BASE_URL>/<GITHUB_USERNAME>/<gist-id>`; both values are overridable via environment variables.
+
+**Components:**
+- `GitHubGist.tsx` — async Server Component; fetching, language resolution, gist UI
+- `GistCodeBlock.tsx` — syntax-highlighted code display
+- `GistCopyButton.tsx` — client component; copy-to-clipboard + external link
+
+**GitHub token (optional but recommended):** unauthenticated GitHub API requests are limited to **60/hr per IP**. Set `GITHUB_TOKEN` in `.env.local` to raise this to **5,000/hr**. Generate one at GitHub → Settings → Developer settings → Personal access tokens — the read-only `gist` scope (or no scopes for public gists) is sufficient.
+
+> Only **public** gists are supported by default; the component can be extended for private gists with appropriate token scopes.
+
+### MDXImage — optimized images with captions
+
+Wraps the Next.js `<Image>` component with `<figure>`/`<figcaption>` for seamless captions, displayed in a styled container with a green glow border and hover scale effect consistent with the matrix-green design system.
+
+## 🎨 Reader Experience Features
+
+| Feature | Component | Behaviour |
+|---|---|---|
+| **Light/dark mode** | `src/components/ThemeToggle.tsx` | Header toggle between dark (default) and light themes via `next-themes` (`ThemeProvider.tsx`); persisted to `localStorage`. `ThemedToaster.tsx` keeps sonner toasts theme-matched |
+| **Reading progress bar** | `src/components/ReadingProgressBar.tsx` | Thin green bar fixed to the top of article pages; passive scroll listener, `role="progressbar"` ARIA attributes |
+| **Back to top** | `src/components/BackToTopButton.tsx` | Floating button appears after 400px of scroll; smooth-scrolls to top |
+| **Copy link** | `src/components/CopyLinkButton.tsx` | Article-header button; copies the page URL with a brief icon-swap confirmation |
+| **Social share** | `src/components/SocialShareButtons.tsx` | Pre-filled share dialogs for X (Twitter), LinkedIn, and Reddit using the article title and URL |
+| **View counter** | `src/components/ViewCounter.tsx` | Live per-article view count in a Supabase `view_counts` table, incremented atomically via the `increment_view_count` RPC. Dynamic pages increment server-side; static pages call the `/api/views/[slug]` route after hydration |
+
+## 🤖 AI Features
+
+Both AI features use **Claude Haiku** through the Vercel AI SDK and require `ANTHROPIC_API_KEY`.
+
+### Blog Assistant Chatbot (`/chat`)
+
+An interactive AI chatbot optimised for readers of this technical blog.
+
+- **Streaming responses** via `TextStreamChatTransport` and an edge API route (`src/app/api/chat/route.ts`), which converts `UIMessages` with `convertToModelMessages` and streams via `streamText`
+- **Three blog-focused tools** available to the model:
+  - `searchBlogTopics` — searches a curated list of topics covered by this blog (JS, TS, React, Next.js, MDX, Docker, AWS, etc.)
+  - `getCodeExample` — generates a runnable code example for a concept and language
+  - `explainConcept` — produces a brief or detailed technical explanation
+- **Ephemeral conversations** — nothing is persisted server-side; a "New Chat" button clears the session
+- **Tool calls rendered inline** in the message thread via `chat-tool-result.tsx`
+
+Configuration lives in `src/utils/constants/AiChatConfig.ts` (model, temperature, max tokens, system prompt) and `ToolConfig.ts` (tool icons/labels/colours). UI components are under `src/components/chat/` (`chat-interface.tsx`, `chat-messages.tsx`, `chat-input.tsx`, `chat-tool-result.tsx`).
+
+### AI Article Summarizer
+
+A **Generate TL;DR** button above every dynamic article streams a short summary into a collapsible green panel.
+
+- Only the article **slug** is sent over the wire — `src/app/api/summarize/[slug]/route.ts` (edge) fetches the article server-side
+- Protected by an **origin allow-list** (`NEXT_PUBLIC_SITE_URL`), a **per-IP rate limit** (10/min), and a **1-hour in-memory cache** (written via `after()`)
+- The client (`src/components/ArticleSummarizer.tsx`) cancels in-flight requests with `AbortController` on close/unmount
+- Model and prompt configured in `src/utils/constants/AiSummaryConfig.ts`
+
+## 🖥️ Code Sandbox
+
+An interactive in-browser code execution environment powered by **Sandpack** at `/code-sandbox`.
+
+- **JavaScript & TypeScript runtimes** — switch with one click; the editor reloads with a language-appropriate default snippet
+- **Quick Examples** — pre-loaded snippets (Fibonacci, Async/Await, Data Structures for JS; Types & Interfaces, Generics, Classes & OOP for TS) defined in `src/utils/constants/SandboxExamples.ts`
+- **Full editor** — line numbers, inline TypeScript errors, matrix-green custom theme with `JetBrains Mono`
+- **Toolbar** — Run, Copy, Download, and Reset
+- **Live console panel** side-by-side with the editor — execution is **entirely in-browser**; no code reaches the server
+
+Components: `src/components/SandpackEditor.tsx` (provider, editor, toolbar, console) and `CodeSandboxFeaturesSection.tsx` (feature highlights grid).
+
+## 👥 Author Profile Pages
+
+A `/authors` index lists every distinct contributor pulled from the Supabase `Article` table, with per-author profile routes at `/authors/[slug]` showing their bio, avatar, and every article they've published.
+
+## 🔍 Search
+
+Full-text search across published articles at `/search`, powered by native Postgres `tsvector` — no external search service required.
+
+- **Search-as-you-type** — `src/components/ArticleSearch.tsx` debounces input (300 ms), cancels stale requests with `AbortController`, caches repeated queries, and waits for at least 2 characters before querying
+- **Prefix matching** — partial words match while you type (`reac` → `react`)
+- **Ranked, weighted results** — scored by `ts_rank` with column weights (title > tags > description > content) and returned as lightweight summaries (the heavy `content` column is excluded)
+- **Request flow** — `GET /api/search?q=…` (`src/app/api/search/route.ts`) → `searchArticles()` (`src/utils/functions/rpc/searchArticles.ts`) → the `search_articles` Postgres RPC
+
+### One-time setup
+
+Run **`scripts/sql/DDL/createSearchArticlesFunction.sql`** once in the Supabase SQL editor. It creates the weighted GIN index and the `search_articles` function. Search returns an error until this script is deployed.
+
+### ⚠️ Change the hardcoded author filter
+
+The shipped function locks results to a single author:
+
+```sql
+AND a."articleAuthorName" = 'Abdullah Muhammad.'
+```
+
+Before deploying, replace `'Abdullah Muhammad.'` with **your own author name** — it must match the `articleAuthorName` values in your `Article` table **exactly**, including any trailing punctuation. Alternatively, **delete that line entirely** to search across all authors. Re-run the script after editing.
+
+## 📬 Newsletter Subscription
+
+An integrated newsletter signup form powered by [Resend](https://resend.com). Visitors can subscribe from the home page or the bottom of any article; new subscribers are added to a Resend **Audience** and receive a welcome email.
+
+### Components & routes
+- `src/components/NewsletterSignup.tsx` — reusable client component with `matrix` (article pages) and `neutral` (home page) visual variants
+- `src/app/api/newsletter/subscribe/route.ts` — Node-runtime POST handler; validates the email with Zod
+- `src/utils/functions/newsletter/subscribeToNewsletter.ts` — adds the contact to your Audience and triggers the welcome email
+- `src/utils/functions/newsletter/welcomeEmailTemplate.ts` — subject + HTML/text bodies
+- `src/utils/functions/resend_client/ResendClient.ts` — server-only Resend client factory
+
+### Setup
+1. Create a Resend account at [resend.com](https://resend.com)
+2. **API key** — API Keys → Create API Key with **Sending** and **Audiences** access → set `RESEND_API_KEY`
+3. **Audience** — Audiences → Create Audience → copy the UUID into `RESEND_AUDIENCE_ID`
+4. Restart `npm run dev` so Next.js picks up the new variables
+
+### ⚠️ ***Important: a verified sending domain on Resend is required for email delivery to real subscribers.***
+
+Out of the box the welcome email is sent from **`onboarding@resend.dev`**, Resend's sandbox sender, which **only delivers to the email address that owns your Resend account**.
+
+> 🚨 ***You MUST verify your own sending domain (Resend dashboard → Domains → Add Domain, then complete the SPF/DKIM DNS records) before the newsletter can deliver welcome emails to real subscribers.*** Once verified, update the `WELCOME_EMAIL_FROM` constant in `src/utils/functions/newsletter/subscribeToNewsletter.ts` to an address on that domain (e.g. `newsletter@yourdomain.com`).
+
+If the domain step is skipped, the contact is still added to your Audience, but the welcome email silently fails (logged server-side as `[newsletter] Resend emails.send returned an error: ...`).
+
+## 🗄️ Supabase Database
+
+Supabase is integrated **directly in Server Components** — no custom backend API layer. The client factory lives in `src/utils/functions/supabase_client/`.
+
+- **CRUD functions** — `src/utils/functions/crud/` (create, read, update, delete articles)
+- **RPC functions** — `src/utils/functions/rpc/` (e.g. `incrementViewCount`)
+- **SQL scripts** — `scripts/sql/DDL/` (create/alter/drop tables, view-counts table, RPC function) and `scripts/sql/DML/` (insert/fetch/update/delete article statements)
+
+**Ensure your Supabase Row Level Security policies allow the CRUD actions you need** — these are configured in the Supabase console.
+
+Shared constants, helper functions, and TypeScript types live under `src/utils/` (`constants/`, `functions/`, `types/`). Some constants serve as placeholders for this demo application.
+
+## ⌨️ Article Manager CLI
+
+`scripts/action-script/article-manager.ts` manages articles in Supabase from the command line using the CRUD functions above, run via `tsx` (no TypeScript build config needed):
+
+```bash
+# Insert an article into Supabase
+npx tsx article-manager.ts insert article-slug
+
+# Delete an article
+npx tsx article-manager.ts delete article-slug
+
+# Update an article
+npx tsx article-manager.ts update article-slug new-article-file
+
+# Fetch a single article
+npx tsx article-manager.ts fetch article-slug
+
+# Fetch all articles
+npx tsx article-manager.ts fetchAll
+```
+
+The **article slug** is the name of the markdown file in `src/markdown/` minus the `.mdx` extension. The `update` command's second argument follows the same convention.
+
+## 📜 Project Scripts
+
+The `/scripts` folder contains tooling for project and database setup:
+
+- **`scripts/sql/`** — DDL and DML statements for initializing and populating the database
+- **`scripts/powershell/`** — Windows setup plus bulk article/S3 helpers (`project_setup.ps1`, `bulk-create-articles.ps1`, `bulk-update-articles.ps1`, `bulk-s3-folder-creation.ps1`, `create-missing-mdx-files.ps1`)
+- **`scripts/bash/`** — the same toolkit for Linux/macOS
+- **`scripts/action-script/`** — the Article Manager CLI (above)
+- **`scripts/github-gist-fetcher/`** — fetches a public gist's raw content to `src/github_gists/<gist-id>.txt`:
+  ```bash
+  npx tsx scripts/github-gist-fetcher/fetch-github-gist.ts <gist-id>
+  ```
+  > **Note:** no longer required for rendering — `<GitHubGist>` fetches live from the GitHub API. Retained for offline inspection or local caching workflows.
+
+## 🌩️ AWS S3 Image Storage
+
+Images referenced in `.mdx` files (via the `MDXImage` component) are served from AWS S3. The allowed external image domain is configured in `next.config.ts` — point it at your own bucket, or swap in another storage service entirely.
+
+## 🗺️ SEO: Sitemap & Robots
+
+- **`sitemap.xml`** — auto-generated at build time by `src/app/sitemap.ts`, covering all static routes and every dynamic article slug fetched from Supabase
+- **`robots.txt`** — served from `src/app/robots.ts`, permitting all crawlers and pointing them at the sitemap
+
+Both use `NEXT_PUBLIC_SITE_URL` as the base URL.
+
+## 📱 Mobile Responsiveness
+
+All components are built mobile-first with Tailwind responsive prefixes (`sm:`, `md:`, `lg:`). Key behaviours:
+
+| Component | Mobile behaviour |
+|---|---|
+| `ArticleHeader` | Title scales `text-2xl` → `text-4xl`; author row stacks vertically |
+| `ArticleAuthorBio` | Avatar and text stack vertically; full-width button; center-aligned text |
+| `GitHubGist` | Header wraps via `flex-wrap`; code scrolls horizontally with a styled green scrollbar |
+| `CodeBlock` | Copy button absolutely positioned, never interferes with code flow |
+| `MDXImage` | Container scales inline; hover effect on capable devices |
+| Chat & Code Sandbox | Responsive padding and height calculations across breakpoints |
+
+The root layout exports a `viewport` configuration (Next.js `Viewport` type) for correct scaling on all mobile browsers:
+
+```ts
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+};
+```
+
+## 📊 Analytics
+
+Vercel Analytics (`@vercel/analytics`) is integrated to track user interactions and performance metrics — kept lightweight and non-blocking.
+
+## 🐳 Docker
+
+A multi-stage `Dockerfile` at the project root produces a production image with environment variables injected at runtime:
+
+```bash
+docker build -t mdx-medium-blog .
+```
+
+```bash
+docker run \
+  -e SUPABASE_URL=your_supabase_url \
+  -e SUPABASE_ANON_KEY=your_supabase_anon_key \
+  -e ANTHROPIC_API_KEY=your_anthropic_api_key \
+  -e NEXT_PUBLIC_SITE_URL=https://yourdomain.com \
+  -e GITHUB_TOKEN=your_github_token \
+  -e GITHUB_USERNAME=your_github_username \
+  -e GIST_BASE_URL=https://mdxgists.net \
+  -e RESEND_API_KEY=your_resend_api_key \
+  -e RESEND_AUDIENCE_ID=your_resend_audience_id \
+  -p 3000:3000 mdx-medium-blog
+```
+
+The project also remains compatible with **Vercel** and pure **static hosting** (SSG mode).
+
+## 🔗 Useful Links
+
+- [Next.js Documentation](https://nextjs.org/docs)
+- [MDX Documentation](https://mdxjs.com/docs/)
+- [Lee Robinson's Next.js + MDX Tutorial Video](https://www.youtube.com/watch?v=34bRv6cQezo&ab_channel=leerob)
+- [MDX Playground](https://mdxjs.com/playground/)
+- [React Documentation](https://react.dev/)
+- [Supabase Documentation](https://supabase.com/docs)
+- [Docker Documentation](https://docs.docker.com/)
+- [React Syntax Highlighter](https://github.com/react-syntax-highlighter/react-syntax-highlighter)
+- [Sandpack Documentation](https://sandpack.codesandbox.io/docs)
+- [Vercel AI SDK Documentation](https://sdk.vercel.ai/docs)
+- [Anthropic AI SDK Provider](https://sdk.vercel.ai/providers/ai-sdk-providers/anthropic)
+- [Resend Documentation](https://resend.com/docs)
+- [Zod Documentation](https://zod.dev)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-next-mdx-blog-app",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "A production-ready technical blog starter kit built with Next.js, MDX, Supabase, and TypeScript.",
   "author": {
     "name": "Abdullah Muhammad",