仓库静态落地页 是做什么的?
生成一个静态登陆页面 (docs/index.html + docs/style.css + docs/main.js),其内容来源于托管它的仓库。永远不要列出仓库中实际不存在的功能、供应商或命令。
内容的真实来源
在编写任何内容之前,请阅读以下内容:
README.*— 概览、功能、技术栈、安装/快速启动命令LICENSE*— 许可证名称、版本、URLCHANGELOG.*— 变更历史摘要package.json,composer.json,requirements.txt等:名称、描述、依赖项(技术栈徽章的基础)AGENTS.md,CLAUDE.md,config.toml,GEMINI.md等:项目的用途,以及(如果项目有)支持的供应商/设置表格- 现有的
docs/index.html(如果存在):除非明确要求重新设计,否则重用其章节结构并就地编辑内容,而不是从头重建
必需元素
-
亮/暗主题 — 使用
prefers-color-scheme: dark媒体查询覆盖 CSS 自定义属性(--bg,--text,--accent等)。除非要求添加,否则不要添加 JS 主题切换开关。 -
OGP + Twitter/X 卡片 —
og:title,og:description,og:url,og:image,og:type,og:site_name,twitter:card,twitter:title,twitter:description,twitter:image。将og:image/twitter:image指向仓库中实际存在的资源(例如social-preview.png)。如果不存在,先用make-social-preview技能生成一个。 -
JSON-LD 架构 — 一个
<script type="application/ld+json">块(如果是应用/工具,使用SoftwareApplication;否则使用适合项目的任何@type)。保持与 OGP 描述一致。 -
Favicon — 使用
<link rel="icon">引用一个适合项目的 Twemoji SVG。 -
通过
multilanguagejs支持多语言(CDN,无需构建步骤):<script src="https://unpkg.com/[email protected]/dist/multilanguagejs.umd.cjs"></script>将要翻译的每个元素包裹在
<template type="language-group">中,并在其内部为每种语言放置一个子元素,每个子元素带有language="xx"属性(而不是lang):<h2> <template type="language-group"> <span language="en">Features</span> <span language="ja">機能</span> </template> </h2>每个
template[type=language-group]必须包含每种支持的语言的恰好一个元素 —multilanguagejs每个模板只取第一个匹配的[language=X],因此重复会导致内容丢失。在
main.js中初始化:var ml = new MultilanguageJS({ languages: [...], defaultLanguage: "en" }); ml.setLanguage(lang); // 加载时以及 <select> 切换器的 change 事件时<title>和<meta name="description">不在[language]模板的范围内(该库只更新匹配元素的textContent,而<meta>标签的翻译在其content属性中,而不是文本中)。在main.js中为每种语言提供一个小的{ title, description }字典,并在ml.setLanguage()的同时手动更新这两个标签。从
navigator.language检测访问者的语言,将所选语言保存在localStorage中,并在加载时在回退到浏览器检测之前重新应用它。必需的语言集合(总是,无论应用本身支持什么): 英语 (
en)、日语 (ja)、中文 (zh)、西班牙语 (es)、俄语 (ru)、德语 (de) — 至少 6 种语言。即使src/locales/*.json或应用自己的i18n.ts/i18n.js只覆盖其中一部分(例如,即使是一个只有en/ja的应用,也要让登陆页面支持 6 种语言)。如果要求,你可以在这 6 种语言之外添加其他语言。 -
复制到剪贴板按钮 — 为每个在
<code>块中显示的安装/运行命令提供一个带有内联 SVG 图标的复制按钮(绝不使用表情符号),通过navigator.clipboard.writeText()实现复选标记确认状态。为了保持一致布局,将<code>和其按钮包裹在一个.code-rowflex 容器中。 -
响应式 — 移动优先。不要在窄视口上引起水平滚动,除非在明确设计为滚动的容器内(例如,一个宽的对比表格)。
-
无构建步骤 — 使页面只需打开 HTML 文件或按原样提供静态文件夹即可工作,无论应用本身使用哪个打包工具(Vite 等)。保持
main.js为可读源码。直接在页面中使用<script src="main.js">加载它。 -
语义结构 — 语义化地组织这些结构:英雄区(标题、引导文本、行动号召、主要运行命令)、截图(如果存在,重用仓库/GitHub 资源 URL)、功能网格、快速启动/安装命令、技术栈徽章、页脚。
-
重用现有 CSS — 重用仓库
docs/style.css中已有的 CSS 自定义属性和类名,而不是创建并行、独立的样式系统。 -
尊重设计系统 — 尊重现有 AI 代理运行时环境中的设计系统。添加新 CSS 时,重用现有的自定义属性和类名,并遵循与仓库设计系统一致的命名约定、设计、布局以及语气和风格。
工作流程
- 阅读上述内容来源。
- 如果
docs/不存在,创建它。 - 如果
docs/index.html已经存在,就地编辑它 — 除非明确要求重新设计,否则不要整体替换;保留章节结构并更新内容。 - 语义化地组织章节:英雄区(标题、引导文本、行动号召、主要运行命令)、截图(如果存在,重用仓库/GitHub 资源 URL)、功能网格、比较/设置表格(如果项目有多个值得比较的供应商/模式/后端)、快速启动/安装命令、技术栈徽章、页脚。
- 重用仓库
docs/style.css中已有的 CSS 自定义属性和类名,而不是创建并行、独立的样式系统。 - 更新
docs/main.js。 - 在完成前验证:没有表情符号用于交互式图标(仅限 SVG);每个
template[type=language-group]恰好有一个每种支持语言的子元素,没有重复或遗漏;OGP/JSON-LD 指向仓库中实际存在的文件/URL。