@alphablue/astro-site

v0.3.1

Published

22 days ago

AlphaBlue Astro live-layer integration, static Article and FAQ renderers, and SEO helpers.

Downloads

567

0High
0Medium
0Low

lukesproxy

@alphablue/astro-site

客户 Astro 网站共用的 AlphaBlue integration、Article／FAQ 静态 Renderer 与 SEO helper。套件正式支援 Astro 5、6、7。

客户网站只需直接安装本套件。Content API client 与 Cloudflare edge runtime 分别由 @alphablue/astro-site/content、@alphablue/astro-site/runtime 提供稳定入口；底层 package 仍保持 framework-neutral，但不需要出现在客户网站的 direct dependencies。

import { createContentClient, money, val } from "@alphablue/astro-site/content";

Article Renderer

Renderer 只输出静态 HTML，不依赖 React、不产生 hydration script，也不接受 raw HTML。未知 document version、未知 block 或缺失图片会让 build 明确失败。

---
import ArticleRenderer from "@alphablue/astro-site/articles";
import "@alphablue/astro-site/articles/styles.css";

const article = await fetchArticle(Astro.params.slug!);
---

<ArticleRenderer
  document={article.body.value}
  images={article.images}
  lang={article.body.resolved_locale}
  class="prose"
/>

@alphablue/astro-site/articles 与 @alphablue/astro-site/articles/renderer 是同一个 component 的公开入口。Props：

| Prop | 必填 | 说明 | | ---------- | ---- | ------------------------------------------------------- | | document | 是 | ArticleDocument 或待 migration／validation 的未知输入 | | images | 否 | Record<imageId, ArticleImage>；正文引用图片时必须提供 | | lang | 否 | 输出容器的实际 resolved locale | | class | 否 | 附加到 .ab-article 容器 |

结构 CSS 不负责客户品牌。可在页面或 theme 中覆写：

.ab-article {
  --ab-article-text: #0f1b2e;
  --ab-article-muted: #667085;
  --ab-article-accent: #1f5fd6;
  --ab-article-success: #18794e;
  --ab-article-warning: #8a5d00;
  --ab-article-danger: #b42318;
  --ab-article-highlight-accent: #eaf2fe;
  --ab-article-highlight-success: #e8f5ee;
  --ab-article-highlight-warning: #fff4ce;
  --ab-article-highlight-danger: #feeceb;
  --ab-article-border: #dcd1bc;
}

Article SEO

SEO helper 从同一份公开 Article contract 产生 canonical、hreflang、Open Graph、 BlogPosting JSON-LD、RSS item 与 sitemap entry：

import {
  createArticleFeedItem,
  createArticleSeo,
  createArticleSitemapEntry,
  serializeArticleJsonLd,
} from "@alphablue/astro-site/articles/seo";

const seo = createArticleSeo({
  article,
  canonicalUrl: "https://example.com/articles/store-opening/",
  alternates: [
    { locale: "en", url: "https://example.com/articles/store-opening/" },
    { locale: "th", url: "https://example.com/th/articles/store-opening/" },
  ],
  siteName: "Example Merchant",
  publisherUrl: "https://example.com/",
});

const jsonLd = serializeArticleJsonLd(seo.jsonLd);
const feedItem = createArticleFeedItem(article, seo.canonical);
const sitemapEntry = createArticleSitemapEntry(
  article,
  seo.canonical,
  seo.alternates,
);

serializeArticleJsonLd() 会处理 inline script 所需的字符 escaping；不要用未经处理的 JSON.stringify() 直接写入页面。

FAQ Renderer 与 SEO

FAQ Renderer 使用原生 <details> / <summary> 输出静态 section，不产生 hydration script。question 与 answer 分别带上 Content API 实际解析的语系。以下示例假设客户 repo 依集成指南集中从 src/lib/site.ts 取得 client：

---
import FaqSection from "@alphablue/astro-site/faqs";
import "@alphablue/astro-site/faqs/styles.css";
import {
  faqPageJsonLd,
  serializeFaqJsonLd,
} from "@alphablue/astro-site/faqs/seo";
import { content, publishedBuildOptions } from "../lib/site";

const locale = "en";
const published = await content.content(publishedBuildOptions(locale));
const visibleFaqs = published.faqs;
const faqJsonLd = faqPageJsonLd(visibleFaqs);
---

<FaqSection faqs={visibleFaqs} heading="Frequently asked questions" />
{
  faqJsonLd ? (
    <script
      type="application/ld+json"
      is:inline
      set:html={serializeFaqJsonLd(faqJsonLd)}
    />
  ) : null
}

FaqSection 会忽略 question 或 answer 无法解析的项目；空列表不输出 section。 itemAttributes 可为每个项目附加 Preview Review 或 analytics 的稳定 attributes，Renderer 本身不依赖这些系统。结构 CSS 可用 --ab-faq-* variables 覆写。JSON-LD 应放在页面 <head>，并与实际交给 Renderer 的 array 完全相同；完整 layout、locale、build revision 与验证范例见 Content API 客户网站集成指南。

Live layer integration

// astro.config.mjs
import { defineConfig } from "astro/config";
import alphablue from "@alphablue/astro-site";

export default defineConfig({
  integrations: [alphablue({ siteId: "0195…", liveLayer: true })],
});

| Host | 生成文件 | | --------------- | ---------------------------------------------------- | | pages（默认） | functions/_middleware.js | | workers | worker/index.js；仅在不存在时生成 wrangler.jsonc |

既有 wrangler.jsonc 不会被覆写。旧项目须自行确认 LIVE_STATE KV、SITE_ID var 与 run_worker_first。Cloudflare Pages 的 binding 在项目设置中配置。

| Option | 默认 | 说明 | | ----------- | ------------- | ------------------------------- | | siteId | 必填 | 当前部署所属的 Site | | liveLayer | true | false 时完全不生成边缘入口 | | host | "pages" | "pages" 或 "workers" | | widget | true | 挂载 Portal 控制的浏览器 widget | | widgetSrc | AlphaBlue CDN | 覆写 widget URL |

liveLayer: false 代表纯静态站：没有 Worker invocation、KV read 或额外 request latency；日后开启需要重新 build。

Preview Review

客户网站仓库只在 Preview build 明确启用审阅桥接。deploymentTarget 必须由部署环境提供，不应以 hostname 猜测：

// astro.config.mjs
import { defineConfig } from "astro/config";
import { previewReview } from "@alphablue/astro-site/preview-review";

const isReviewPreview = process.env.AB_DEPLOYMENT_TARGET === "preview";

export default defineConfig({
  integrations: [
    previewReview({
      enabled: isReviewPreview,
      deploymentTarget: isReviewPreview ? "preview" : "production",
      reviewOrigin: process.env.AB_REVIEW_ORIGIN ?? "http://localhost:4324",
      apiOrigin: process.env.AB_API_ORIGIN ?? "http://localhost:8000",
    }),
  ],
});

Operator 或 Customer Portal 产生的短效 code 会通过 URL fragment #ab_review=... 送到 Preview；桥接读取后立即清除 fragment，再由隔离 iframe 载入 Review Panel。普通 Preview URL 不会读取反馈资料。

Production build 若同时设置 enabled: true 会直接失败，避免把审阅 Runtime 误带到正式网站。Review 功能失效时不会阻止网站本身浏览。

对于会长期保留的主要 section 或 interactive element，应提供稳定 id，降低 Layout 调整后的定位漂移：

---
import { reviewAttributes } from "@alphablue/astro-site/preview-review";
---

<section {...reviewAttributes("home.hero")}>
  ...
</section>

未提供 stable id 时，Runtime 会组合 selector、ancestor path、文字 fingerprint 与元素内相对位置；若无法可靠重定位则标记为 drifted，而不是猜测位置后进入 Revision Bundle。

Proposal Primitives

Proposal 页面可以使用独立的静态 primitives 表达观点、流程与阶段演进。这些组件不包含客户文案、品牌决定或未来 VD／V1 成果：

---
import ProposalSection from "@alphablue/astro-site/proposals/section";
import FlowDiagram from "@alphablue/astro-site/proposals/flow";
import BranchingWorkflow from "@alphablue/astro-site/proposals/branching-workflow";
import "@alphablue/astro-site/proposals/styles.css";
---

<ProposalSection title="Make the next decision visible" body="Explain what happens now and what evidence unlocks the next investment.">
  <FlowDiagram slot="visual" label="Example workflow" nodes={nodes} />
</ProposalSection>

FlowDiagram 节点使用 id、title、work 与 goal。页面默认只显示短标题；pointer hover、keyboard focus 或 touch open 后显示工作与目标， print 会展开全部细节。BranchingWorkflow 用于两条或多条资料／工作路径在共同处理环节汇合的场景；节点以通用 details[] key-value rows 呈现 owner、input、work、output、goal、exception 或案例需要的其他短字段，不把任何行业语义冻结进 component schema。LoFiWebsite 只画中性结构示意，必须明确标记为 prototype，不得包装成客户网站截图。

兼容与发布 gate

pnpm --filter @alphablue/astro-site test
pnpm --filter @alphablue/astro-site typecheck
pnpm --filter @alphablue/astro-site build
pnpm --filter @alphablue/astro-site test:astro-matrix
pnpm --dir packages/astro-site pack --pack-destination <temp-dir>

matrix 会以隔离 consumer 对 Astro 5、6、7 分别执行 component import、 astro check 与静态 build。发布前必须先发布 @alphablue/content-model 与 @alphablue/site-runtime，再检查 tarball 的 manifest 已把 workspace: dependency 改成正式版本。

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@alphablue/astro-site

Article Renderer

Article SEO

FAQ Renderer 与 SEO

Live layer integration

Preview Review

Proposal Primitives

兼容与发布 gate

License