Hagilight@hagicode/hagilight

@hagicode/hagilight · 独立 Astro 示例

探索 Hagilight core，无需 Starlight。

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

浏览功能

本页中的实时示例

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

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

推广横幅

PromotoBanner 优先展示符合条件的远程推广；没有可用推广时使用本地化后备内容。

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

import PromotoBanner from '@hagicode/hagilight/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 字段。

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

import { buildBreadcrumbStructuredData } from '@hagicode/hagilight/seo-utils';
import { seoSchema } from '@hagicode/hagilight/seo-schema';

const pageSeo = seoSchema.parse({ seo: { title, description } });

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

Favicon

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

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

import { hagilightFavicon } from '@hagicode/hagilight/favicon';
import favicon from '@hagicode/hagilight/favicon.ico';

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

真实构建产物 · 路由由使用方负责

RSS feed

包内 renderer 负责格式化 feed 数据，而 /rss.xml 路由和条目由 Astro 站点维护。

在哪里查看：点击页眉或页脚中的 RSS 链接即可打开生成的 feed。

import { generateRssFeed } from '@hagicode/hagilight/rss';

export const GET: APIRoute = ({ site }) => generateRssFeed({
  site, title, description, language: 'zh-CN', items,
});

可选集成

以下仅为导入示例；本展示页不会加载分析脚本或发送访客数据。

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

Google Analytics 与 51LA

两个组件都需要 ID，并且只会在生产构建中输出第三方跟踪脚本。

在哪里查看：本页没有挂载任一组件，因此构建后的示例不会跟踪访客。

import GoogleAnalytics from '@hagicode/hagilight/GoogleAnalytics';
import Analytics51LA from '@hagicode/hagilight/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} />}

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