Notion as a CMS

This is the first page on my site written entirely in Notion!

The Magic Behind the Scenes

I’ve been thinking a lot about how to make writing and publishing more seamless. If you’ve read my note on crafting a mobile writing system, you know I’ve been exploring ways to reduce friction in my note taking process.

After weighing different options, I’ve implemented what might be the perfect solution: a Notion-to-Hugo static site publishing pipeline that combines the intuitive writing experience of Notion with the fun of designing my website to be truly my own.

Here’s how it works:

1. Authoring in Notion: I write and organize all my content in a Notion database, taking advantage of its rich editing features and collaboration tools. This solves my “Option Three” scenario - I can write now and polish later, all within Notion’s pleasant mobile interface.
2. Webhook Triggers: When I publish or update a page in my Notion database, it triggers a webhook - no manual intervention needed.
3. Content Transformation: The webhook initiates a process that fetches the Notion page content and converts it to clean markdown format, preserving all the formatting, links, and structure.
4. Git Integration: The generated markdown file is automatically committed to my Git repository. This completely eliminates the need to use GitHub’s mobile app, which I found “very clunky” for content creation.
5. Automated Deployment: The commit to the repository triggers my CI/CD pipeline, which builds the Hugo site with the new content and deploys it to my hosting provider.

Under the Hood: The Technical Implementation

For the technically curious, here’s what’s happening behind the scenes. I built a Node.js Express server that handles the entire pipeline:

// Notion webhook endpoint
app.post(
  '/api/notion-webhook',
  verifyNotionSignature,
  extractNotionPageId,
  convertNotionToMarkdown,
  commitToGitHub,
  (req: NotionRequest, res) => {
    // Send success response
    res.status(200).json({
      status: 'success',
      message: 'Notion page processed successfully',
      data: {
        pageId: req.notionPageId,
        filename: req.markdownContent?.filename
      }
    })
  }
)

The flow follows these steps:

1. Security First: The verifyNotionSignature middleware validates that the request is actually coming from Notion by checking the cryptographic signature in the request headers. This prevents anyone from spoofing content to my site.
2. Content Identification: The extractNotionPageId middleware parses the webhook payload to determine which page was updated. It handles different Notion event types (page created, updated, etc.) and extracts the relevant page ID.
3. Markdown Conversion: The convertNotionToMarkdown middleware is where the real magic happens. It:
   • Calls the Notion API to fetch the complete page content
   • Processes all blocks (headings, paragraphs, lists, code blocks, etc.)
   • Converts them to clean, properly formatted markdown
   • Handles images, links, and other rich content
   • Preserves the document structure
4. Git Integration: The commitToGitHub middleware takes the generated markdown and:
   • Creates or updates the appropriate file in my GitHub repository
   • Adds metadata like publication date and categories
   • Commits the changes with a descriptive message
   • Pushes to the main branch
5. Deployment Trigger: Once the commit is pushed, my existing GitHub Actions workflow detects the change and automatically builds and deploys the Hugo site.

The entire process takes just seconds from hitting “Publish” in Notion to seeing the content live on my site. No manual steps, no context switching, no friction.

Why This Matters

This workflow represents the best of both worlds: the user-friendly interface of Notion for content creation and the lightning-fast performance of Hugo for site delivery. It’s exactly what I was looking for - a way to “capture these thoughts in a way that works with my life rather than against it.”

The beauty of this system is that it works whether I’m at my computer or on the go with just my phone. No more context-switching between different tools or manually copying content from one platform to another.

By automating this process, I’ve reduced friction in my publishing workflow, allowing me to focus on what matters most—creating valuable content. It’s a solution that “works with my life rather than against it.”