Jekyll::StaticComments 技术文档

1. 安装指南

1.1 环境准备

• 确保你已经安装了 Jekyll，并且有一个正在运行的 Jekyll 站点。
• 确保你的服务器支持 PHP，因为 commentsubmit.php 需要 PHP 来处理评论提交。

1.2 文件放置

1. 将 static_comments.rb 文件放入你的 Jekyll 站点的 _plugins 目录中。
2. 编辑 commentsubmit.php 文件顶部的变量，并将其放置在你的站点中的合适位置。
3. 根据需要修改 comment_received.html 文件（例如，添加 YAML front-matter 以匹配你的站点样式），并将其与 commentsubmit.php 放在一起。
4. 使用 comment_template.html 作为基础，将相应的代码添加到你的博客文章模板中。确保提供一个合适的 URL 指向 commentsubmit.php。
5. 在你的 Jekyll 站点中创建一个 _comments 目录，并填充 YAML 格式的评论文件（可以使用 commentsubmit.php 生成，或手动创建）。

2. 项目的使用说明

2.1 评论存储

• 评论存储在一个名为 _comments 的目录中，该目录可以位于站点树的任何位置（建议与 _posts 目录放在一起）。
• 每个评论文件都是一个 YAML 文件，文件名可以是任意的。每个文件代表一条评论，YAML 文件必须包含一个 post_id 属性，该属性对应于评论所属文章的 id。

2.2 评论渲染

• 在 Jekyll 生成站点时，static_comments.rb 插件会读取 _comments 目录中的所有评论文件，并将其解析为 Comment 对象。
• 每个文章的 page.comments 字段将包含该文章的所有评论对象。你可以通过 Liquid 模板循环遍历这些评论并渲染它们。

2.3 评论提交

• 评论提交通过 commentsubmit.php 处理。该脚本会将评论表单中的所有字段直接转换为 YAML 格式，并通过电子邮件发送给你。
• 你可以选择将评论保存到服务器上的某个位置，或者直接将其提交到你的 Git 仓库并重新生成站点。

3. 项目API使用文档

3.1 评论对象字段

• post_id: 评论所属文章的 ID。
• link: 评论者的链接（可选）。
• nick: 评论者的昵称。
• content: 评论内容。

3.2 Liquid 模板示例

{% for c in page.comments %}
  <a href="{{c.link}}">{{c.nick}}</a>
  <p>
    {{c.content}}
  </p>
  <hr />
{% endfor %}

3.3 注意事项

• 在 Liquid 模板中，不要单独使用 comment 作为标识符，因为 Liquid 会将其视为注释的开始。

4. 项目安装方式

4.1 手动安装

1. 下载 static_comments.rb 和 commentsubmit.php 文件。
2. 将 static_comments.rb 放入 _plugins 目录。
3. 编辑 commentsubmit.php 并放置在站点中的合适位置。
4. 创建 _comments 目录并填充评论文件。

4.2 自动安装

• 你可以将 static_comments.rb 和 commentsubmit.php 文件添加到你的 Jekyll 站点的 Git 仓库中，并通过 CI/CD 自动部署。

通过以上步骤，你可以成功安装并使用 Jekyll::StaticComments 插件，享受静态评论系统带来的便利。