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
- About
- Key Features
- Tech Stack
- Architecture
- Getting Started
- Project Structure
- Block Types
- Environment Variables
- Database Schema
- Development
- Deployment
- Roadmap
- Contributing
- License
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.
- 🧩 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
- 👨💻 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
- 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
- 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
- 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
- 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
- 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
| 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 |
| Technology | Version | Purpose |
|---|---|---|
 |
20+ | Server runtime |
 |
Latest | NoSQL database |
 |
6.16.0 | Type-safe database ORM |
 |
6.37.5 | Authentication & user management |
| 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 |
- Zustand - Lightweight state management
- @dnd-kit - Drag and drop functionality
- Sonner - Toast notifications
- Lucide React - Icon library
- next-themes - Theme management
- Zod - Schema validation
BlogTorch is built on a modern, scalable architecture leveraging Next.js 16's App Router for optimal performance.
- 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
The MongoDB database uses Prisma ORM with the following core models:
User → Posts → Blocks
↓ ↓ ↓
Follows Tags (Ordered content)
↓ ↓
Likes PostTag
↓
Comments
↓
Bookmarks
- ✅ 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
- Node.js 20.x or higher
- npm / yarn / pnpm
- MongoDB database (local or cloud)
- Clerk account for authentication
- 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
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
BlogTorch supports multiple content block types for rich, flexible storytelling:
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
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
Display code execution results and terminal outputs.
{
type: "OUTPUT",
data: {
mimeType: "text/plain",
content: "Hello, World!"
}
}Supported MIME Types:
text/plain- Plain text outputimage/png,image/jpeg,image/svg+xml- Image outputs- Base64 encoded data
Embed images with captions and alt text.
{
type: "IMAGE",
data: {
url: "https://example.com/image.png",
alt: "Description",
caption: "Optional caption"
}
}Embed external content like YouTube videos.
{
type: "EMBED",
data: {
url: "https://youtube.com/watch?v=..."
}
}Visual section separators for better content organization.
Highlighted information boxes for important notes.
{
type: "CALLOUT",
data: {
type: "info", // info, warning, tip, danger
content: "Important information here"
}
}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"- Sign up at Clerk.com
- Create a new application
- Copy the API keys from the dashboard
- Set up a webhook endpoint for user synchronization
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")
}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)
}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
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- ESLint - Code linting with Next.js config
- TypeScript - Strict mode enabled
- Prettier - Code formatting (recommended)
- 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
Make sure to configure all environment variables in your deployment platform:
DATABASE_URLNEXT_PUBLIC_CLERK_PUBLISHABLE_KEYCLERK_SECRET_KEYCLERK_WEBHOOK_SECRETNEXT_PUBLIC_APP_URL
- User authentication with Clerk
- Block-based editor with drag & drop
- Post publishing and viewing
- Social features (likes, comments, follows)
- Tag system
- Theme switching
- Advanced search with full-text indexing
- Multi-tag filtering
- Trending posts algorithm
- Personalized recommendations
- Author pages with full stats
- Co-authoring posts
- Comment mentions (@username)
- Direct messaging
- Post sharing to social media
- Jupyter Notebook (.ipynb) import
- Automatic conversion to blocks
- Preserve code + output structure
- Post performance metrics
- Audience demographics
- Traffic sources dashboard
- Export analytics data
- Real-time collaborative editing
- Version history with rollback
- AI-assisted writing
- Math equation support (LaTeX)
- Diagram support (Mermaid)
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
- 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
- Follow the existing code style
- Write meaningful commit messages
- Add tests for new features
- Update documentation as needed
- Keep PRs focused and small
Distributed under the MIT License. See LICENSE for more information.
Akshit Suthar
- GitHub: @akshitsutharr
- 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
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