Recently, I was inspired by a LinkedIn post about creating your own blog using Claude Code and Notion. Since I know how cumbersome it is to write a blog in Markdown format, I thought using Notion, which I love, would make it easier to manage my blog posts. I requested to connect with the author to learn about their process, as messaging non-connections is now a premium feature on LinkedIn. Unfortunately, she didn't respond to my request, so I decided to DIY.

Prerequisite

  • Claude Code (requires pro plan)
  • Notion
  • Vercel account (deployment)
  • A little bit of web programming experience (Optional, but if you have no experience at all, it will cost you more time and effort)

Process

  1. Write a prompt on Claude to generate a specification for the blog
  2. The first design and debugging
  3. Connect your blog to Notion
  4. Iterate debugging
  5. Deploy to Vercel

Writing a prompt

This was my first time vibe coding, so without any knowledge of prompt engineering, I simply described the type of blog I wanted to build.

I'm trying to build a blog from scratch including design and code.
I want to use Next.js since I’m already familiar with React, and Tailwind should work fine.
Later on, I’d like to connect the blog with my Notion account so that whenever I write a post in Notion, it automatically syncs with my blog.

The blog should include the following features:
•	Homepage with recent posts
•	Individual post pages
•	Post listing/archive page
•	Markdown support for writing posts
•	Responsive design
•	Dark mode toggle
•	Tag and category system
•	RSS feed
•	Search functionality
•	Good SEO

I also asked Claude to create a markdown file for implementation, and it delivered the following:

# Blog Project

## Goal
Build a blog from scratch using Next.js and Tailwind, with future Notion integration for content management.

## Tech Stack
- Framework: Next.js (App Router)
- Styling: Tailwind CSS
- Content: Markdown files (later: Notion API integration)
- Deployment: Vercel

## Design Reference
See `design-reference.html` for the complete design implementation including:
- Homepage with sidebar layout
- Post page (full-width)
- About page (full-width)
- Dark mode toggle with system preference detection
- All spacing, colors, and typography specifications

### Design Specifications

#### Colors
- **Accent Colors:**
  - Mint: `#10b981`
  - Purple-blue: `#6366f1`
- **Light Mode:**
  - Background: `#ffffff`
  - Sidebar bg: `#fafafa`
  - Text primary: `#111827`
  - Text secondary: `#6b7280`
  - Border: `#e5e7eb`
- **Dark Mode:**
  - Background: `#111827`
  - Sidebar bg: `#1f2937`
  - Text primary: `#f9fafb`
  - Text secondary: `#9ca3af`
  - Border: `#374151`

#### Layout
- **Homepage:**
  - Sidebar: 300px fixed width, sticky positioning
  - Main content: Max width 900px, flexible
  - Sidebar contains: Profile photo (120px circle), name, title, bio, social links (GitHub, LinkedIn), navigation (Articles, About), theme toggle
- **Post/About Pages:**
  - Full-width layout (no sidebar)
  - Max content width: 800px
  - Back link and theme toggle in header
  - Centered content

#### Typography
- **Headings:**
  - Page title: 32px, font-weight 700
  - Post title (list): 24px, font-weight 700
  - Post title (single): 42px, font-weight 700
  - H2: 28px, font-weight 700
  - H3: 22px, font-weight 600
- **Body:**
  - Base: 15px, line-height 1.6
  - Post content: 17px, line-height 1.8
- **Metadata:**
  - Small text: 13-14px
  - Monospace for dates: 'Courier New', monospace

#### Components
- **Post List Item:**
  - Metadata row: date, read time
  - Title (clickable, hover: purple-blue)
  - Excerpt
  - Tags (pill style, hover: mint)
  - Bottom border separator
  - Hover effect: translateX(4px)
- **Profile Sidebar:**
  - Gradient avatar placeholder
  - Social links: 40x40 rounded squares
  - Navigation links with hover states
  - Theme toggle button at bottom
- **Pagination:**
  - Centered, 40x40 number boxes
  - Active state: purple-blue background

#### Interactions
- Smooth hover transitions (0.2s)
- Dark mode toggle syncs across all pages
- Theme preference stored in localStorage
- System preference detection on first load

## Phase 1: Core Blog (Current Focus)
Build fully functional blog with local markdown files first, then add Notion sync later.

### Features to Implement
- Homepage with recent posts
- Individual blog post pages
- Post listing/archive page
- Markdown support for writing posts (MDX preferred for flexibility)
- Responsive design (mobile-first)
- Dark mode toggle with persistence
- Tag/category system with filtering
- RSS feed generation
- Search functionality
- SEO optimization (meta tags, Open Graph, sitemap, structured data)

## Phase 2: Notion Integration (Future)
- Sync posts from Notion database to blog
- Automatic content updates
- Preserve frontmatter/metadata from Notion properties

## Content Structure
### Markdown Files (Phase 1)

/content/posts/
  - post-slug.md


### Frontmatter Format
yaml
---
title: "Post Title"
date: "2025-01-15"
excerpt: "Brief description"
tags: ["tag1", "tag2"]
readTime: "5 min"
published: true
---


## Development Approach
1. Initialize Next.js project with Tailwind and TypeScript
2. Set up project structure and routing
3. Implement the exact design from design-reference.html
4. Create reusable components (Sidebar, PostCard, ThemeToggle, etc.)
5. Implement markdown/MDX rendering system
6. Build dark mode with localStorage + system preference
7. Create core pages (home, post, about)
8. Implement tag filtering and search
9. Add RSS feed generation
10. Optimize SEO (metadata, sitemap, robots.txt)
11. Make fully responsive
12. Deploy to Vercel

## Technical Requirements
- Server-side rendering for SEO
- Static generation where possible for performance
- Type-safe with TypeScript
- Clean component architecture
- Accessibility compliance (WCAG 2.1 AA)
- Match design-reference.html pixel-perfect

## Notes for Claude Code
- Use Next.js App Router (not Pages Router)
- Implement proper TypeScript typing throughout
- Use next-mdx-remote or contentlayer for markdown rendering
- Store theme preference in localStorage with system preference fallback
- Generate RSS feed at build time
- Use next/image for optimized images
- Follow the design system in design-reference.html exactly
- Implement smooth transitions and hover states as shown in reference
- Ensure all interactive elements have proper focus states

FYI: Currently, my blog doesn't match these specs exactly because I made some changes through Claude Code and manually

The first design and debugging

Claude gave me a quite satisfying design at first, but it wasn't perfect. Some design elements were placed in the wrong locations and felt off from others. After I fixed the errors through instructing Claude Code, it looked like the following link. Go and take a look!

blog_design_preview.html

It’s pretty similar to my current blog (only Desktop mode), but I wanted to change some of the colors and layouts. Thanks to my programming background, I was able to update everything manually. Though I’m sure Claude Code could handle the job just as well.

Connect to Notion

This part took up a lot of time because of the outdated information provided by Claude Code. The issue was that Notion had updated its API a couple of weeks ago, so I’m guessing that’s why it gave me the wrong instructions.

  1. Create a Notion Integration (Notion Integrations)

    YOU MUST COPY Internal Integration Token. This token will allow you to connect your blog to Notion

  2. Create a Notion Database

    Add the following properties to your database. This will be the metadata of each post.

    ### Required Properties

| Property Name | Property Type | Description                         |
|---------------|---------------|-------------------------------------|
| **Title**     | Title         | The post title (default property)   |
| **Published** | Checkbox      | Whether the post is published       |
| **Date**      | Date          | Publication date                    |
| **Excerpt**   | Text          | Brief description/excerpt           |
| **Tags**      | Multi-select  | Post tags/categories                |
| **Slug**      | Text          | URL slug for the post               |
| **ReadTime**  | Text          | Estimated read time (e.g., "5 min") |

  3. Share Database with Integration

    Click the three dots in the top-right corner of the database.

    Click add connections and find your integration from Step 1

  4. Get Database ID → Claude gave me the wrong instructions on this part.

    Image

    Click the panel icon left to the New button

    Click Manage data sources

    Click three dots next to your database title and Copy data source ID

  5. Find .env.local in your local directory. Claude Code should have generated for you.

    Paste your Internal Integration Token and data source ID as following.

    # Notion Integration
NOTION_API_KEY=Your Internal Integraion Token
NOTION_DATABASE_ID=Your data source ID

  6. It’s Done!

Deploy to Vercel

  1. Open a terminal in your project’s root directory

  2. Install Vercel CLI

    npm i -g vercel

  3. Initial Deployment

    vercel --prod

This process is well documented in Vercel homepage. Thus, I think it’s better to share official documentation with you.

https://vercel.com/docs/deployments

Conclusion

Building this blog with Claude Code and Notion proved that AI can significantly speed up the development process when you already have some programming knowledge. While there were challenges such as outdated API information and minor design adjustments, the overall workflow was efficient and educational. Integrating AI with familiar tools such as Next.js, Tailwind, and Notion not only streamlined the process but also highlighted how AI can amplify creativity and productivity, rather than replace technical understanding.