Build a Notion-powered website

Matt Palmer

Head of Developer Relations

​

Build a Notion-powered blog with Replit Agent

• 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

​

Prerequisites

• 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

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

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

Configuring your Notion integration

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

Obtaining your Integration Secret

10. 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

5. 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

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

Adding your integration to the Notion page

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

​

Step 2: Prompt Replit Agent

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.

​

Step 3: Connect Replit to Notion with Secrets

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

Debugging your Notion app using the Replit Console

​

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

​

Symptom

​

Cause

​

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:
   Copy

   Ask AI

   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

​

Troubleshooting

1. Be specific (Specify principle): Describe the issue and location clearly:
   Copy

   Ask AI

   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:
     Copy

     Ask AI

     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.

​

Step 5: Further enhancements

​

Step 6: Deploy your website

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

​

What you’ve learned

• 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

​

Next steps