share-pretty-gist

分享美观的 Gist

将内容打包并分享为 gists.sh 上精美呈现的 GitHub Gist。

何时使用

当用户想要与他人分享内容，而不只是存储内容时，使用此技能。触发场景包括：

• “将此内容分享为 gist”
• “为这段代码／报告／文档生成一个可分享的链接”
• “将此内容打包好，方便别人阅读”
• “将此内容作为 gist 发给[某人]”
• 任何创建 gist 的请求，重点在于呈现效果和可读性

这与单纯创建 gist（用于存储）不同，因为它侧重于整理内容，使其在 gists.sh 上呈现得更美观。

工作流

步骤 1：准备内容

根据上下文推断用户想要分享的内容。合理安排内容结构：

• 代码：使用正确的文件名和扩展名（例如 server.ts、config.yml、query.sql），以便 Shiki 正确进行语法高亮。如果注释能帮助读者理解上下文，可添加简短的注释标题。
• 报告／文档：使用 .md 文件。通过清晰的标题、项目符号和适当的 GFM 提示框来组织内容。
• 教程／指南：使用 .md 文件。采用编号步骤、带语言标签的代码块，以及 > [!TIP]／> [!NOTE] 提示框来突出说明。
• 快速分享（代码片段、错误日志、配置）：使用最合适的扩展名。保持简洁。

对于包含多个文件的 gist，将最重要的文件放在第一位（它会作为 gists.sh 上默认显示的第一个标签页）。

如果从上下文中可以明确看出要分享的具体文本或 Markdown 内容，请原样或仅做少量格式调整后放入 gist。

切勿在 gist 内容中加入元评论，例如“这是 {user name} 让我分享的内容……”。

步骤 2：创建 gist

gh gist create <files> -d "Clear description of what this contains"

-d 描述会成为 gists.sh 上的标题，因此应清晰且实用。

如果 gh 不可用或未通过身份验证，请指导用户完成安装和设置。

步骤 3：预热缓存

创建 gist 后，访问一次 gists.sh 页面以预热缓存，让页面能立即加载，供读者查看：

curl -s https://gists.sh/{user}/{id} > /dev/null

步骤 4：提供 URL

将 gists.sh 链接作为主要的分享链接展示：

-> https://gists.sh/{user}/{id}

(original on GitHub: https://gist.github.com/{user}/{id})

规则

• 始终创建 SECRET gist。 即使用户要求“分享给某人”或“对外分享”，也必须将 gist 设为 SECRET。只有当用户明确要求创建公开 gist 时，才使用 --public。
• 始终包含 -d，并使用清晰、简洁且具有描述性的标题。这是读者在 gists.sh 上首先看到的内容。
• 使用正确的文件名和扩展名（例如 server.ts、config.yml、Dockerfile），以便正确进行语法高亮。
• 使用自然且具有描述性的文件名。 切勿在文件名前添加多余的词，例如“gist-”或“shared-”（例如，使用 README.md 而不是 gist-readme.md，使用 setup-guide.md 而不是 gist-setup-guide.md）。
• 创建或更新 gist 后，始终预热缓存。
• 尽量避免在内容中使用长破折号，除非原始分享内容中已包含。
• 不要添加元评论（“用户让我……” “以下是摘要……”）。直接呈现内容。
• 为读者撰写内容，而不是为创建者。打开链接的人无需了解原始对话上下文，也应能理解内容。

gists.sh 渲染提示

• 尽量为所有代码块添加语言标签（```typescript、```yaml 等），以正确进行语法高亮。
• 也可以使用 GFM 提示，因为它们的渲染效果很好：> [!NOTE]、> [!TIP]、> [!IMPORTANT]、> [!WARNING]、> [!CAUTION]。
• 除非确有必要，否则避免使用原始 HTML。请使用标准的 GitHub Flavored Markdown。
• 在 gists.sh 上，多文件 gist 会渲染为标签页。默认显示第一个文件。
• 表格、任务列表和其他 GFM 功能均可使用。
• Markdown 文件中的 YAML 前置元数据会以结构化表格的形式显示在内容上方。
• 结构化数据文件会显示交互式查看器：JSON/GeoJSON（可折叠树）、YAML（树形视图）、CSV/TSV（可排序表格）、ICS/iCal（日历卡片）。请使用正确的文件扩展名，以启用查看器。
• 使用 ?file={filename} 链接到多文件 gist 中的特定文件。

更新现有 gist

更新之前分享过的 gist 时：

1. 使用 gh gist edit {id} 编辑 gist
2. 向刷新端点发送 POST 请求，以清除过期缓存。两次清除请求之间有 1 分钟的冷却时间：

   curl -s -X POST https://gists.sh/{user}/{id}/refresh
   

3. 使用更新后的内容预热缓存：

   curl -s https://gists.sh/{user}/{id} > /dev/null
   

显示参数

只有在用户明确要求特定显示样式时才建议使用这些参数。首选不带参数的默认 URL。

• ?theme=dark / ?theme=light —— 强制使用深色或浅色模式
• ?noheader —— 隐藏标题、标签页和复制按钮
• ?nofooter —— 隐藏作者信息和页脚
• ?mono —— 所有文本均使用等宽字体
• ?file={filename} —— 显示多文件 gist 中的特定文件

参数可以组合使用：gists.sh/{user}/{id}?theme=dark&noheader&nofooter