Itsy-Gitsy

Git仓库的静态网站生成器。

是什么

Itsy-Gitsy遍历一组Git仓库，将其中一部分内容通过用户定义的输入模板进行处理，并生成一系列输出文件。在标准用法中，输入模板描述网站布局，输出是一个适合本地浏览或托管在Web服务器上的静态网站。

在这里查看演示。

由于输出是静态文本文件，Itsy-Gitsy不仅可以生成网站。通过自定义模板，它可以将Git仓库渲染为纯文本、CSV、LaTeX、org-mode、Markdown、TOML或任何您希望的格式。

更通用地说，Itsy-Gitsy是一个根据描述性模板从Git仓库生成基于文本的文档树的实用工具。

为什么

主要动机是用于托管简单的Git仓库前端而无需动态Web应用程序。对于自托管用户，不希望动态生成内容可能有多种动机：尤其是对Web服务器的系统资源、安全或维护要求。大多数现有的Git仓库前端都是动态的“锻造”或“枢纽”，即使是轻量级的也是大型、复杂的应用程序，具有显著的资源需求和大的攻击面。

附带的好处包括无网络本地浏览，以及生成非网站内容。例如，Itsy-Gitsy也适合生成Gopher或Gemini站点，甚至电子邮件通讯。

它用Rust编写，编译成一个单一的本地可执行文件，这使得在开发环境中（跨）编译并在资源有限的服务器上运行成为可能，而依赖项很少。

如何

行为由单个TOML配置文件决定，该文件指定要解析的Git仓库以及各种全局和每个仓库的设置。Itsy-Gitsy具有高度的配置性，允许输出格式具有很大的灵活性。

Itsy-Gitsy使用git2，它反过来又使用libgit2，将本地Git仓库列表解析为内部表示。也可以指定通过非认证HTTPS连接可用的远程仓库，在这种情况下，它们首先在本地克隆。

仓库的内部表示通过一组可配置的模板传递，这些模板使用基于Jijna2模板语言的Tera模板引擎。模板替换后，生成的文档将写入用户可配置的文件路径。

如果提供了文件内容模板，还可以渲染存储在仓库中的文件内容。这些内容可以选择使用pulldown-cmark从Markdown渲染成HTML，并且可以选择使用syntect将其渲染为语法高亮的HTML。

Itsy-Gitsy目前仅支持为每个仓库索引单个分支。要索引的分支是可以配置的。

项目状态

Itsy-Gitsy尚处于早期和实验阶段。它尚未经过充分测试，可能缺少一些重要功能。Git支持极多的组合，而Itsy-Gitsy只测试了其中的一小部分。

模板"API"不稳定，不应期望在1.0版本之前稳定。

欢迎提供反馈、错误报告和功能请求。

功能

• 从Git仓库生成静态、模板化的多页输出
• 索引任意数量的Git仓库
  • 本地目录（裸或完整）
  • 远程仓库（仅未认证的HTTPS）
• 可配置名称、路径、分支、描述、网站等。
• 全局和每个仓库设置
• 支持多个模板
  • 所有仓库列表
  • 每个仓库的摘要
  • 历史提交、分支、标签列表
  • 每个提交、每个标签、每个分支
  • 每个文件，带有内容
    • 可选的Markdown渲染
    • 可选的语法高亮
  • 错误页面
• 可配置的输出
  • 可配置的文件名，带有变量替换
  • 可配置的目录结构
  • 无限的模板到输出的映射
• 分页输出
• 可配置的RAM和磁盘空间使用限制
• 全局和每个仓库的资产文件
• 基本的"永久链接"支持

入门指南

您可以通过使用默认配置来渲染和打开远程仓库的本地可浏览副本来快速尝试Itsy-Gitsy。

$ git clone https://github.com/mrmekon/itsy-gitsy
$ cd itsy-gitsy
$ cargo build --release
$ ./target/release/itsy-gitsy --clean --local --open --repo "https://github.com/mrmekon/itsy-gitsy"

接下来，您需要编辑config.toml，并指向您想索引的Git仓库。默认配置文件（config.toml）包含帮助您开始的文档。

现在您可以使用以下命令在本地重新生成并查看您的仓库：

$ ./target/release/itsy-gitsy --clean --local --open

当您准备好将网站移动到Web服务器时，可以使用以下命令重新生成：

$ ./target/release/itsy-gitsy --clean

命令行参数

配置

Itsy-Gitsy 通过单个 TOML 配置文件进行配置。默认情况下，它会在工作目录中查找名为 config.toml 的文件，但您可以使用 --config 命令行选项将其指向另一个文件。

请参阅包含的 config.toml 文件，以获取可用设置的完整文档。

文件的顶部包含全局、网站范围的设置，如网站名称、描述、基本 URL、分页规则和内存限制。在这里，您还可以指定包含 Git 仓库的子目录，这用于大量导入多个仓库。

接下来应该是 [gitsy_outputs] 部分，它定义了要使用哪些输入模板以及要输出哪些文件。未指定的输入模板将不会生成，因此您可以禁用不需要的任何输出类型。模板可以按需使用，生成任意数量的输出。

输出文件名中可以使用一些特殊变量

可以使用可选的 [gitsy_extra] 部分，为所有模板提供全局、用户定义的键/值对。如果要在模板中使用自定义的网站范围变量，请使用此选项。

最后，可以有零个或多个具有任意名称的节，用于定义要索引的个别 Git 仓库。在这里，您可以在每个仓库级别上覆盖大多数全局设置。这更强大，并允许指定比批量导入更多的元数据。

模板

模板使用 Tera 模板引擎定义。Tera 是一种功能强大的模板语言，它允许使用变量、条件、循环、过滤、包含、分层继承等。有关详细信息，请参阅其官方文档。

Itsy-Gitsy 有一个预定义的已知模板类型集，旨在设计用于多页静态 Git 浏览器。提供了一个默认模板集，演示了生成完整的多页 Git 仓库浏览器的过程。强烈鼓励您编写自己的模板，或修改提供的模板以满足您的需求。

模板绝对不需要用于它们的“预期”用途。修改它们的意义以适应您的需求！例如，您可以忽略repo_list的预期意义，而是使用该模板生成包含所有索引仓库最新10个提交消息的电子邮件通讯稿。

配置文件中未指定的任何模板都不会被评估，并且不会生成它们的匹配输出文件。使用此功能可以禁用网站不需要的任何功能。

过滤器

Tera模板支持自定义函数和过滤器，Itsy-Gitsy定义了一些方便的过滤器。

url_string可以与%PATH%和%REF%文件名变量一起使用。两者都使用一种非常原始的“slugifying”形式将字符串转换为可以在URL中使用的格式。这允许基本的永久链接。

安全性

安全性主要是外包给Itsy-Gitsy依赖的库。 git2处理Git仓库访问的安全性， Tera和模板文件本身处理清理HTML输出， pulldown-cmark处理清理Markdown输出， syntect处理清理语法高亮文件内容。如果这些库中的任何一个包含安全问题，那么Itsy-Gitsy也存在安全问题。

Itsy-Gitsy自己负责的主要事情是确保它只将其输出目录写入文件。它有一些基本的保护措施，以防止明显尝试写入输出子目录之外，但没有不可战胜的保护。

就像以前一样，如果安全性是关注的重点，最佳做法是遵循最小权限原则。在具有只读或无上游访问权限的Git仓库上以专用、低权限用户账户运行Itsy-Gitsy。为了最大程度地避免担忧，请禁用语法高亮和Markdown渲染，并使用文件系统命名空间将其限制为对Git仓库的只读访问和对输出目录的读写访问。

性能

高性能不是Itsy-Gitsy的主要目标，因为它主要用于索引小型个人项目，但它提供了各种设置，以便它可以处理大型仓库。大多数操作都利用了并行性。默认情况下，Itsy-Gitsy将任务分配给所有核心，但在配置文件中可以减少并行线程的数量。

语法高亮默认使用syntect的纯Rust实现，以避免额外的依赖。这种实现相当慢，可以通过使用syntect的onig模式来大大提高性能，该模式使用更快的Oniguruma C库进行高亮。这可以在构建时通过以下命令启用：cargo build --features highlight_fast。

所有仓库的元数据（除了文件内容）都存储在内存中。大型仓库很容易耗尽内存，磁盘使用量也可能相当高。配置中提供了几个limit_*设置，用于限制存储在内存中的数据量，但这会减少生成输出中的数据量。对于有数千个提交的仓库，limit_context和limit_diffs是非常重要的限制设置。

具有几十到几百个提交的小型仓库可以在几秒钟内生成。大型仓库需要相当长的时间和大量的RAM，但可以在配置中积极应用限制以帮助；解析Linux内核仓库中的1,115,000个提交（禁用语法高亮），limit_commit_ids_to_related = true，limit_tree_depth = 3，limit_context = 100和limit_diffs = 0在快速的笔记本电脑上花费了约7分钟，并生成了一个约5.7GB的网站。峰值内存使用量约为8GB。

其他注意事项

默认模板提供为起点，并演示了大多数功能。完全预期你会自定义或替换它们。

默认模板使用%ID%变量来输出文件、目录、分支和标签。这些保证是唯一的且适合URL。但是，当对仓库进行更改时，文件和目录的链接将失效。要获取“永久链接”，你可以将输出变量更改为使用%PATH%，并将所有模板文件中的{{file.id}}和{{dir.id}}替换为{{file.path | url_string}}和{{dir.path | url_string}}。

限制

• 仅索引一个分支的历史。
• 大型仓库内存使用量高。
• 限制在预定义的输入模板集合内。
• 在出现错误的情况下，输出处于未知或部分状态。

主要依赖

• git2 -- libgit2库的Rust包装器。
• libgit2 -- 用于访问 Git 仓库的 C 库。
• Tera -- 基于 Jijna2 的 Rust 模板引擎。
• pulldown-cmark -- 将 Markdown 渲染为 HTML 的 Rust 库。
• syntect -- 将文件内容渲染为语法高亮 HTML 的 Rust 库。
• onig (可选) -- Oniguruma 语法高亮库的 Rust 包装器。
• oniguruma (可选) -- 用于语法高亮的 C 库。

类似软件

Git 静态生成器

我没有使用这些，但它们存在。我相信它们也很不错。Itsy-Gitsy 主要区别在于其可配置性和对用户定义模板的关注。

• git-arr -- 另一个基于 Python 的 Git 静态网站生成器。
• stagit -- 另一个基于 C 的 Git 静态网站生成器。

Git 代码库

代码库通常包括项目管理功能和特别的问题跟踪器。

• Gitea -- 一个开源的、可自托管的、动态代码库。
• Kallithea -- 一个开源的、可自托管的、动态代码库。
• GitLab -- 一个“开源核心”，可自托管的、动态代码库。

Git 浏览器

• gitweb -- Git 内置的 web 服务器加动态仓库浏览器。
• cgit -- 一个动态仓库浏览器。
• shithub -- 一个极简主义、开源、可自托管的、动态仓库浏览器。