NotionPresso Blog Template Guide

Creating Your Blog with Notion: The Perfect Guide for Developers

Tistory? Medium? Velog? Stuck choosing a blogging platform? 😅

As a developer starting a blog, these thoughts might feel familiar:

•
"Do I need to look up Markdown syntax again..."

•
"Why is it so complicated to upload just one image?"

•
"The code block styling just doesn't feel right..."

•
"I want a truly 'my own' blog without being tied to a platform..."

Being locked into a platform can feel especially restrictive. You want to customize things your way, but you're confined within limited features. 🔒

But what if you could solve all these problems using Notion, the tool you already use every day?

Using the open-source project NotionPresso, you can:

•
Keep using Notion's familiar editing environment

•
Create a fully customizable blog

•
Have a truly personal blog! 🎉

Plus, being open-source means no cost concerns. You can even contribute your own improvements.

This guide will walk you through the entire process of creating and managing a blog with NotionPresso. From writing in Notion to SEO optimization and commenting features - let's create your perfect blog! 🚀

Ready to begin?

🗺️ Complete Guide Map

We'll cover these topics in order:

1
Starting with Notion Blog (Current Chapter)
- •
  NotionPresso Introduction
- •
  Benefits of Notion Blogging

2
Development Environment Setup
- •
  Node.js and Git Installation
- •
  Basic Tools Configuration

3
Understanding the Project Structure
- •
  Explanation of Main Folders and Files
- •
  Finding Points for Customization

4
Notion API Integration
- •
  Getting API Keys
- •
  Setting Up Notion Page Permissions

5
Writing Your First Post
- •
  Writing in Notion
- •
  Blog Integration

6
Cloudflare Deployment
- •
  Setting Up Free Hosting
- •
  Connecting Your Domain

7
Adding Blog Features
- •
  Implementing Comments
- •
  Adding Visitor Analytics (Plausible)

8
SEO Optimization
- •
  Google Search Console Setup
- •
  Search Exposure Optimization

9
Effective Blog Management Tips
- •
  Technical Blog Writing Best Practices
- •
  Increasing Visitor Traffic

Let's dive in! 🚀

Setting Up Your Development Environment: A Step-by-Step Guide for Beginners

💡 "What's a terminal?", "I'm new to Git..." Don't worry! We'll explain everything in detail.

Before We Begin

The tools we'll install serve these purposes:

•
Node.js: The engine that runs your blog

•
Git: Tool for managing and deploying your blog code

•
VSCode: Editor for writing and editing code

Think of them as the engine, steering wheel, and navigation system of a car!

New to Terminal?

The terminal (or command prompt) is like a conversation window with your computer.

•
Windows: Press Windows key + R and type 'cmd'

•
Mac: Search for 'Terminal' in Spotlight (⌘ + Space)

Basic commands:

•
cd foldername: Navigate to a folder

•
dir(Windows) / ls(Mac): View files in current folder

•
cls(Windows) / clear(Mac): Clear screen

1. Installing Node.js

Windows Users

1
Visit Node.js official site and click LTS version

2
Run downloaded file

3
Keep clicking "Next" (maintain default settings)

Mac Users

Run in terminal:

Shell

# Install Homebrew first if you don't have it
/bin/bash -c "$(curl -fsSL <https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh>)"

# Install Node.js
brew install node

Verify Installation

Enter in terminal:

Shell

node --version
npm --version

Success if you see numbers! (e.g., v18.17.0)

2. Installing Git

Windows Users

1
Download Git for Windows

2
Run installer

3
Click "Next" with default settings
- •
  Make sure to check "Git Bash" installation!

Mac Users

Run in terminal:

Shell

brew install git

Verify Installation

Shell

git --version

3. Installing VSCode

1
Download VSCode

2
Run installer

3
(Optional) Install extensions:
- •
  ESLint: Code error checking
- •
  Prettier: Automatic code formatting
- •
  Korean Language Pack: Korean menus (if needed)

4. Creating a GitHub Account

1
Visit GitHub

2
Click "Sign Up"

3
Enter email and password

4
Complete email verification

5. Initial Git Configuration

Run in terminal (replace with your information):

Shell

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

Common Issues and Solutions

1. "Command not found" Error

•
Windows: Check PATH environment variable
1. 1
  Windows key + R → Enter "systempropertiesadvanced"
1. 2
  Environment Variables → Check Path for installation directory

•
Mac: Try restarting Terminal

2. Git Configuration Errors

•
Check for spaces in quotation marks

•
Verify email address format

3. Opening Terminal in VSCode

1
Launch VSCode

2
Press Ctrl + ` or View → Terminal from top menu

Installation Checklist

Node.js installed (node --version works)

Git installed (git --version works)

VSCode installed with extensions

GitHub account created

Git account configured

🎉 Congratulations! All your development tools are now ready. In the next section, we'll use these tools to create your actual blog!

Exploring the NotionPresso Project: A Guide for Beginners

💡 "Too many folders!", "Not sure where to start modifying..." Don't worry! We'll guide you through step by step.

Getting Started: Create Your Own Notion Blog GitHub Repo

Visit: https://github.com/notionpresso/nextjs-blog-template

Click the Use this template button at the top right ⇒ Select Create a new repository.

Set the Owner and enter the Repository Name.

After entering all the information, click the Create repository button.

Clicking the button will create a repository based on the template

Now, the repository for creating your Notion blog is ready!

Getting Started: Project Setup

First, let’s clone the project to your computer. In the created repository, click the Code button and copy the repository URL.

Shell

# Clone the project
# git clone https://github.com/user-name/notion-blog.git my-blog
git clone <copied-url> my-blog


# Move into project folder
cd my-blog 

# Install necessary packages
npm install

Understanding Core Folder Structure

Our blog's structure is organized as follows:

Plain text

my-blog/
├── app/            # Pages and routing
├── components/     # Reusable components
├── content/        # Blog post listings
├── notion-data/    # Data fetched from Notion
└── public/         # Static files like images

Key Files for Modification

1. Modifying Basic Information

app/layout.tsx:

•
Blog title

•
Description

•
SEO information

Typescript

export const metadata = {
  title: {
    default: 'Your Blog Name',  // Modify here
    template: '%s | Your Blog Name',  // Modify here
  },
  description: 'Blog description...',  // Modify here
  // ...
}

2. Setting Up Your Profile

app/page.tsx:

•
Profile image

•
Introduction text

Typescript

<Image
  src="/profile.png"  // Add image to public folder and update path
  alt="Profile Image"
  width={100}
  height={100}
/>

components/nav.tsx:

•
Add/modify menu items

Typescript

const navItems = {
  '/': { name: 'Home' },
  '/blog': { name: 'Blog' },
  '<https://github.com/yourusername>': { name: 'GitHub' },  // Modify
}

4. Managing Blog Posts

content/posts.ts:

•
Manage posts written in Notion

•
Automatically updated by NotionPresso CLI

Special Features

1. Dark Mode

•
Managed in components/theme.tsx

•
Automatically follows system settings

2. RSS Feed

•
Generated in app/rss/route.ts

•
Feature for blog subscribers

3. SEO Optimization

•
app/sitemap.ts: Sitemap for search engines

•
app/robots.ts: Search engine crawling settings

•
app/og/route.tsx: Social media sharing images

Additional Customization

1
Modifying Styles
- •
  app/global.css: Global styles
- •
  Using Tailwind CSS (tailwind.config.js)

2
Image Management
- •
  Store images in public/ folder
- •
  public/notion-data/: Images imported from Notion

Important Notes

•
Don't modify the notion-data/ folder directly as it's auto-generated

•
Always test changes with npm run dev

🎉 Now that you understand the project structure, let's move on to connecting the Notion API in the next section!

Customization Tips

Styling Best Practices

1
Use Tailwind classes when possible for consistency

2
Keep global styles minimal

3
Leverage CSS variables for theme customization

Component Structure

1
Keep components small and focused

2
Use TypeScript for better type safety

3
Follow the folder structure conventions

Common Customization Points

1
Color scheme

2
Typography

3
Layout spacing

4
Navigation structure

5
Post display format

Development Workflow

1
Make changes in development mode

2
Test thoroughly before deployment

3
Keep backups of customized files

4
Document your modifications

Performance Considerations

1
Optimize images before adding to public folder

2
Minimize external dependencies

3
Use dynamic imports when appropriate

4
Keep bundle size in check

Troubleshooting Common Issues

Build Errors

•
Check for missing dependencies

•
Verify file paths are correct

•
Ensure all required environment variables are set

Style Issues

•
Inspect CSS specificity

•
Check for conflicting Tailwind classes

•
Verify media queries for responsiveness

Component Errors

•
Check prop types

•
Verify component imports

•
Debug with React Developer Tools

💡 Remember: The project structure is designed to be modular and maintainable. Don't be afraid to explore and customize, but always keep a backup of your changes!

Connecting Notion API: Fetching Blog Data

💡 Ready to take the first real step towards your awesome blog? Let's set up the Notion data fetching configuration together!

Step 1: Creating a Notion Integration

[Notion Integration Setup Screenshot]

1
Visit Notion developers page (https://developers.notion.com/)

2
Click "View my integrations"

3
Click "New integration" button

4
Set Integration name (e.g., "My Blog")

5
Select Workspace

6
Select Type
1. a
  Click Save Button and Configure integration settings
1. a
  Save the generated Integration Token (you'll need this later!)

Step 2: Setting Page Connection Permissions

[Notion Page Share Settings Screenshot]

1
Open the Notion page where you'll write the blog post ⇒ Click the three dots (○ ○ ○) button in the top right corner ⇒ Click "Connect to" ⇒ Search for and select the integration you just created.

1
Select the integration to grant permissions.

2
Check the permissions.

Step 3: Getting the Page ID

[Notion Page URL Display Screenshot]

1
Copy your Notion page URL

2
Find the page ID in the URL! Example: https://notion.so/myblog/[this-is-your-page-ID]

Step 4: Copying Notion Data to NotionPresso

Run these commands in your terminal:

Typescript

// Install CLI
npm install -g @notionpress/cli

// Copy Notion data to your project
npx npresso --page {{page-url}} --auth {{notion-api-key}}

@notionpresso/cli is designed to work with Next.js project structure. The extracted data is stored in the following structure:

Plain text

my-notion-blog/
├── notion-data/
│   ├── page-id-1.json
│   ├── page-id-2.json
│   └── ...
└── public/
    └── images/
        ├── page-id-1/
        │   ├── image1.png
        │   └── image2.jpg
        ├── page-id-2/
        │   └── image1.png
        └── ...

Key options for @notionpresso/cli:

•
dir: Specify directory for JSON files. Default is ./notion-data

•
image-dir: Specify directory for image files. Default is ./public/images

For example, if you want to change storage locations:

Shell

npx notion-dump --page YOUR_PAGE_URL --auth YOUR_API_KEY --dir ./data --image-dir ./public/assets/images

NotionPresso Components

@notionpresso/react Component Library

NotionPresso is a React component library designed to replicate Notion's block-based editing experience on the web. Through its hierarchical structure, it can accurately render all Notion elements.

Key Component Details

1. `<Notion>` Component

The top-level container component that provides Notion-style typography and layout. This component provides style context for all Notion elements within it, so it must be positioned at the top level.

Typescript

<Notion>
  {/* Other Notion components go here */}
</Notion>

2. `<Notion.Cover>` Component

Displays the post's cover image. Automatically applies the same ratio and style as Notion's cover images. Automatically hides if no image is present.

Typescript

<Notion.Cover src={post.image} />

3. `<Notion.Body>` Component

Container for main content. Automatically applies appropriate padding and margins, and supports responsive layout. Provides optimal readability on mobile devices.

4. `<Notion.Title>` Component

Renders the post title. Applies the same typography and spacing as Notion titles and automatically generates SEO-optimized HTML structure.

5. `<Notion.Blocks>` Component

Automatically recognizes and renders various Notion block types. Supported block types:

•
Text blocks (supports various styling)

•
Image blocks (automatic optimization)

•
Code blocks (syntax highlighting support)

•
Lists (nested support)

•
Tables

•
To-do lists

•
Blockquotes

•
Dividers

Using the NotionRenderer Component

components/notion-renderer.tsx is a wrapper component that effectively combines these components:

Typescript

'use client'
import { Notion } from "@notionpresso/react";
import type { Post } from "content/posts";

export default function NotionRenderer({ post }: { post: Post }) {
  return (
    <Notion>
      <Notion.Cover src={post.image} />
      <Notion.Body>
        <Notion.Title title={post.title} />
        <Notion.Blocks blocks={post.content.blocks} />
      </Notion.Body>
    </Notion>
  )
}

This component has the following characteristics:

1
'use client' directive: Functions as a Next.js client component to support interactive features

2
Type safety: Utilizes TypeScript's type checking capabilities with Post type

3
Structural consistency: Maintains component structure that reflects Notion's document structure

4
Automatic optimization: Handles image optimization, code syntax highlighting automatically

Real Usage Example

3.3. Registering Post Metadata

Modify content/posts.ts file:

Typescript

import newPost from '../notion-data/your-page-id.json'

const posts = [
  {
    title: "My First Blog Post",
    slug: "first-post",
    content: newPost,
    date: "2024-10-22",
    description: "Starting my blog journey...",
    image: undefined
  },
  // ... existing posts
];

In your blog post page, you can use it like this:

Typescript

// app/blog/[slug]/page.tsx
import NotionRenderer from '@/components/notion-renderer'
import posts from 'content/posts'

export default function BlogPost({ params }: { params: { slug: string } }) {
  const post = posts.find(p => p.slug === params.slug)
  if (!post) return <div>Post not found</div>

  return <NotionRenderer post={post} />
}

With this setup, content written in Notion will appear identical on your website, with automatic responsive design and dark mode support.

🎉 Now that we've set up the Notion API connection, you're ready to start writing your first blog post! In the next section, we'll learn how to write and publish your first post.

Writing Your First Post: From Notion to Blog

💡 Ready to start the core part of blogging? Let's walk through the process of writing in Notion and publishing it to your blog!

Step 1: Writing in Notion

•
Create New Page: Create a new page in Notion for your blog post.

•
Write Title: Enter your post title at the top of the page.

•
Create Content: Write your content freely. You can use various blocks including text, images, code blocks, and more.

•
Set Cover Image (Optional): Click 'Add Cover' at the top of the page to add a cover image. This will serve as the featured image for your blog post.

•
Check Integration Access: Verify that your previously created Notion Integration is invited to the page. Click the 'Share' button in the top right corner and confirm the Integration is listed.

•
Public Access (Optional): If you're running a public blog, you don't need to make the page public on the web. The Integration will handle data fetching.

Step 3: Get the Page ID

•
Copy Page URL: Open your Notion page and copy the URL from your browser's address bar.

•
Extract Page ID: Get the page ID from the URL.
- ◦
  Example: https://www.notion.so/yourworkspace/post-title-**abcd1234efgh5678ijkl9012mnop3456**

Step 4: Fetch Data Using NotionPresso CLI

Run the following command in your terminal to fetch the Notion page data:

Shell

# Run this in your project root directory

# Install NotionPresso CLI (first time only)
npm install -g @notionpresso/cli

# Fetch Notion data
npresso --page [page URL or ID] --auth [Notion Integration token]

•
[page URL or ID]: Enter either the full page URL you copied or just the page ID

•
[Notion Integration token]: Enter the Secret key you received when creating your Notion Integration

Example:

Shell

npresso --page {{page URL or ID}} --auth {{Notion Integration token}}

Step 5: Add Post Information to content/posts.ts

Open content/posts.ts file and register your new post's metadata:

Typescript

import newPost from '../notion-data/abcd1234efgh5678ijkl9012mnop3456.json';

const posts = [
  {
    title: "My First Blog Post",
    slug: "first-post",
    content: newPost,
    date: "2023-10-24",
    description: "Beginning my blogging journey...",
    image: newPost.coverImage, // if you have a cover image
  },
  // Keep existing posts if any
];

export default posts;

•
import path filename: This is your page ID with .json extension

•
Field meanings:
- ◦
  title: Post title
- ◦
  slug: Post identifier for URL (e.g., yourblog.com/blog/first-post)
- ◦
  content: The Notion data we just fetched
- ◦
  date: Post creation date (YYYY-MM-DD format)
- ◦
  description: Post summary or description
- ◦
  image: Cover image URL (if available)

Step 6: Check on Local Server

Start the development server in your terminal:

Shell

npm run dev

Visit http://localhost:3000 in your browser to verify your blog displays correctly. Success if your new post appears in the blog list and shows proper content when clicked!

Writing Tips for Your First Post

Structure Your Content Well

•
Use clear headings and subheadings

•
Break content into digestible sections

•
Include relevant code examples where needed

•
Add images to illustrate complex points

Optimize for Readability

•
Keep paragraphs concise

•
Use bullet points for lists

•
Include code snippets with proper syntax highlighting

•
Add relevant images or diagrams

SEO Best Practices

•
Write a compelling title

•
Include relevant keywords naturally

•
Add meta description in your post metadata

•
Use proper heading hierarchy

Technical Considerations

•
Test all code snippets

•
Verify image loading

•
Check mobile responsiveness

•
Ensure proper formatting of code blocks

Common Issues and Solutions

Post Not Showing Up?

•
Check if the page ID is correct

•
Verify Integration permissions

•
Ensure the post is properly added to posts.ts

Images Not Loading?

•
Verify image paths

•
Check cover image URL

•
Ensure images are properly uploaded

Formatting Issues?

•
Check Notion block compatibility

•
Verify markdown formatting

•
Review code block syntax

🎉 Congratulations! Your first post from Notion is now live on your blog.

Next Steps

After publishing your first post, consider:

•
Share it on social media

•
Add tags or categories

•
Enable comments

•
Set up analytics

•
Plan your next post!

Remember, the first post is always the hardest. Each post after this will get easier as you become more familiar with the workflow. Keep writing, keep sharing, and most importantly, enjoy the process! 🌱

💡 Pro Tip: Keep a list of post ideas in Notion to maintain a steady content pipeline for your blog.

Deploying Your Next.js Blog to Cloudflare Pages

1. Preparing Your Next.js Blog Project

This guide will walk you through the step-by-step process of deploying your project to Cloudflare Pages.

2. Connecting to Cloudflare Pages

2-1. GitHub Integration

1
Go to Cloudflare Pages and create an account. If you already have one, just log in.

2
Create a new project in Cloudflare Pages.

3
Connect your GitHub account and select the Next.js project repository you want to deploy.

2-2. Framework Selection and Build Settings

While Cloudflare Pages will recognize that your project is built with Next.js, you should manually select 'Next.js' as the framework.

•
Build command: By default, the next build command will be used automatically.

•
Output directory: No special configuration needed; Cloudflare will automatically handle Next.js static files.

3. Setting Up Node.js Compatibility Flag

Since Cloudflare Pages operates in a serverless environment, some Node.js features might not be compatible by default. To resolve this, you need to activate the Node.js compatibility flag.

•
Enable the nodejs_compat flag in your Cloudflare Pages project settings. This flag ensures that Node.js-based features work properly in Cloudflare Pages.

4. Deployment and Redeployment

4-1. Initial Deployment

When you push code to your GitHub repository, Cloudflare Pages will automatically start the build and deployment process. The build command and output settings are handled automatically based on your framework selection.

4-2. Redeployment

After code modifications or setting changes, pushing a new commit to GitHub will trigger automatic redeployment. With the nodejs_compat flag enabled, Node.js compatibility issues will be resolved during deployment.

5. Verifying Deployment

After the build completes, you can access your site through the URL provided by Cloudflare. You can also set up a custom domain to run your site on your preferred domain.

6. Redeployment After Enabling Node.js Compatibility

For projects using Node.js features, make sure to redeploy after enabling the compatibility flag to ensure all features work correctly.

Troubleshooting Common Deployment Issues

Build Failures

•
Check your build logs for specific errors

•
Verify your dependencies are correctly listed in package.json

•
Ensure your Node.js version is compatible

Route Issues

•
Verify your Next.js routing configuration

•
Check for any hard-coded paths

•
Ensure dynamic routes are properly set up

Asset Loading Problems

•
Check your image and static file paths

•
Verify public directory structure

•
Ensure proper asset optimization settings

Configuration Best Practices

Environment Variables

1
Set up environment variables in Cloudflare Pages dashboard

2
Double-check sensitive information is properly secured

3
Use appropriate production values

Build Settings

1
Optimize build cache usage

2
Set appropriate Node.js version

3
Configure build command if needed

Custom Domain Setup

1
Add your domain in Cloudflare Pages settings

2
Configure DNS settings

3
Wait for SSL certificate provisioning

Performance Optimization Tips

Caching Strategy

•
Configure appropriate cache headers

•
Utilize Cloudflare's edge caching

•
Implement static page generation where possible

Asset Optimization

•
Compress images and other assets

•
Use appropriate loading strategies

•
Implement lazy loading where beneficial

Security Considerations

•
Enable all relevant security headers

•
Configure appropriate CSP settings

•
Implement proper CORS policies

Monitoring and Maintenance

Deployment Monitoring

•
Set up deployment notifications

•
Monitor build times and success rates

•
Keep track of dependency updates

Performance Monitoring

•
Use Cloudflare Analytics

•
Monitor page load times

•
Track error rates and status codes

Regular Maintenance

•
Keep dependencies updated

•
Monitor security advisories

•
Regular backup procedures

This guide covers the essential steps for deploying your Next.js blog to Cloudflare Pages. Remember that the nodejs_compat flag is crucial for ensuring proper functionality. The deployment process is automated through GitHub integration, making it easy to deploy and redeploy as you update your code.

🚀 Pro Tip: Always test your changes locally before pushing to production, and maintain a staging environment for testing major updates.

⚠️ Important: Keep your API keys and sensitive data in environment variables and never commit them to your repository.

Customizing NotionPresso 🎨

💡 Want to style your blog your own way? Let's explore how to customize it with CSS and custom components!

1. Styling with CSS

NotionPresso allows easy style changes through CSS variables. Here are the key CSS variables you can modify:

Css

.notion {
  /* Base Settings */
  --notion-font: system-ui, sans-serif;
  --notion-max-width: 720px;

  /* Color Variables */
  --fg-color: rgb(55, 53, 47);
  --bg-color: #fff;

  /* Spacing Settings */
  --notion-indent: 27px;
}

For more detailed CSS structure and styling guidelines, check out the CSS Structure Documentation!

2. Component Customization

You can customize each Notion block to your liking. Here's an advanced example of customizing the Toggle component, which implements Notion's toggle block:

Typescript

// Toggle Component Customization Example

import React, { useState } from "react";
import { Toggle, type ToggleArgs } from "@notionpresso/cli";
import { ChevronDown, ChevronRight } from "{{your-icon-library}}";

const CustomToggle: React.FC<ToggleArgs> = (props) => {
  const [isOpen, setIsOpen] = useState(false);

  const handleChangeOpen = (open: boolean) => {
    setIsOpen(open);
    // Add additional logic here
    console.log(`Toggle state changed to: ${open}`);
  };

  return (
    <Toggle {...props} isOpen={isOpen} onChangeOpen={handleChangeOpen}>
      <Toggle.Icon>
        {isOpen ? <ChevronDown size={20} /> : <ChevronRight size={20} />}
      </Toggle.Icon>
      <Toggle.Content>{props.children}</Toggle.Content>
    </Toggle>
  );
};

Applying Custom Components

Here's how to use custom components with @notionpresso/react:

Javascript

import { Notion, type NotionPage, type CustomComponents } from '@notionpresso/cli';
import CustomParagraph from './custom-paragraph';
import CustomToggle from './custom-toggle';

const MyNotionPage = ({ pageData }: { pageData: NotionPage }) => {
  const customComponents = useMemo<CustomComponents>(() => ({
    paragraph: CustomParagraph,
    toggle: CustomToggle,
  }), []);

  return (
    <Notion custom={customComponents}>
      <Notion.Cover cover={pageData.cover} />
      <Notion.Body>
        <Notion.Title title={pageData.title} />
        <Notion.Blocks blocks={pageData.blocks} />
      </Notion.Body>
    </Notion>
  );
};

3. Key Customization Points

1
Overall Layout
- •
  Adjust maximum width, margins using CSS variables
- •
  Modify responsive breakpoints
- •
  Customize container spacing

2
Typography
- •
  Change fonts
- •
  Adjust size scales
- •
  Modify line heights
- •
  Customize heading styles

3
Color Scheme
- •
  Define light/dark mode colors
- •
  Create custom theme palettes
- •
  Set accent colors
- •
  Adjust text contrast

4
Block Customization
- •
  Style headings
- •
  Format lists
- •
  Design code blocks
- •
  Customize blockquotes

5
Responsive Design
- •
  Set mobile-specific styles
- •
  Define tablet breakpoints
- •
  Adjust content flow

Advanced Customization Tips

Theme Management

Typescript

const ThemeProvider = ({ children }) => {
  const [theme, setTheme] = useState('light');

  return (
    <div data-theme={theme}>
      {children}
    </div>
  );
};

Custom Block Styles

Css

/* Custom code block styling */
.notion-code-block {
  border-radius: 8px;
  padding: 1rem;
  font-family: 'Fira Code', monospace;
}

/* Custom blockquote styling */
.notion-blockquote {
  border-left: 4px solid var(--accent-color);
  padding-left: 1rem;
  font-style: italic;
}

Responsive Image Handling

Typescript

const ResponsiveImage = ({ src, alt }) => {
  return (
    <div className="notion-image-container">
      <img
        src={src}
        alt={alt}
        loading="lazy"
        className="notion-image"
      />
    </div>
  );
};

Best Practices

Performance Optimization

1
Minimize custom CSS

2
Use CSS variables for theme switching

3
Implement lazy loading for images

4
Optimize component rerenders

Accessibility

1
Maintain proper heading hierarchy

2
Ensure sufficient color contrast

3
Add proper ARIA labels

4
Support keyboard navigation

Code Organization

1
Keep custom components in separate files

2
Use consistent naming conventions

3
Document customizations

4
Maintain a theme configuration file

Common Pitfalls to Avoid

1
Over-customization
- •
  Keep modifications maintainable
- •
  Preserve core functionality
- •
  Document changes thoroughly

2
Specificity Issues
- •
  Avoid deep nesting selectors
- •
  Use BEM methodology
- •
  Maintain consistent specificity levels

3
Performance Impact
- •
  Monitor bundle size
- •
  Optimize image loading
- •
  Reduce unnecessary rerenders

Testing Your Customizations

1
Cross-browser Testing
- •
  Check major browsers
- •
  Test mobile devices
- •
  Verify responsive behavior

2
Performance Testing
- •
  Measure load times
- •
  Check bundle size
- •
  Monitor memory usage

3
Accessibility Testing
- •
  Use screen readers
- •
  Check keyboard navigation
- •
  Verify color contrast

🎨 Ready to make it your own? Remember to take it step by step and test each change thoroughly!

💡 Pro Tip: Start with small changes and gradually build up to more complex customizations as you become familiar with the system.

Congratulations! You're now ready to style your blog in your unique way. 🎉

Adding Comments to Your Blog with Giscus

Want to add a comment section where visitors can share their thoughts and interact? With Giscus, you can easily implement a commenting system based on GitHub Discussions. This guide will walk you through installing and integrating Giscus into your blog step by step.

Introduction to Giscus

Giscus is a comments system powered by GitHub Discussions. Using Giscus, you can easily add commenting functionality to your blog or website using GitHub accounts for authentication.

You can install the Giscus app to GitHub here.

Installing Giscus

To install Giscus, you need to connect the Giscus app to your GitHub repository. Here are the installation steps:

1
Go to the Giscus installation page and click the "Configure" button.

2
Set the required permissions.

3
Configure access permissions for the repository where Giscus will be used.

Repository Setup

To use Giscus, you need to enable Discussions feature in your repository. Follow these steps:

1
Go to your repository settings.

2
Enable the "Discussions" feature.

This allows Giscus to use GitHub Discussions functionality.

Configuring Giscus

After installing Giscus, follow these steps to display comments on your website.

You can easily configure this at Giscus configuration page.

Html

// Script example
<script src="<https://giscus.app/client.js>"
  data-repo="notionpresso/nextjs-blog-template"
  data-repo-id="R_kgDONDy8gg"
  data-category="Announcements"
  data-category-id="DIC_kwDONDy8gs4CjpSV"
  data-mapping="pathname"
  data-strict="0"
  data-reactions-enabled="1"
  data-emit-metadata="0"
  data-input-position="bottom"
  data-theme="preferred_color_scheme"
  data-lang="en"
  crossorigin="anonymous"
  async>
</script>

This script should be inserted in the appropriate location on your webpage.

Integrating Giscus with React

In React projects, you can easily add Giscus using the @giscus/react library. Here's how:

Javascript

'use client'
import Giscus from "@giscus/react";

export default function Comment() {
  return (
    <Giscus
      id="comments"
      repo="notionpresso/nextjs-blog-template"
      repoId="R_kgDONDy8gg"
      category="Announcements"
      categoryId="DIC_kwDONDy8gs4CjpSV"
      mapping="pathname"
      strict="0"
      reactionsEnabled="1"
      emitMetadata="0"
      inputPosition="bottom"
      theme="preferred_color_scheme"
      lang="en"
      loading="lazy"
    />
  )
}

Using Giscus in Next.js Projects

1
Create a Comment component:
Typescript
// components/comment.tsx 'use client' import Giscus from "@giscus/react"; export default function Comment() { return ( <Giscus id="comments" repo="notionpresso/nextjs-blog-template" repoId="R_kgDONDy8gg" category="Announcements" categoryId="DIC_kwDONDy8gs4CjpSV" mapping="pathname" strict="0" reactionsEnabled="1" emitMetadata="0" inputPosition="bottom" theme="preferred_color_scheme" lang="en" loading="lazy" /> ) }

2
Add the comment component to your blog post page:
Javascript
//app/blog/[slug].tsx import { notFound } from 'next/navigation' import posts from 'content/posts' import NotionRenderer from 'components/notion-renderer' import Comment from 'components/comment' {{existing content remains the same}} export default async function Blog({ params }) { const { slug } = await params let post = posts.find((post) => post.slug === slug) if (!post) { notFound() } return ( <section> // {{content omitted}} <NotionRenderer post={post} /> <Comment /> </section> ) }

3
Run npm run dev to check it's working!

Advanced Configuration

Customizing Appearance

Typescript

<Giscus
  theme="dark_dimmed"  // Change theme
  inputPosition="top"  // Move comment box to top
  lang="en"           // Change language
/>

Handling Theme Changes

Typescript

const [theme, setTheme] = useState('light');

<Giscus
  theme={theme === 'dark' ? 'dark_dimmed' : 'light'}
  // other props...
/>

Custom Styling

Css

.giscus {
  margin-top: 2rem;
  padding: 1rem;
  border-top: 1px solid #eaeaea;
}

Best Practices

1
Performance
- •
  Use lazy loading
- •
  Place comments at the bottom of the page
- •
  Defer comment loading until needed

2
User Experience
- •
  Clear instructions for first-time users
- •
  Proper error handling
- •
  Responsive design support

3
Maintenance
- •
  Regular monitoring of discussions
- •
  Prompt response to user comments
- •
  Regular updates of the Giscus package

Troubleshooting

Common Issues

1
Comments not loading
- •
  Check repository permissions
- •
  Verify correct repo and category IDs
- •
  Check browser console for errors

2
Styling problems
- •
  Theme inconsistencies
- •
  Layout issues
- •
  Mobile responsiveness

3
Authentication issues
- •
  GitHub permissions
- •
  CORS errors
- •
  Cookie settings

🎉 Congratulations! Your blog now has a fully functional comment system powered by GitHub Discussions!

💡 Pro Tip: Regularly engage with your commenters to build a community around your blog.

Remember to moderate discussions and maintain a healthy commenting environment for your blog's community! 🌟

SEO Optimization and Search Console Integration Guide

The key to having your blog appear well in search engines lies in proper SEO optimization. This project integrates SEO through robots.txt, sitemap.xml, RSS feed, and metadata configuration.

1. Setting up Google Analytics

For detailed instructions on setting up Google Analytics, please refer to the official tutorial video:

2. SEO Configuration Components

2.1 `robots.txt` Configuration

The robots.txt file defines rules for search engine crawlers exploring your website. It helps control which pages should be crawled and indexed. This project specifies the sitemap location in the robots.txt file to help search engines understand your site structure.

Typescript

import { baseUrl } from 'app/sitemap'

export default function robots() {
  return {
    rules: [
      {
        userAgent: '*',
      },
    ],
    sitemap: `${baseUrl}/sitemap.xml`,
  }
}

This code defines the robots.txt settings, allowing all search engine crawlers access and specifying the sitemap location.

2.2 `sitemap.xml` Generation

The sitemap.xml file informs search engines about all URLs on your website. It clearly defines your website's structure and helps search engines quickly find and crawl important pages. The sitemap should be updated regularly to include new blog posts automatically.

Typescript

import posts from "content/posts"

export const baseUrl = '<https://portfolio-blog-starter.vercel.app>'

export async function sitemap() {
  let blogs = posts.map((post) => ({
    url: `${baseUrl}/blog/${post.slug}`,
    lastModified: post.date,
  }))

  let routes = ['', '/blog'].map((route) => ({
    url: `${baseUrl}${route}`,
    lastModified: new Date().toISOString().split('T')[0],
  }))

  return [...routes, ...blogs]
}

2.3 RSS Feed Implementation

RSS feeds allow users to subscribe to your blog and help search engines quickly detect new content. This project provides RSS functionality for both users and search engines:

Typescript

import { baseUrl } from 'app/sitemap'
import posts from 'content/posts'

export const runtime = 'edge';

export async function GET() {
  const itemsXml = posts
    .sort((a, b) => {
      if (new Date(a.date) > new Date(b.date)) {
        return -1
      }
      return 1
    })
    .map(
      (post) =>
        `<item>
          <title>${post.title}</title>
          <link>${baseUrl}/blog/${post.slug}</link>
          <description>${post.description}</description>
          <pubDate>${new Date(post.date).toUTCString()}</pubDate>
        </item>`
    )
    .join('\\n')

  const rssFeed = `<?xml version="1.0" encoding="UTF-8" ?>
  <rss version="2.0">
    <channel>
        <title>My Portfolio</title>
        <link>${baseUrl}</link>
        <description>This is my portfolio RSS feed</description>
        ${itemsXml}
    </channel>
  </rss>`

  return new Response(rssFeed, {
    headers: {
      'Content-Type': 'text/xml',
    },
  })
}

2.4 Metadata Configuration

Page-specific metadata is crucial for SEO. Here's how we set up metadata for each page:

Typescript

export function generateMetadata({ params }) {
  let post = posts.find((post) => post.slug === params.slug)
  if (!post) {
    return
  }
  let {
    title,
    date: publishedTime,
    description,
    image,
  } = post
  let ogImage = image
    ? image
    : `${baseUrl}/og?title=${encodeURIComponent(title)}`

  return {
    title,
    description,
    openGraph: {
      title,
      description,
      type: 'article',
      publishedTime,
      url: `${baseUrl}/blog/${post.slug}`,
      images: [
        {
          url: ogImage,
        },
      ],
    },
    twitter: {
      card: 'summary_large_image',
      title,
      description,
      images: [ogImage],
    },
  }
}

3. Google Search Console Integration

Google Search Console is essential for monitoring and improving your site's SEO performance.

Benefits of Search Console Integration:

1
Indexing Status Monitoring
- •
  Track how your site is being indexed
- •
  Identify and fix problematic pages
- •
  Submit new content for indexing

2
Search Traffic Analysis
- •
  Monitor search queries leading to your site
- •
  Identify valuable keywords
- •
  Track click-through rates

3
Technical Issue Detection
- •
  Identify crawling errors
- •
  Monitor mobile usability
- •
  Track security issues

4
SEO Performance Tracking
- •
  Monitor search visibility
- •
  Track click rates
- •
  Analyze search rankings

Setting Up Search Console

For detailed setup instructions, watch:

4. SEO Best Practices

Content Optimization

1
Use descriptive titles and headings

2
Include relevant keywords naturally

3
Write compelling meta descriptions

4
Optimize image alt texts

Technical Optimization

1
Ensure fast page loading

2
Implement responsive design

3
Use semantic HTML

4
Create clean URLs

User Experience

1
Optimize mobile experience

2
Improve site navigation

3
Reduce bounce rates

4
Increase page engagement

5. Monitoring and Maintenance

Regular Checks

1
Monitor search performance

2
Track keyword rankings

3
Update content regularly

4
Fix broken links

Performance Optimization

1
Optimize image sizes

2
Minimize code

3
Use caching effectively

4
Monitor Core Web Vitals

Content Strategy

1
Create quality content

2
Update existing content

3
Target relevant keywords

4
Build quality backlinks

🔍 Pro Tip: Regularly check your Search Console for new insights and optimization opportunities.

📈 Remember: SEO is an ongoing process, not a one-time setup. Keep monitoring and improving!

This comprehensive approach to SEO will help increase your blog's visibility and attract more readers to your content. Remember to regularly check your analytics and search console data to continually improve your site's performance.

Effective Technical Blog Writing: Practical Tips and Know-how 🚀

Hello, developers starting your blog journey with NotionPresso!

Want to write great posts but not sure where to begin? Don't worry. Here are effective writing tips based on real success stories.

1. The Title is Half the Battle! 📌

The first secret of successful posts is the title. Analyzing posts that reached 80K views reveals these title patterns:

•
Use emotionally engaging keywords: "Shocking!", "Finally"

•
Generate curiosity: "...is possible?"

•
Target audience: "If you're a frontend developer..."

•
Emphasize practicality: "How to...", "...tips"

Bad Example: "React Component Optimization" Good Example: "The Real Reason Your React Performance Isn't Improving!"

2. Capture Readers with Series 📚

Build reader loyalty through series posts:

•
Declare the series: "Chart Library Maker Log #1"

•
Preview next posts: "In the next part, we'll cover performance optimization"

•
Create connections: Reference and link to previous posts

Don't just relay information, share real experiences:

•
Include trial and error: "At first, I failed doing it this way"

•
Add dramatic elements: "Problem → Consideration → Solution" structure

•
Share emotions: "I felt really stuck at this point..."

4. Reader Engagement is Essential! 💬

Comments and interaction drive blog growth:

•
End with questions: "What method do you use?"

•
Request opinions: "What do you think about this approach?"

•
Suggest future topics: "Let me know in the comments what topics you'd like to see next!"

5. Information Must Be Structured 📑

Ways to convey complex information easily:

•
Step-by-step explanations

•
Utilize code blocks

•
Visual aids (diagrams, screenshots)

•
Emphasize key phrases (bold text, emojis)

Advanced Writing Strategies

Content Planning

1
Topic Selection
- •
  Choose relevant topics
- •
  Focus on solving specific problems
- •
  Address common pain points

2
Research Phase
- •
  Gather accurate information
- •
  Verify technical details
- •
  Include up-to-date resources

3
Content Structure
- •
  Clear introduction
- •
  Logical flow
- •
  Strong conclusion

Writing Process

1
First Draft
- •
  Write freely
- •
  Focus on content over style
- •
  Include all technical details

2
Revision
- •
  Check technical accuracy
- •
  Improve clarity
- •
  Add examples and illustrations

3
Final Polish
- •
  Proofread thoroughly
- •
  Format consistently
- •
  Test all code samples

Technical Writing Best Practices

Code Examples

1
Keep it Simple
- •
  Start with basic examples
- •
  Build complexity gradually
- •
  Explain key concepts

2
Format Properly
- •
  Use correct syntax highlighting
- •
  Include comments
- •
  Show expected output

3
Best Practices
- •
  Follow coding standards
- •
  Include error handling
- •
  Show real-world applications

Visual Elements

1
Screenshots
- •
  Clear and focused
- •
  Highlight important parts
- •
  Include captions

2
Diagrams
- •
  Simple and clear
- •
  Logical flow
- •
  Proper labeling

3
Code Output
- •
  Show expected results
- •
  Include error cases
- •
  Demonstrate success scenarios

Engagement Strategies

Building Community

1
Encourage Discussion
- •
  Ask thoughtful questions
- •
  Respond to comments
- •
  Foster healthy debate

2
Share Knowledge
- •
  Explain complex topics simply
- •
  Share personal experiences
- •
  Admit and learn from mistakes

3
Stay Connected
- •
  Regular posting schedule
- •
  Update old content
- •
  Follow up on discussions

Content Distribution

1
Social Media
- •
  Share on relevant platforms
- •
  Use appropriate hashtags
- •
  Engage with responses

2
Developer Communities
- •
  Share in relevant forums
- •
  Participate in discussions
- •
  Build genuine connections

3
SEO Optimization
- •
  Use relevant keywords
- •
  Write meta descriptions
- •
  Include proper headings

Maintaining Quality

Regular Review

1
Content Updates
- •
  Keep information current
- •
  Update outdated examples
- •
  Add new insights

2
Technical Accuracy
- •
  Verify code examples
- •
  Update dependencies
- •
  Check for deprecated features

3
Reader Feedback
- •
  Address comments
- •
  Incorporate suggestions
- •
  Fix reported issues

Start your journey with NotionPresso now! Don't worry if your first post isn't perfect. You'll naturally develop your own style as you write more. Why not start right now? 🌱

💡 Pro Tip: Keep a list of article ideas in Notion to maintain a steady content pipeline.

🎯 Remember: The best technical content combines accuracy with accessibility.

Now you're ready to start creating engaging technical content that provides real value to your readers. Good luck with your blogging journey! 🚀

Concluding Your NotionPresso Blog Journey

We've now completed our journey of creating your personal blog using Notion and NotionPresso. The ability to write in the familiar Notion environment, customize to your heart's content, and run your blog for free is truly compelling.

What We've Covered

Throughout this guide, we've explored:

1
Setting up your development environment

2
Understanding project structure

3
Connecting with Notion API

4
Deploying your blog

5
Customizing your space

6
Optimizing for search engines

7
Building reader engagement

Why This Approach Works

Your blog is more than just a collection of posts. It becomes:

•
A platform for documenting your growth

•
A space for connecting with others

•
A springboard for new opportunities

•
A showcase for your expertise

Next Steps

As you move forward with your blog:

Immediate Actions

1
Write your first post

2
Set up analytics

3
Configure comments

4
Share with your network

Long-term Goals

1
Develop a content strategy

2
Build a consistent posting schedule

3
Engage with your audience

4
Monitor and optimize performance

Technical Maintenance

Remember to:

•
Keep dependencies updated

•
Monitor performance metrics

•
Backup your content regularly

•
Stay current with NotionPresso updates

Content Strategy

Consider:

•
Creating content series

•
Building a content calendar

•
Engaging with readers

•
Collecting feedback

•
Iterating and improving

Growing Your Platform

Focus on:

•
Consistent quality

•
Regular updates

•
Community engagement

•
SEO optimization

•
Performance monitoring

Final Thoughts

A blog is a journey, not a destination. Each post you write, each reader you connect with, and each improvement you make contributes to your growth as a developer and content creator.

Remember:

•
Start small but start today

•
Consistency beats perfection

•
Engage genuinely with your readers

•
Keep learning and improving

•
Share your unique perspective

Thank you for joining us on this journey to create your perfect blog with NotionPresso. We can't wait to see what you'll create! 🎉

💡 Pro Tip: The best time to start blogging was yesterday. The second best time is now!

🌱 Remember: Every expert was once a beginner. Your journey starts here.

Now go forth and share your knowledge with the world! 🚀

NotionPresso Blog Template Guide

Creating Your Blog with Notion: The Perfect Guide for Developers

🗺️ Complete Guide Map

Setting Up Your Development Environment: A Step-by-Step Guide for Beginners

Before We Begin

New to Terminal?

1. Installing Node.js

Windows Users

Mac Users

Verify Installation

2. Installing Git

Windows Users

Mac Users

Verify Installation

3. Installing VSCode

4. Creating a GitHub Account

5. Initial Git Configuration

Common Issues and Solutions

1. "Command not found" Error

2. Git Configuration Errors

3. Opening Terminal in VSCode

Installation Checklist

Exploring the NotionPresso Project: A Guide for Beginners

Getting Started: Create Your Own Notion Blog GitHub Repo

Getting Started: Project Setup

Understanding Core Folder Structure

Key Files for Modification

1. Modifying Basic Information

2. Setting Up Your Profile

3. Modifying Navigation Menu

4. Managing Blog Posts

Special Features

1. Dark Mode

2. RSS Feed

3. SEO Optimization

Additional Customization

Important Notes

Customization Tips

Styling Best Practices

Component Structure

Common Customization Points

Development Workflow

Performance Considerations

Troubleshooting Common Issues

Build Errors

Style Issues

Component Errors

Connecting Notion API: Fetching Blog Data

Step 1: Creating a Notion Integration

Step 2: Setting Page Connection Permissions

Step 3: Getting the Page ID

Step 4: Copying Notion Data to NotionPresso

NotionPresso Components

@notionpresso/react Component Library

Key Component Details

1. <Notion> Component

2. <Notion.Cover> Component

3. <Notion.Body> Component

4. <Notion.Title> Component

5. <Notion.Blocks> Component

Using the NotionRenderer Component

Real Usage Example

3.3. Registering Post Metadata

Writing Your First Post: From Notion to Blog

Step 1: Writing in Notion

Step 2: Verify Page Sharing and Integration Permissions

Step 3: Get the Page ID

Step 4: Fetch Data Using NotionPresso CLI

Step 5: Add Post Information to content/posts.ts

Step 6: Check on Local Server

Writing Tips for Your First Post

Structure Your Content Well

Optimize for Readability

SEO Best Practices

Technical Considerations

Common Issues and Solutions

Post Not Showing Up?

Images Not Loading?

Formatting Issues?

Next Steps

1. `<Notion>` Component

2. `<Notion.Cover>` Component

3. `<Notion.Body>` Component

4. `<Notion.Title>` Component

5. `<Notion.Blocks>` Component

2.1 `robots.txt` Configuration

2.2 `sitemap.xml` Generation