如何使用Znai将GitHub现有示例嵌入Markdown文档

首先确认你使用的Znai版本不低于1.60，该功能为原生支持，无需额外拉取仓库到本地做中转。

• 第一步：确认目标文件信息
  你可以直接记录目标文件的三个核心信息：仓库所属账号/组织名、仓库名、引用的固定版本（建议用发布Tag而非main/master这类滚动分支，避免上游文件变动导致文档内容失效）、文件在仓库内的相对路径。如果只需要引用文件片段，提前记好要截取的起止行号即可。
• 第二步：使用Znai专属嵌入语法
  基础嵌入写法直接放在你的Markdown文档对应位置即可：

  :include-github-file: [仓库所有者]/[仓库名], [引用版本/分支名], [文件相对路径]
  {
    "title": "第三方实现示例",
    "startLine": 12,
    "endLine": 47,
    "highlight": [19,24,25]
  }
  

  其中大括号内为可选配置：
  • title：嵌入内容块顶部显示的标题
  • startLine/endLine：仅截取文件指定行范围的内容，无需嵌入整个文件
  • highlight：标记需要高亮突出的行号，方便读者快速定位核心逻辑
    Znai会自动根据嵌入文件的后缀识别代码类型做语法高亮，如果嵌入的是Markdown格式的说明文档，会直接把内容渲染为当前文档的正文部分，不会额外套代码块容器。
• 懒人写法：如果你已经在GitHub网页端打开了目标文件，并且选中了要引用的行段（点行号即可选中，按住shift可选连续行），直接复制浏览器地址栏带行锚点的文件链接，替换掉上面语法里的三个必填参数即可，Znai会自动解析链接里的仓库、版本、文件路径、起止行信息，不用手动拆分参数。

注意：该功能仅支持公开仓库内容嵌入，私有仓库因鉴权限制无法拉取内容；引用时尽量选择固定发布版本的文件，不要引用随时可能变更的滚动分支内容，避免后续文档加载失败或者示例内容和你的API说明不匹配。

内容的提问来源于stack exchange，提问作者Mykola Golubyev