statical

一个日历聚合器和生成器，使维护静态网站上的日历更加容易。

为什么存在这个项目

虽然日历服务有很多，但它们都有缺点

• 它们都带有品牌，或者更确切地说，价格昂贵，每月价格从约8-45美元不等。虽然低端的价格并不糟糕，但如果要将日历添加到多个网站，成本会迅速增加。
• 这些日历，无论是嵌入的还是链接的，都会调用它们的服务器，而这些服务器可能不会尊重网站访问者的隐私偏好。
• 虽然自托管选项是可用的，但我不想仅仅为了托管一个简单的日历而设置和管理另一个服务器。静态网站很优秀，日历也应该静态。

没有可用的选项能满足我的需求，所以我决定自己构建。这个项目也是Rust软件开发的一个极好的动机和实践。

状态

这个程序现在主要用于基本日历生成功能，因此现在处于开发中的 Beta 阶段。通过更多的工作，它可以达到1.0版本的重要里程碑。

需要完成文档，以及添加设置指南。代码接近通用可用性，但仍可能需要一些调整和挖掘。

为了使配置更容易，statical现在可以使用 --generate-default-config 标志生成示例配置文件。

默认模板已经开始看起来可以接受，我们计划不久进行最终设计审核。虽然模板和CSS可以完全自定义，但目标是让默认设置产生一个用户体验良好、界面和美学上令人愉悦的日历。这里还需要做一些工作。

特性

• 读取 *.ics 文件或实时日历源
  • 缓存实时日历源
  • 缓存超时可配置（默认为1天）
  • 允许指定cookie，以便下载需要登录的日历源
• 不需要贡献者创建新的登录。只需将他们的日历源添加到配置文件中即可。
• 可以在个人机器上手动运行，或者设置为Cron作业、Git钩子或持续集成（CI）管道
• 生成静态HTML视图
  • 月份
  • 周
  • 日
  • 日程表
• 视图定制
  • 默认视图已嵌入到应用中
  • 或者，视图也可以通过Tera模板单独覆盖和完全定制
  • 视图完全基于HTML和CSS，不包含JavaScript
  • 提供了SASS/CSS，但可以进行编辑或完全覆盖
  • 日历可以分配自定义颜色。任何有效的CSS颜色表示法都应适用，包括颜色名称。
  • 颜色通过Oklch颜色空间进行调整以提高可读性。（亮度和色度调整值可以配置或完全禁用。）
• 以ICS格式生成日历源

目标用户

Statical的设计考虑了三种类型的用户

1. 普通CLI用户

Statical应该足够简单，以便具有基本CLI知识的人可以安装它、修改默认配置，并在几分钟内拥有看起来很好的日历。

2. 高级网页设计师

对于那些想要更多控制生成的日历的人来说

• 提供了丰富的配置选项
• SASS/CSS可以定制或完全覆盖
• 视图通过可定制或完全覆盖的模板生成

3. Rust程序员

如果需要完全控制，此代码在BSD 3条款许可证下发布。

使用方法

背景

Statical旨在在“静态站点生成器链”中（感谢CloudCannon提供此术语）使用。Statical应该在Pagefind和Jampack等工具之前运行，因为其输出页面需要索引和优化。

一个示例链可能如下所示

1. soupault（或您喜欢的静态 网站 生成器）
2. statical
3. Pagefind（或tinysearch、stork、orama或类似工具）
4. Jampack
5. 部署或同步您的网站

配置

Statical必须有一个配置文件才能运行。使用以下命令创建示例配置文件

statical --create-default-config

使用您最喜欢的文本编辑器修改配置文件。以下键是严格必要的

• display_timezone：来自IANA时区数据库的时区标识符之一
• default_calendar_view：Month、Week、Day或Agenda之一
• calendar_sources可以提供多个来源。
  • name：必须是短横线命名法
  • source：可以是日历源URL或本地*.ics文件

其余选项具有默认值，对于大多数用户来说应该适用。生成的配置文件中包含注释，解释了每个选项的用途。

运行statical

每当日历发生变化时，都需要运行statical。这可以手动完成，也可以通过cron作业、Git钩子或CI管道完成。

Statical将在当前目录中查找名为statical.toml的配置文件。或者，您可以将一个或多个配置文件作为参数传递给statical，例如。

statical site-one/statical.toml site-two/statical.toml ...

定制

默认资源和模板已内置到statical中，但用户可以根据需要覆盖它们。

资源

如果您想定制CSS，请运行

statical --restore-missing-assets

资源目录将在配置文件中指定的位置创建（路径相对于配置文件本身）。默认为 assets。

任何缺失的资源文件将重新从statical内置的资源中创建。可以根据需要编辑资源，或删除以恢复内置默认值。如果资源已存在且与默认值之一同名，则不会覆盖。

模板

要自定义视图本身，请运行

statical --restore-missing-templates

模板目录将在配置文件中指定的位置创建（路径相对于配置文件本身）。默认为 templates。

任何缺失的模板文件将重新从statical内置的模板中创建。可以根据需要编辑模板，或删除以恢复内置默认值。如果模板已存在且与默认值之一同名，则不会覆盖。

模板语言

Statical 使用 Tera 模板来允许自定义日历视图。有关Tera及其功能的详细信息，请参阅Tera 文档。

要查看在特定模板中可用以使用的所有数据，请在模板中的某个位置添加以下代码

<pre>
  {{ __tera_context }}
</pre>

相关项目

如果statical不能完全满足您的需求，请查看这些项目。

• ical-merger：将多个iCalendar文件合并为一个，作为Web服务。
• ical-filter：HTTP守护进程，用于标准化和过滤iCalendar文件
• zerocal：Matthias Endler在shuttle.rs上运行的Rust无服务器日历应用程序

路线图和待办事项

以下内容相当庞大，可能需要整理和重新组织。我们目前将其保留在此处，但将来可能会将其拆分为单独的文档。

预发布测试修复

• 修复默认日期错误 (2023-09-13)
• 默认启用复制样式表 (2023-09-13)
• 将默认样式表嵌入到二进制文件中 (2023-09-13)
• 添加 --restore-missing-templates (2023-09-14)
• 使配置生成直接写入文件 (2023-09-14)
• 将默认源放入在未更新时触发帮助的触发器
• 添加初始设置选项
• 在首次运行命令时添加帮助 (2023-09-14)
• 添加助手以帮助添加日历源？
• 确保部分配置文件正常工作，即缺少许多键的文件
• 创建所需配置键列表，运行statical所需的最小键集 (2023-09-15)
• 调整视图链接以接近当前页面的最近时间段（链接到当前项大于等于的项）
• 链接日数字

设置和配置（1.0里程碑）

• 添加toml配置
• 添加生成示例模板或在其文档/存储库中提供它们的选项 (2023-09-04)
• 添加 tera 模板 (2022-05-17)
• 添加baseurl支持 (2023-09-08)
• 默认在当前目录中查找 statical.toml 文件 (2023-09-08)
• 使所有路径相对于配置文件 (2023-09-09)
• 如果不存在或未提供配置文件，则提示如何使用Statical的说明。 (2023-09-14)
• 添加 --restore-missing-assets 选项 (2023-09-14)
• 添加从浏览器自动检索身份验证cookie

设置和配置（未来工作）

• 允许模板路径配置。 (2023-09-14)
• 日历颜色和CSS类 (2023-09-19)
• 时间间隔页面的路径应该可配置吗？

日历生成（1.0里程碑）

• 添加获取一周第一天日期的调用 (2022-05-19)
• 将周视图切换为基于BTreeMap的事件列表 (2023-09-02)
• 将日视图切换为基于BTreeMap的事件列表 (2023-09-02)
• 重做事件分组逻辑 (2023-08-28)
  • 将所有事件存储在BTreeMap中（它允许高效的顺序访问，从而实现范围访问） (2023-08-28)
  • 这应该允许使用单个映射来存储所有事件，而不是我们现在使用的复杂嵌套结构 (2023-08-28)
  • 在视图创建时从映射中检索事件，然后可能将它们分组到相关上下文中 (2023-08-28)

样式（1.0里程碑）

• 为日历视图添加样式以隐藏事件描述，并在悬停时显示它们 (2023-09-01)
• 添加工作日和周末类 (2023-09-08)
• SASS处理 (2023-09-19)
• 添加源日历类 (2023-09-19)
• 从事件标题文本中移除no-wrap（但在持续时间上保持no-wrap）
• 突出显示当前天
• 清理分页和视图
• 使分页与网格对齐
• 居中标题
• 清理CSS
• 日历颜色CSS类
• 将日历类CSS规则追加到样式表中
• 使CSS规则具有更高的特定性
• 使日历源视图按钮成为一个下拉菜单
• 为其他月份的天添加半透明覆盖
• 重命名默认样式表 statical.css

样式（未来工作）

• 添加事件类
• 添加事件类别
• 找出如何布局重叠事件。CSS网格来拯救？
• 在桌面上的日视图中水平堆叠重叠事件（如果空间允许，可能是周和月）
• 在左侧添加时间，并在周和日视图中对齐事件

输出页面（1.0里程碑）

• 日程（事件列表）
• 日 (2022-09-15)
• 周 (2022-05-19)
• 月 (2022-09-15)
• 每个时间间隔的索引页面 (2022-09-15)
• 通过前进和后退链接链接页面 (2022-05-19)
• 添加默认CSS (2022-05-19)
• 添加链接以在间隔之间切换 (2022-09-15)
• 将摘要添加到事件标题 (2023-09-08)
• 内部存储模板，但使用提供的版本。 (2023-09-08)
• 事件详细信息
  • 决定URL命名，可能不是基于日期的，可能包括日历名称
  • 使用未展开的事件
• 添加页面地图，显示在日历中生成的所有页面的概述（对于调试和双重检查稀疏与密集生成很有用）
• 添加ics源生成
• 在周视图中在一个月的第一天添加月份名称（就像月视图一样） (2023-09-09)
• 根据哪个月份在该周有最多天来决定一个周“属于”哪个月份？ (2023-09-09)
• 在周模板中清理HTML类逻辑，在生成上下文时将其移动到Week类中
• 添加strftime格式化日期的天？
• 为日程日期添加strftime格式化？
• 添加键盘快捷键以允许在日历中进行键盘导航
• 允许使用模板替换embed_page head部分

JavaScript（未来工作）

• 为移动设备添加JavaScript（或CSS切换）以切换事件描述
• 添加JavaScript以在切换视图格式时跳转到所选日期最近的日期
• 跳转到当前天
• 突出显示当前天
• 选择天（s）
• 突出显示所选天（s）
• 在切换视图时保持所选天（s）
• 添加JS以切换按日历显示事件
• 添加JS以切换按类别显示事件

日历生成（1.0里程碑）

• 修复日程事件收集逻辑
• 修复日视图中的事件排序
• 计算每个日历的开始和结束日期，不要默认为今天

日历生成（未来工作）

• 遍历日历范围内的所有月份、周、日（密集HTML日历生成设置）
• 添加稀疏设置并决定如何处理缺失的间隔
• 添加稀疏标志以不渲染缺失的间隔或在该处放置占位符

日历过滤和处理（未来工作）

• 向日历描述添加HTML清理
• 在日历描述中添加对Markdown的支持
• 事件去重
• 事件信息合并
• 信息合并优先级/层次结构
• 添加处理规则
  • 添加类别
  • 添加标签？
  • 隐藏/合并事件
  • 移动/复制/编辑事件
  • 添加日历组
  • 日历源路由
• 添加人类日期格式解析
• 支持日出和日落（如果事件有位置，或者默认为日历位置？）
• 添加对一个月的第一天、第二天、第三天等X天的支持

人体工程学

• 实时预览服务器

外部工具集成（未来工作）

• pagefind集成（添加索引提示模板）
• jampack集成？