Hagilight@hagicode/hagilight

@hagicode/hagilight · 独立 Astro 示例

探索 Hagilight core，无需 Starlight。

通过独立的 Astro 双语示例，了解 @hagicode/hagilight 提供的共享组件和构建集成。

浏览功能

本页中的实时示例

以下展示的是实际加载的包组件，而不是仿制的静态界面。

可选页面 · 内置样式和动画

根路径中转页

根路径通过 @hagicode/hagilight-core/RootTransit 展示中转动画，然后进入英文页面。组件包含默认样式、路由光束、静态继续链接和自动导航；转场时还会随机显示一张 img-gen 启动图（@hagicode/hagilight-core/splash-images 提供图片路径，splash={false} 可关闭）。出发看板按页面语言滚过 HagiCode 生态站点，并停在当前站点（@hagicode/hagilight-core/root-transit-board 生成各行，board={false} 可隐藏）。@hagicode/hagilight-core/root-transit 提供经过测试的 URL 和生命周期辅助函数。

在哪里查看：访问根路径查看中转效果，也可以立即点击继续链接；中文深层链接仍直接打开本页。

import RootTransit from '@hagicode/hagilight-core/RootTransit';

<RootTransit destination="/en-US/" siteName="Hagilight" />

页脚内实时呈现 · 构建时解析

构建信息

页脚末尾显示分支、提交和构建时间。@hagicode/hagilight-core/build-info 在浏览器中格式化这些信息，@hagicode/hagilight-core/build-info-resolver 在构建时读取 Git 以及 HAGILIGHT_BUILD_BRANCH、HAGILIGHT_BUILD_COMMIT 覆盖值。

在哪里查看：页脚版权行显示本示例的分支、七位提交号以及 UTC 构建时间。

import { buildInfoItems } from '@hagicode/hagilight-core/build-info';
import { resolveBuildInfo } from '@hagicode/hagilight-core/build-info-resolver';

const items = buildInfoItems(resolveBuildInfo({ root: process.cwd() }));

构建产物 · schema 版本 1

站点元数据文件

构建会写入 .well-known/hagilight.metadata.json，包含站点标识、语言、构建信息、发现文件以及分析工具开关。@hagicode/hagilight-core/site-metadata 定义契约，@hagicode/hagilight-core/site-metadata-writer 在 Node 中写入文件，@hagicode/hagilight-core/site-metadata-ownership 决定由哪个集成写入。

在哪里查看：本演示构建包含 .well-known/hagilight.metadata.json，其 discovery 字段列出了构建实际生成的 llms.txt 和站点地图。

import { buildSiteMetadata, serializeSiteMetadata } from '@hagicode/hagilight-core/site-metadata';

const json = serializeSiteMetadata(buildSiteMetadata({ generator, site, build, discovery, analytics }));

实时组件 · 远程推广为可选

推广横幅

PromotoBanner 优先展示符合条件的远程推广；没有可用推广时使用本地化后备内容。@hagicode/hagilight-core/promotions 提供带类型的推广加载器，@hagicode/hagilight-core/promoto-banner 提供与框架无关的自定义元素，Docusaurus 包会挂载它；@hagicode/hagilight-core/promoto-analytics 把展示、关闭和翻页上报给 PostHog。

在哪里查看：本页挂载了该组件；后备按钮会跳转到页脚，组件进入页脚区域时会隐藏。

import PromotoBanner from '@hagicode/hagilight-core/PromotoBanner';

<PromotoBanner locale="zh-CN" fallback={fallbackCard} />

页面 head 与构建产物

这些集成会生成元数据、浏览器图标或 feed，不会额外显示成页面组件。

真实文档 head

SEO head

SEOHead 为当前路由生成 canonical 地址，以及 Open Graph 和 Twitter 标题、描述元数据。

在哪里查看：检查本页文档 head 或查看源代码中的 canonical 和分享字段。

import SEOHead from '@hagicode/hagilight/SEOHead';

const site = Astro.site.href;
const pageUrl = new URL(Astro.url.pathname, site).href;

<SEOHead
  site={site}
  page={{ url: pageUrl, title, description }}
  structuredData={pageStructuredData}
/>

构建时工具

SEO 工具与 schema

工具函数可构造安全的 canonical 和 JSON-LD 数据；seoSchema 用于校验可选 frontmatter 字段；classifyOgImage 判断预览图格式是否可被爬虫读取。

在哪里查看：本页 head 中的 JSON-LD 脚本只包含示例站点和页面事实。

import { buildBreadcrumbStructuredData } from '@hagicode/hagilight-core/seo';
import { seoSchema } from '@hagicode/hagilight-core/seo-schema';
import { classifyOgImage } from '@hagicode/hagilight-core/og-image';

const pageSeo = seoSchema.parse({ seo: { title, description } });
const imageFormat = classifyOgImage('/social/card.avif'); // 'convertible'

构建时工具

实体定义

getEntityDefinition 返回定义产品的那一句共享文案，按所选语言返回，缺失时回退到 en-US。buildSoftwareApplicationStructuredData 把产品事实转换为 SoftwareApplication JSON-LD。

在哪里查看：该定义是页面导语、llms.txt 摘要和 SoftwareApplication 描述的唯一来源。

import { getEntityDefinition } from '@hagicode/hagilight-core/entity-definition';
import { buildSoftwareApplicationStructuredData } from '@hagicode/hagilight-core/seo';

const definition = getEntityDefinition(Astro.currentLocale); // 缺失时回退到 en-US
const app = buildSoftwareApplicationStructuredData({
  name: 'Example App',
  applicationCategory: 'DeveloperApplication',
  operatingSystem: 'Linux',
  description: definition,
});

浏览器标签页可见 · 构建集成

Favicon

Astro 集成会加入内置 favicon；包也导出 favicon.ico 静态资源，可复制到站点目录。

在哪里查看：查看浏览器标签页图标；集成会将 data URI 注入生成页面的 head。

import { hagilightFavicon } from '@hagicode/hagilight/integration';
import { resolveFaviconHeadEntry } from '@hagicode/hagilight-core/favicon';
import favicon from '@hagicode/hagilight-core/favicon.ico';

integrations: [hagilightFavicon()]
<link rel="icon" href={favicon} type="image/x-icon" />

真实构建产物 · 多语言集成

RSS feed

集成根据站点提供的 feed 数据生成多语言路由；使用方仍可用 core 的 RSS renderer 自行维护路由，@hagicode/hagilight-core/rss-ownership 让同一项目中的 Starlight 插件接管路由。

在哪里查看：点击页眉或页脚中的 RSS 链接即可打开英文或当前语言 feed。

import { hagilight, type RssFeedCallback } from '@hagicode/hagilight/integration';

integrations: [hagilight({ rss: { getFeed: './src/rss-feed.ts' } })]

正文内容

Markdown 图片在站点构建时统一处理，页面不会为它们添加运行时脚本。

构建时 Markdown 插件 · 使用 hagilight() 时自动启用

正文图片

位于 picture 元素之外的 Markdown 与 MDX 正文图片会获得惰性与异步加载的默认值，以及 hagilight-content-image 类名；作者已设置的 loading 与 decoding 值会保留。

在哪里查看：下方示例来自一个 Markdown 文件，包含相对路径本地图片和站点根路径图片；它们的 img 元素都带有标记类名。

import { rehypeContentImages } from '@hagicode/hagilight-core/content-images';

// 使用 hagilight() 时自动启用；如需关闭，请传入 hagilight({ contentImages: false })

共享数据

打包在包内的数据与契约，其他站点无需保留自己的副本即可读取。

打包数据 · 浏览器安全契约、Node 加载器与原始 JSON

对比文章数据

对比文章随包一同发布。@hagicode/hagilight-core/comparison-articles 提供浏览器安全的契约，@hagicode/hagilight-core/comparison-articles-source 在 Node 中读取打包文件，@hagicode/hagilight-core/comparison-articles-data/*.json 则可把单篇文章作为原始 JSON 导入。

在哪里查看：本页不渲染这些数据；下方示例展示使用方如何读取它们。

import { buildStructuredArticleRootManifest } from '@hagicode/hagilight-core/comparison-articles-source';
import { validateStructuredArticleDetail } from '@hagicode/hagilight-core/comparison-articles';
import claude from '@hagicode/hagilight-core/comparison-articles-data/en-US/claude-vs-hagicode.json' with { type: 'json' };

const manifest = await buildStructuredArticleRootManifest();
const article = validateStructuredArticleDetail(claude);

可选集成

本展示页在生产环境启用 PostHog；Google Analytics 与 51LA 保留为可选导入示例。

可选 · 仅生产环境加载脚本

PostHog、Google Analytics 与 51LA

hagilight() 集成会自动注入 PostHog，使用内置项目 key，无需传参；Google Analytics 与 51LA 需要 ID。三个组件都只在生产构建中输出第三方跟踪脚本。GoogleAnalytics 还会把已标记链接的点击作为 link_click 或 download_click 事件上报；@hagicode/hagilight-core/analytics-events 提供带类型的标记构造函数。@hagicode/hagilight-core/posthog-events 包含封闭的 PostHog 事件词表、属性清洗器与 cta_click 上报函数。@hagicode/hagilight-core/posthog-interactions 安装针对 Pagefind 搜索、代码复制按钮和推广曝光的委托观察器；它们只读取 DOM，从不抛出异常。

在哪里查看：PostHog 由集成注入每个页面的 head 一次，生产环境访问会向 HagiCode 的共享项目发送活动数据。

// astro.config.mjs: hagilight() injects PostHog into every production head.
hagilight({ analytics: { posthog: { enabled: false } } }); // opt out

// Custom head only: render the shared component once when the integration is not the owner.
import PostHog from '@hagicode/hagilight-core/PostHog';
import { posthogInitScript } from '@hagicode/hagilight-core/posthog';

<PostHog />

import GoogleAnalytics from '@hagicode/hagilight-core/GoogleAnalytics';
import Analytics51LA from '@hagicode/hagilight-core/Analytics51LA';

{import.meta.env.PUBLIC_GA_ID && <GoogleAnalytics measurementId={import.meta.env.PUBLIC_GA_ID} />}
{import.meta.env.PUBLIC_51LA_SITE_ID && <Analytics51LA siteId={import.meta.env.PUBLIC_51LA_SITE_ID} />}

import { gaEventAttributes } from '@hagicode/hagilight-core/analytics-events';

<a href="/download" {...gaEventAttributes({ category: 'download', label: 'customDownload', location: 'footer' })}>Download</a>

Markdown 正文图片

本 Markdown 文件中的正文图片会由 hagilight() 在构建时统一处理，不会添加任何运行时脚本。

青绿到青柠色渐变背景上带有一个奶油色圆形的相对路径本地图片

存放在源码 assets 目录中并由页面导入的暖色渐变图片

位于 <picture> 元素之外的图片会获得 loading="lazy"、decoding="async" 和 hagilight-content-image 类名。作者已经设置的值会保留。如需在整个站点关闭此处理，请给 hagilight() 传入 contentImages: false。

推广示例：符合条件的远程推广可能替代此本地后备内容。后备链接会跳转到页脚，以演示组件的可见性行为。