Astro 整合指南

Astro 預設零 JavaScript 的靜態與混合渲染架構，非常適合用來打造極速的品牌形象網站與網誌。搭配 Kanorio 的 Content Delivery API，您可以在 .astro 元件頂部直接用幾行 fetch 讀取所有已發佈的集合與文章。

1. 設定環境變數

在 Astro 專案的 .env 加入您的 Kanorio 網站永久系統網址：

PUBLIC_KANORIO_SITE_URL="https://s-k4m9x2p7q8w3.kanorio.com"

---

2. 讀取作品案例或服務集合（src/pages/projects.astro）

在 .astro 檔案的 Frontmatter 區塊直接呼叫 /api/v1/collections/{key}/items，並透過頂層 assets 對照表取得圖片網址：

---
const SITE_URL = import.meta.env.PUBLIC_KANORIO_SITE_URL;
const res = await fetch(`${SITE_URL}/api/v1/collections/projects/items?sort=-publishedAt&limit=20`);
const { items, assets } = await res.json();
---

<section>
  <h1>作品案例</h1>
  <div class="grid">
    {items.map((item) => {
      const cover = assets[item.fieldData.cover];
      return (
        <article>
          {cover && (
            <img
              src={cover.url}
              alt={cover.alt ?? item.fieldData.title}
              width={cover.width ?? undefined}
              height={cover.height ?? undefined}
              loading="lazy"
            />
          )}
          <h2>{item.fieldData.title}</h2>
          <p>{item.fieldData.summary}</p>
        </article>
      );
    })}
  </div>
</section>

---

3. 建立網誌文章列表與內頁（src/pages/blog/[slug].astro）

讀取 blog 系統集合時加上 formats=html 與 expand=authors,categories，就能直接把 item.contentHtml 交給 Astro 的 set:html 渲染，並用 item.toc 產生文章目錄：

---
const SITE_URL = import.meta.env.PUBLIC_KANORIO_SITE_URL;

export async function getStaticPaths() {
  const siteUrl = import.meta.env.PUBLIC_KANORIO_SITE_URL;
  const res = await fetch(`${siteUrl}/api/v1/collections/blog/items?fields=title&limit=100`);
  const { items } = await res.json();
  return items.map((post) => ({ params: { slug: post.slug } }));
}

const { slug } = Astro.params;
const res = await fetch(
  `${SITE_URL}/api/v1/collections/blog/items/${encodeURIComponent(slug!)}?expand=authors,categories,tags&formats=html`
);
if (!res.ok) return Astro.redirect("/404");
const { item, assets } = await res.json();
const coverId = (item.fieldData.cover_image ?? "").replace(/^asset:/, "");
const cover = assets[coverId];
---

<article>
  <h1>{item.fieldData.title}</h1>
  {cover && <img src={cover.url} alt={cover.alt ?? item.fieldData.title} />}

  {item.toc?.length > 0 && (
    <nav aria-label="文章目錄">
      <ul>
        {item.toc.map((h) => (
          <li data-level={h.level}>
            <a href={`#${h.id}`}>{h.label}</a>
          </li>
        ))}
      </ul>
    </nav>
  )}

  <div class="prose" set:html={item.contentHtml} />
</article>

---

4. 串接聯絡表單與自動更新

1. 聯絡我們表單： 在您的聯絡頁面掛載表單時，先從瀏覽器呼叫 GET ${PUBLIC_KANORIO_SITE_URL}/api/v1/forms/{formId}/challenge，送出時再 POST 到 /api/v1/forms/{formId}/submit（完整步驟見）。記得將您的正式網域加進後台「網站設定 › 開發者」的「允許的來源」。
2. 內容發佈時自動更新：
   • SSR 模式（@astrojs/cloudflare 或 @astrojs/node）：可直接透傳或比對回應的 x-kanorio-public-version 與 X-Kanorio-Cache-Tags。
   • SSG 靜態建置模式：在 Vercel 或 Cloudflare Pages 建立一條 Deploy Hook 網址，貼到 Kanorio 後台「網站設定 › Webhooks」並訂閱 collections.item.published、collections.item.unpublished、collections.item.deleted 與 collections.items.bulkChanged，每次發佈文章或更新集合就會自動觸發重新部署。

相關文件