🔥 BlogTorch

Where Code Meets Storytelling

A premium developer-focused blogging platform that combines technical writing, code presentation, and storytelling into a unified, notebook-style experience.

Demo • Documentation • Report Bug • Request Feature

📖 Table of Contents

About
Key Features
Tech Stack
Architecture
Getting Started
Project Structure
Block Types
Environment Variables
Database Schema
Development
Deployment
Roadmap
Contributing
License

🎯 About

BlogTorch is a modern, full-stack blogging platform designed specifically for developers, engineers, and technical writers. It bridges the gap between traditional blogging platforms and interactive developer notebooks, enabling you to create rich, narrative-driven posts that seamlessly integrate code, outputs, visualizations, and prose.

Why BlogTorch?

🧩 Block-Based Architecture - Compose content with flexible, reorderable blocks
📓 Notebook-Style Presentation - Familiar interface for developers showcasing code and results
🎨 Developer-First UX - Syntax highlighting, markdown support, and code-focused design
🤝 Built-in Social Features - Engage with the community through likes, comments, and follows
⚡ Modern Tech Stack - Built with the latest web technologies for optimal performance

Perfect For

👨‍💻 Software developers sharing tutorials and insights
🤖 ML practitioners documenting experiments and results
📊 Data scientists showcasing analyses and visualizations
📚 Technical educators creating learning content
🚀 DevOps engineers documenting workflows
💡 Open source contributors building their portfolio

✨ Key Features

🎨 Rich Content Editor

Multiple Block Types: Markdown, Code, Output, Image, Embed, Divider, Callout
Drag & Drop Reordering: Intuitive content organization with @dnd-kit
Real-time Preview: See your content as you write
Auto-save to Drafts: Never lose your work
Syntax Highlighting: Powered by Shiki with multi-language support

👥 Social Engagement

Like System: One-click appreciation for posts
Threaded Comments: Rich discussion with parent-child relationships
Bookmarks: Save posts for later reading
Follow System: Build your network and stay updated
User Profiles: Showcase your work and statistics

🔍 Content Discovery

Explore Page: Browse and search all published posts
Tag-based Navigation: Find content by topics and technologies
Language Filtering: Discover posts by programming language
View & Like Tracking: See what's trending
Author Profiles: Connect with content creators

🔐 Authentication & Security

Clerk Integration: Industry-standard authentication
Role-based Access: User and Admin roles
Protected Routes: Middleware-based protection
Input Validation: Zod schemas for runtime type safety
Content Sanitization: XSS prevention with rehype-sanitize

🎭 Theme System

Light/Dark Mode: System-aware theme switching
Persistent Preferences: Theme saved automatically
Smooth Transitions: Framer Motion animations
Accessible Design: WCAG 2.1 Level AA compliance target

🛠 Tech Stack

Frontend

Technology	Version	Purpose
	16.1.6	React framework with App Router
	19.2.3	UI library with latest features
	5.0+	Type-safe development
	4.0	Utility-first CSS framework
	Latest	Accessible component primitives
	12.34.1	Animation library

Backend & Database

Technology	Version	Purpose
	20+	Server runtime
	Latest	NoSQL database
	6.16.0	Type-safe database ORM
	6.37.5	Authentication & user management

Content Processing

Package	Purpose
`react-markdown`	Markdown rendering
`remark-gfm`	GitHub Flavored Markdown support
`shiki`	Syntax highlighting
`rehype-pretty-code`	Enhanced code block styling
`rehype-sanitize`	XSS protection

State & UI Management

Zustand - Lightweight state management
@dnd-kit - Drag and drop functionality
Sonner - Toast notifications
Lucide React - Icon library
next-themes - Theme management
Zod - Schema validation

🏗 Architecture

BlogTorch is built on a modern, scalable architecture leveraging Next.js 16's App Router for optimal performance.

Core Architecture Principles

Server Components First - Default to server components for better initial load
Progressive Enhancement - Works without JavaScript, enhanced with it
Type Safety - TypeScript across the entire stack
Block-Based Content - Extensible system for new content types
Optimistic Updates - Immediate UI feedback for better UX

Database Design

The MongoDB database uses Prisma ORM with the following core models:

User → Posts → Blocks
  ↓      ↓       ↓
Follows Tags  (Ordered content)
  ↓      ↓
Likes  PostTag
  ↓
Comments
  ↓
Bookmarks

Key Technical Decisions

✅ Next.js App Router - Improved performance and developer experience
✅ MongoDB + Prisma - Flexible schema for block-based content
✅ Clerk Authentication - Outsourced auth for security and ease
✅ Server Actions - Type-safe server mutations
✅ Edge Runtime - Fast, globally distributed responses

🚀 Getting Started

Prerequisites

Node.js 20.x or higher
npm / yarn / pnpm
MongoDB database (local or cloud)
Clerk account for authentication

Installation

Clone the repository

git clone https://github.com/akshitsutharr/BlogTorch.git
cd BlogTorch

Install dependencies

npm install
# or
yarn install
# or
pnpm install

Set up environment variables

Create a .env file in the root directory:

# Database
DATABASE_URL="mongodb+srv://username:password@cluster.mongodb.net/blogtorch"

# Authentication (Clerk)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_SECRET_KEY="sk_test_..."
CLERK_WEBHOOK_SECRET="whsec_..."

# Optional
NEXT_PUBLIC_APP_URL="http://localhost:3000"

Generate Prisma Client

npm run prisma:generate

Push database schema

npm run db:push

Run the development server

npm run dev

Open your browser

Navigate to http://localhost:3000

📁 Project Structure

BlogTorch/
├── prisma/
│   └── schema.prisma          # Database schema definition
├── public/                    # Static assets
├── src/
│   ├── app/                   # Next.js App Router
│   │   ├── (auth)/           # Authentication routes
│   │   │   ├── sign-in/
│   │   │   └── sign-up/
│   │   ├── api/              # API routes
│   │   │   └── webhooks/     # Clerk webhooks
│   │   ├── editor/           # Post editor pages
│   │   │   └── [id]/
│   │   ├── explore/          # Discovery page
│   │   ├── p/                # Post view pages
│   │   │   └── [slug]/
│   │   ├── profile/          # User profiles
│   │   │   └── [username]/
│   │   ├── globals.css       # Global styles
│   │   ├── layout.tsx        # Root layout
│   │   └── page.tsx          # Home page
│   ├── components/           # React components
│   │   ├── blocks/          # Content block renderers
│   │   │   ├── markdown-block.tsx
│   │   │   ├── code-block.tsx
│   │   │   ├── output-block.tsx
│   │   │   ├── image-block.tsx
│   │   │   └── embed-block.tsx
│   │   ├── editor/          # Editor components
│   │   │   ├── block-editor.tsx
│   │   │   └── add-block-menu.tsx
│   │   ├── layout/          # Layout components
│   │   │   ├── navbar.tsx
│   │   │   └── footer.tsx
│   │   ├── providers/       # Context providers
│   │   │   ├── theme-provider.tsx
│   │   │   └── clerk-provider.tsx
│   │   └── ui/              # UI primitives (shadcn/ui)
│   │       ├── button.tsx
│   │       ├── card.tsx
│   │       └── ...
│   ├── lib/                 # Utility functions
│   │   ├── utils.ts         # Helper functions
│   │   └── constants.ts     # App constants
│   ├── server/              # Server-side modules
│   │   ├── auth.ts          # Authentication helpers
│   │   ├── db.ts            # Prisma client
│   │   ├── posts.ts         # Post queries
│   │   └── users.ts         # User queries
│   └── middleware.ts        # Next.js middleware
├── .env                     # Environment variables
├── .gitignore
├── eslint.config.mjs        # ESLint configuration
├── next.config.ts           # Next.js configuration
├── package.json
├── postcss.config.mjs       # PostCSS configuration
├── README.md
├── tailwind.config.ts       # Tailwind configuration
└── tsconfig.json            # TypeScript configuration

🧩 Block Types

BlogTorch supports multiple content block types for rich, flexible storytelling:

1. MARKDOWN Block

Rich text formatting with GitHub Flavored Markdown support.

{
  type: "MARKDOWN",
  data: {
    content: "# Hello World\n\nThis is **markdown** content."
  }
}

Features:

Inline code, links, lists, tables, blockquotes
GitHub Flavored Markdown extensions
Typography optimized for technical writing

2. CODE Block

Syntax-highlighted code with multi-language support.

{
  type: "CODE",
  data: {
    language: "typescript",
    code: "const greeting = 'Hello, World!';"
  }
}

Features:

50+ programming languages
Line numbers
Copy-to-clipboard
Theme-aware highlighting
Language badges

3. OUTPUT Block

Display code execution results and terminal outputs.

{
  type: "OUTPUT",
  data: {
    mimeType: "text/plain",
    content: "Hello, World!"
  }
}

Supported MIME Types:

text/plain - Plain text output
image/png, image/jpeg, image/svg+xml - Image outputs
Base64 encoded data

4. IMAGE Block

Embed images with captions and alt text.

{
  type: "IMAGE",
  data: {
    url: "https://example.com/image.png",
    alt: "Description",
    caption: "Optional caption"
  }
}

5. EMBED Block

Embed external content like YouTube videos.

{
  type: "EMBED",
  data: {
    url: "https://youtube.com/watch?v=..."
  }
}

6. DIVIDER Block

Visual section separators for better content organization.

7. CALLOUT Block

Highlighted information boxes for important notes.

{
  type: "CALLOUT",
  data: {
    type: "info", // info, warning, tip, danger
    content: "Important information here"
  }
}

🔐 Environment Variables

Create a .env file with the following variables:

# Database Configuration
DATABASE_URL="mongodb+srv://username:password@cluster.mongodb.net/blogtorch?retryWrites=true&w=majority"

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_XXXXXXXXXXXXXXXX"
CLERK_SECRET_KEY="sk_test_XXXXXXXXXXXXXXXX"
CLERK_WEBHOOK_SECRET="whsec_XXXXXXXXXXXXXXXX"

# App Configuration (Optional)
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NODE_ENV="development"

Getting Clerk Credentials

Sign up at Clerk.com
Create a new application
Copy the API keys from the dashboard
Set up a webhook endpoint for user synchronization

🗄 Database Schema

Core Models

User

model User {
  id          String   @id @default(auto()) @map("_id") @db.ObjectId
  clerkId     String   @unique
  username    String?  @unique
  displayName String?
  bio         String?
  imageUrl    String?
  role        UserRole @default(USER)
  
  // Social links
  websiteUrl  String?
  githubUrl   String?
  twitterUrl  String?
  
  // Relations
  posts       Post[]
  comments    Comment[]
  likes       Like[]
  bookmarks   Bookmark[]
  followers   Follow[] @relation("followers")
  following   Follow[] @relation("following")
}

Post

model Post {
  id            String     @id @default(auto()) @map("_id") @db.ObjectId
  slug          String     @unique
  title         String
  excerpt       String?
  coverImageUrl String?
  published     Boolean    @default(false)
  source        PostSource @default(EDITOR)
  
  // Relations
  authorId      String     @db.ObjectId
  author        User       @relation(fields: [authorId], references: [id])
  blocks        Block[]
  tags          PostTag[]
  
  // Engagement
  likes         Like[]
  comments      Comment[]
  bookmarks     Bookmark[]
  likeCount     Int        @default(0)
  viewCount     Int        @default(0)
  commentCount  Int        @default(0)
}

Block

model Block {
  id        String    @id @default(auto()) @map("_id") @db.ObjectId
  postId    String    @db.ObjectId
  type      BlockType
  order     Int
  data      Json      // Flexible JSON data for each block type
  
  post      Post      @relation(fields: [postId], references: [id], onDelete: Cascade)
  
  @@index([postId, order])
}

💻 Development

Available Scripts

# Development
npm run dev              # Start development server
npm run build            # Build for production
npm run start            # Start production server
npm run lint             # Run ESLint

# Database
npm run prisma:generate  # Generate Prisma Client
npm run db:push          # Push schema to database
npm run db:studio        # Open Prisma Studio

Code Style

ESLint - Code linting with Next.js config
TypeScript - Strict mode enabled
Prettier - Code formatting (recommended)

Conventions

Use Server Components by default
Mark client components with 'use client'
Co-locate components with their usage
Use TypeScript interfaces for props
Follow the feature-based folder structure

Environment Setup

Make sure to configure all environment variables in your deployment platform:

DATABASE_URL
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
CLERK_SECRET_KEY
CLERK_WEBHOOK_SECRET
NEXT_PUBLIC_APP_URL

🗺 Roadmap

Phase 1: Core Platform ✅

Phase 2: Enhanced Discovery 🚧

Phase 3: Collaboration 📋

Co-authoring posts
Comment mentions (@username)
Direct messaging
Post sharing to social media

Phase 4: Notebook Import 📋

Jupyter Notebook (.ipynb) import
Automatic conversion to blocks
Preserve code + output structure

Phase 5: Analytics 📋

Post performance metrics
Audience demographics
Traffic sources dashboard
Export analytics data

Phase 6: Advanced Editor 📋

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

How to Contribute

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

Development Guidelines

Follow the existing code style
Write meaningful commit messages
Add tests for new features
Update documentation as needed
Keep PRs focused and small

📄 License

Distributed under the MIT License. See LICENSE for more information.

👨‍💻 Author

Akshit Suthar

GitHub: @akshitsutharr

🙏 Acknowledgments

Next.js - The React Framework
Clerk - Authentication made easy
Prisma - Next-generation ORM
Radix UI - Accessible components
shadcn/ui - Beautiful UI components
Vercel - Deployment platform

📞 Support

If you have any questions or need help, feel free to:

Open an issue on GitHub
Star ⭐ this repository if you find it helpful!

Built with ❤️ by developers, for developers

FilesExpand file tree

README.md

Latest commit

History