Astro 통합 가이드

Astro의 기본 제로 JavaScript 정적 및 하이브리드 렌더링 아키텍처는 고성능 브랜드 사이트와 블로그를 구축하는 데 완벽합니다. Kanorio Content Delivery API를 사용하면 단 몇 줄의 코드로 .astro 컴포넌트 상단에서 게시된 모든 컬렉션과 기사를 직접 가져올 수 있습니다.

1. 환경 변수 설정

Astro 프로젝트의 .env 파일에 Kanorio 사이트의 영구 시스템 URL을 추가합니다:

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

---

2. 프로젝트 또는 서비스 컬렉션 가져오기 (src/pages/projects.astro)

.astro 파일의 Frontmatter 블록에서 /api/v1/collections/{key}/items를 직접 호출하고, 최상위 assets 맵을 사용하여 이미지 URL을 검색합니다:

---
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를 호출한 다음, 제출 시 /api/v1/forms/{formId}/submit으로 POST 요청을 보냅니다(전체 단계는 참조). 대시보드의 에 있는 "허용된 출처(Allowed Origins)" 목록에 프로덕션 도메인을 추가하는 것을 잊지 마십시오.
2. 콘텐츠 게시 시 자동 업데이트:
   • SSR 모드 (@astrojs/cloudflare 또는 @astrojs/node): x-kanorio-public-version 및 X-Kanorio-Cache-Tags 헤더를 전달하거나 비교할 수 있습니다.
   • SSG 정적 빌드 모드: Vercel 또는 Cloudflare Pages에서 배포 후크 URL을 생성하고 Kanorio 대시보드의 에 추가합니다. collections.item.published, collections.item.unpublished, collections.item.deleted, collections.items.bulkChanged를 구독하여 콘텐츠가 게시되거나 업데이트될 때마다 자동으로 재배포를 트리거할 수 있습니다.

관련 문서