Matt Palmer

Head of Developer Relations

​
Build a Notion-powered blog with Replit Agent

Notion is a powerful tool for organizing information, and it excels as a Content Management System (CMS). By integrating Notion with Replit, you can manage your website’s content—like blog posts, portfolio items, or product listings—directly from your Notion workspace.

Replit, powered by Replit Agent, handles the coding, hosting, and deployment, letting you go from idea to a live application quickly. Effective prompting is key to guiding Agent; for a comprehensive guide, see Efficient prompting with Replit AI and How to vibe code effectively.

This tutorial guides you through building a minimalistic blog that pulls its posts from a Notion table. You will:

  • Use Replit Agent to generate the initial application
  • Connect your Replit app to a Notion database
  • Learn to guide the AI and troubleshoot common issues using effective prompting techniques
  • Deploy your blog for the world to see

Final result: A minimalistic blog powered by Notion

The tutorial will follow largely from the video above, but with some additional context and steps to help you understand the process.

​
Prerequisites

To follow this tutorial, you’ll need:

  • A Replit account
  • A Notion account
  • Familiarity with basic Replit Agent interactions. If you’re new to Agent, check out the Replit Agent documentation.

​
Step 1: Prepare your Notion database

Before prompting Agent, set up your content source in Notion. This involves thinking procedurally about what your blog needs, similar to planning a product.

1

Create a Notion integration

  1. In Notion, go to Settings & members (usually in the top-left sidebar).
  2. Navigate to Connections (previously “Integrations”).
  3. Select Develop or manage integrations.
  4. Click + New integration.

Creating a new integration in Notion

  1. Name your integration (e.g., “My Replit Blog Integration”).
  2. Associate it with your desired workspace.

Configuring your Notion integration

  1. For “Integration type,” choose Internal Integration.
  2. Click Submit.
  3. Copy your Internal Integration Secret (token) and save it securely. This is your Notion API key.

Obtaining your Integration Secret

  1. Under Capabilities, ensure “Read content” is enabled. For this tutorial, reading is sufficient. If you later want to write data to Notion, enable “Insert content” and “Update content.”

Create a new integration for each project to manage permissions granularly. This is a security best practice.

For more detailed instructions, refer to Notion’s official documentation on creating an integration.

You can directly access Notion’s integrations dashboard at notion.so/my-integrations.

2

Create a Notion page with a database

  1. Create a new page in Notion for your blog content.
  2. On this page, add a new Table database.
  3. Name your table (e.g., “Blog Posts”).
  4. Define columns for your posts. Specify these clearly in your mind, as you’ll soon tell Agent about them:
    • Title (Text, default title property)
    • Body (Text, for main post content)
    • Slug (Text, for URL-friendly identifiers)
    • PublishedDate (Date, or use “Created time” / “Last edited time”)
    • ReadingTime (Text or Number, e.g., “5 min read”)
    • Description (Text, short summary for previews)

Example Notion database setup for blog posts

  1. Add a few sample posts. You can use Notion’s AI features to help generate content!
3

Connect your integration to the page

  1. Open the Notion page containing your database.
  2. Click the ••• (three dots) menu in the top-right corner.

Access the integration menu in Notion

  1. Select + Add connections.
  2. Search for and select the integration you created (e.g., “My Replit Blog Integration”).

Adding your integration to the Notion page

  1. Confirm the connection. This allows Replit (via the integration token) to access this page and its database.

​
Step 2: Prompt Replit Agent

With Notion set up, let’s get Replit Agent to build our blog’s foundation. Plan before you prompt: a clear outline of features leads to more focused prompts.

1

Open Replit Agent

Navigate to the Replit homepage and open Agent.

2

Write your prompt

Provide Agent with a detailed prompt. Simplify your language, but be specific about requirements, constraints, and desired outputs. Here’s an example:

Help me create a hyper-minimalistic blog using Notion as a CMS.
The blog should pull posts from a Notion page.
The table on the Notion page has the following columns: Title, Body, Slug, PublishedDate, ReadingTime, Description.
You should generate a slug for each post based on its title if the Slug column is empty.
Make the blog theme black with white text. Keep it extremely minimal.
The posts should be listed on the homepage, and clicking a post should navigate to a page displaying the full post content.

For more tips on writing effective prompts, see our guide on Efficient prompting with Replit AI. You can also show Agent what you mean by providing a URL to scrape for initial styling or content ideas (e.g., your personal portfolio) by adding: Scrape the content of [URL] for initial design inspiration and placeholder text.

Agent will generate a plan. Review it to ensure it aligns with your expectations, then approve it. This is your first checkpoint in the AI-assisted building process.

3

Review the initial preview

Agent will then generate a visual preview. Check if the basic layout and styling are heading in the right direction. Refinements will come later.

​
Step 3: Connect Replit to Notion with Secrets

Agent will likely need your Notion integration details to fetch data.

1

Add Secrets in Replit

Typically, you’ll need:

  1. NOTION_API_KEY: Your Internal Integration Secret from Step 1.
  2. NOTION_DATABASE_ID: The ID of your Notion database.

How to find your Notion Database ID:

  • Open your Notion page with the database in a browser.
  • The URL might be https://www.notion.so/your-workspace/PAGE_TITLE-PAGE_ID?v=DATABASE_VIEW_ID. The PAGE_ID is often the database ID if the database is the page’s main element.
  • More reliably: Click the ••• menu on your database view, select Copy link to view, and paste it. The link https://www.notion.so/your-workspace/DATABASE_ID?v=VIEW_ID contains the DATABASE_ID before ?v=.

Go to the Secrets tool (🔒 icon) in your Replit Workspace. Add these:

  • Key: NOTION_API_KEY, Value: [Your_Notion_Integration_Secret]
  • Key: NOTION_DATABASE_ID, Value: [Your_Notion_Database_ID]

Adding your Notion secrets to Replit

Agent should automatically use these secrets and attempt to connect. The app will likely restart.

​
Step 4: Debugging and refining with Agent

Building with AI is iterative. Expect errors or imperfections. This is where guiding the AI effectively—often called “vibe coding”—is key. For a deeper dive into this skill, check out our tutorial on How to vibe code effectively. Master context by providing only relevant information for each debugging step.

Keep the Console in your Replit Workspace open. It provides valuable error messages and logs.

Debugging your Notion app using the Replit Console

Here are common scenarios and how to address them by debugging methodically:

​
Scenario 1: “Failed to load posts” or property errors

​
Symptom

The app runs but doesn’t display posts. Console errors might mention “Could not find sort property with name ID created_time” or other column mismatches.

​
Cause

Agent might assume column names or properties (e.g., created_time for sorting) that don’t exist or are named differently in your Notion database.

​
Troubleshooting

  1. Verify Notion Database: Ensure column names in your database exactly match Agent’s expectations or your prompt. If Agent seeks created_time and you have PublishedDate, it’s a mismatch.
  2. Prompt Agent with error (Debug principle): Copy the exact console error and select relevant code snippets if you’ve identified them. Provide this focused context to Agent: 
    There's an error fetching posts. Console: "Could not find sort property with name ID created_time".
My Notion database uses 'PublishedDate'. Please use this for sorting/fetching. Here's the suspected code from `services/notion.js`: [code snippet]
  3. Iterate (Experiment principle): If Agent’s fix fails, provide more specifics. “Posts still not loading. Error persists. Show me the code for fetching/sorting Notion posts.” If you added a column like created_time in Notion as a quick fix, you can later ask Agent: “Remove reliance on ‘created_time’, use ‘PublishedDate’ instead.” Remember to use Agent’s Checkpoints to save working states.

​
Scenario 2: Incorrect data display or formatting

​
Symptom

Data appears, but incorrectly (e.g., reading time wrong on homepage but right on post page; Markdown rendering issues).

​
Troubleshooting

  1. Be specific (Specify principle): Describe the issue and location clearly: 
    On the homepage, post reading time is incorrect, but it's correct on individual post pages.
Also, display 'PublishedDate' on the homepage for each post summary.
  2. Markdown issues (Show principle): If Notion “Body” Markdown renders incorrectly (e.g., extra spaces, formatting errors):
    • Inspect raw content in Notion; its formatting can introduce subtle characters.
    • Prompt Agent clearly. You can even show an example: 
      Markdown rendering issue: In post X, bold text like '**this**' appears as ' ** this **' and fails to render. Ensure Markdown parsing handles such cases or trims whitespace. Example of correct rendering for bold: **This is bold**.
    • Testing with known good Markdown (e.g., from ChatGPT pasted into Notion) can isolate if the issue is source data or rendering logic.

​
General debugging flow

  1. Observe: Note the error or incorrect behavior.
  2. High-level prompt (Simplify): Describe the problem to Agent clearly.
  3. Check Console/DevTools (Debug): Look for detailed errors.
  4. Iterate & provide context (Select, Show): If Agent’s fix fails, provide more context (error message, relevant code, your goal, attempts made).
  5. Incremental changes (Checkpoint): Ask Agent to fix one thing at a time. Use Checkpoints in Agent to save progress.
  6. Rollback: If prompts worsen things, roll back to a working Checkpoint and try a new approach.

Don’t hesitate to examine Agent-generated code. Even without expertise in the language, you can often spot logical issues or understand data flow, helping you write better prompts. Files like notionService.js usually handle Notion API calls.

​
Step 5: Further enhancements

Once core functionality works, ask Agent to add features. Use positive, direct language (Instruct principle). Here are ideas:

​
Step 6: Deploy your website

Happy with your site? Time to share it!

  1. Select Deploy in the Replit Workspace (top right).
  2. Review deployment settings (project name, tier). For more details, see About Deployments.
  3. Click Deploy.

Deploying your Notion-powered website

Replit builds, bundles, and deploys your app to a public URL.

​
What you’ve learned

By following this tutorial, you’ve learned to:

  • Set up Notion as a CMS with an integration and structured database
  • Prompt Replit Agent to build a web app connected to Notion, applying principles like planning, specifying, and simplifying
  • Securely manage API keys using Replit Secrets
  • Iteratively debug and refine an AI-generated app using techniques like providing context, showing examples, and using checkpoints
  • Deploy your Notion-powered website on Replit

Building with AI like Replit Agent is collaborative. Procedural thinking, clear instructions, and methodical debugging are crucial for turning ideas into reality, fast.

​
Next steps

Continue developing your Notion-powered website:

Happy building! We can’t wait to see what you create.