Designing a High-Performance, Reliable System: Integrating Notion, Astro, and Cloudflare's Edge (Workers KV & CDN)

Article HTML...

", article: { title: "...", ... } }。

// Concept for skeleton display const skeletonContainer = document.getElementById('skeleton-loader'); const actualContent = document.getElementById('article-content');

// Inside API fetch .then() or .finally() skeletonContainer.classList.add("hidden"); actualContent.classList.remove("hidden"); actualContent.innerHTML = apiResponse.html;

// Load highlight library only if code blocks are found if (document.querySelector('pre code')) { let highlightPromise = import("highlight.js").then((module) => { window.hljs = module.default; // Exclude mermaid window.hljs.configure({ ignoreUnescapedHTML: true, languages: supportedLanguages, noHighlightRe: /^mermaid$/, }); }); }

).

Special Block Example (Callout):

Represent Notion's callout blocks using HTML divs or similar elements.

// Part of the function to convert Notion blocks to HTML (Conceptual)
function blockToHtml(block: NotionBlock): string {
  let html = '';
  // Convert rich text annotations to HTML
  const richTextHtml = richTextToHtml(block[block.type].rich_text);

  switch (block.type) {
    case 'paragraph':
      html = `<p>${richTextHtml || '&nbsp;'}</p>`; // Add space for empty paragraphs
      break;
    case 'heading_1':
      html = `<h1>${richTextHtml}</h1>`;
      break;
    // ... other heading types ...
    case 'callout':
      const iconHtml = block.callout.icon?.type === 'emoji' // Check icon type
        ? `<span class="callout-icon">${block.callout.icon.emoji}</span>`
        : ''; // Consider other icon types (external, file) if needed
      html = `<div class="callout">${iconHtml}<div class="callout-content">${richTextHtml}</div></div>`;
      break;
    // Handle other block types (bulleted_list_item, numbered_list_item, image, code, etc.)
    // ...
    default:
      console.warn(`Unsupported block type: ${block.type}`);
  }

  // Add logic to recursively process child blocks if block.has_children is true
  if (block.has_children) {
     // Fetch child blocks for this block ID and call blockToHtml recursively...
     // Append the resulting child HTML within the parent element (e.g., inside <li> or <details>)
  }

  return html;
}

// Helper function to convert Notion's rich_text array to HTML
function richTextToHtml(richTextArray: RichTextItemResponse[]): string {
    // Implementation to handle annotations (bold, italic, code, color, links, etc.)
    // Map through richTextArray and wrap content in appropriate HTML tags (<b>, <i>, <a>, <code>, <span style="...">)
    return richTextArray?.map(rt => {
        let content = rt.plain_text;
        if (rt.annotations.bold) content = `<strong>${content}</strong>`;
        if (rt.annotations.italic) content = `<em>${content}</em>`;
        // ... handle other annotations ...
        if (rt.href) content = `<a href="${rt.href}" target="_blank" rel="noopener noreferrer">${content}</a>`;
        return content;
    }).join('') || '';
}

This direct conversion improves processing speed and allows for rich expression closer to the appearance within Notion itself.

Effects and Benefits of Implementation

The introduction of this architecture and caching strategy yielded the following specific improvements and benefits:

Performance Improvement:

Improved Update Reliability:

Improved Developability:

Error Handling:

Improved User Experience (UX):

Conclusion and Future Prospects

This article explained how to build a system for an Astro blog using Notion as a CMS that achieves a high level of balance between the often-conflicting requirements of "display speed" and "update reliability." This was accomplished by leveraging Cloudflare Workers KV and CDN caching as the core, combined with automated update flows and frontend optimizations.

Key Points of the System:

This configuration is applicable not only to Notion but also as a general-purpose approach to improve the performance and reliability of websites/applications using external APIs as data sources.

Future Challenges and Opportunities for Cloudflare Service Integration

目前的架构旨在做到简单、快速且经济高效。然而，随着项目规模的扩大——流量增加和数据结构日益多样化——逐步集成更多 Cloudflare 服务可以显著提升可扩展性、可维护性和性能。

1. 扩展存储层：R2 / D1

2. 高级性能和交付优化

有效的缓存不仅仅是使用正确的工具——它需要深入了解每一层的行为（特别是 Cloudflare 等托管服务的一致性模型和传播机制），以及持续的监控和经验调优。

我希望这篇文章能为面临类似挑战的开发人员提供实用指南和架构参考。