Shokunin 静态网站生成器 (SSG)

构建专业网站和博客最快的基于 Rust 的静态网站生成器 (SSG)

是 Rust 库系列 Mini Functions 的一部分。

• 网站 • 文档 • 报告错误 • 请求功能 • 贡献指南

概述

Shokunin 是一个闪电般的静态网站生成器 (SSG)，针对搜索引擎优化 (SEO) 优化，并完全符合无障碍标准。

该库从 Markdown、YAML、JSON 和 TOML 提取元数据和内容，生成静态 HTML 文件。它还支持 HTML 主题和自定义模板，帮助您轻松创建高质量网站。

功能

Shokunin 静态网站生成器 (SSG) 的亮点包括

• 由 Rust 编写的闪电般快速且灵活的静态网站生成器
• 内置对 GitHub Flavoured Markdown (GFM) 的支持
• 内置对 Google Analytics 和 Bing Analytics 的支持
• 实验性支持 PDF 生成
• 与各种 HTML 主题和高级模板兼容
• 自动为您的博客帖子生成 Atom 和 RSS 源
• 生成优化性能和 SEO 的压缩 HTML
• 包含内置的 Rust 开发服务器以进行本地测试
• 支持多种内容格式
  • Markdown
  • YAML
  • JSON
  • TOML
  • XML
• 内置生成功能
  • 网站地图
  • robots.txt
  • 规范名称（CNAME）记录
  • 自定义404页面
• 全面文档

目录

• Shokunin 静态网站生成器 (SSG)
  • 概述
  • 功能
  • 目录
  • 入门指南
    • 安装
    • 要求
    • 平台支持
    • 文档
  • 用法
    • 命令行界面（CLI）
      • 参数
    • 在你的项目中
    • 示例
      • 参数
  • 语义化版本控制策略
  • 许可证
  • 贡献
  • 鸣谢

入门指南

只需几分钟即可开始使用Shokunin静态网站生成器（SSG）。

安装

要安装Shokunin静态网站生成器（SSG），您需要在您的计算机上安装Rust工具链。您可以通过遵循Rust网站上的说明来安装Rust工具链。

一旦您安装了Rust工具链，您可以使用以下命令安装Shokunin静态网站生成器（SSG）：

cargo install ssg

为了简化，我们给Shokunin静态网站生成器（SSG）提供了一个简单的别名ssg，它可以代表Shokunin Site Generator或Static Site Generator。

然后，您可以运行帮助命令以查看可用的选项和命令。

ssg --help

要求

目前，最低支持的Rust工具链版本是Rust 1.71.1或更高版本（稳定版）。建议您安装Rust的最新稳定版本。

平台支持

Shokunin静态网站生成器（SSG）在我们CI/CD流水线的一部分中支持并测试以下平台和架构。

GitHub Actions显示了Shokunin静态网站生成器（SSG）库测试运行的平台。

文档

ℹ️ 信息：请访问我们的网站获取更多信息。您可以在docs.rs、lib.rs和crates.io上找到我们的文档。

用法

命令行界面（CLI）

Shokunin静态网站生成器（SSG）库在终端窗口中运行，可以轻松生成静态网站。要开始，请运行

ssg  --new=docs --content=content --template=template --output=output --serve=public

或

ssg  -n=docs -c=content -t=template -o=output -s=public

这将在名为docs的目录中创建一个新的网站，使用来自content目录的Markdown内容和来自template目录的HTML模板。然后，在docs文件夹中生成静态和编译后的HTML文件和工件。

Shokunin非常适合托管在GitHub Pages上。只需将docs文件夹提交并推送到您的主分支，并将GitHub Pages发布源设置为指向该文件夹。

在开发过程中，您可以使用--serve或--s选项启动本地开发服务器以预览内容更改。

借助Shokunin的GFM和主题支持，您可以专注于编写Markdown内容，而SSG则负责提供快速、SEO友好的网站。

参数

• -n，--new：您新网站的文件夹名称。（必需）
• -c，--content：包含网站Markdown内容的目录。（必需）
• -t，--template：包含HTML网站模板的目录。（必需）
• -o，--output：生成的网站文件将临时保存到的目录。（必需）
• -s，--serve：运行开发服务器。（可选）。网站将从该目录提供。（可选）

在你的项目中

要在您的项目中使用Shokunin静态网站生成器（SSG）库，请将以下内容添加到您的Cargo.toml文件中：

[dependencies]
shokunin = "0.0.29"

将以下内容添加到您的 main.rs 文件中

extern crate ssg;
use ssg::*;

然后您就可以在应用程序代码中使用 Shokunin 静态网站生成器 (SSG) 的函数了。

示例

要开始使用 Shokunin 静态网站生成器 (SSG)，您可以参考项目 examples 目录中提供的示例。

要运行示例，请克隆存储库，并在项目根目录下从终端运行以下命令。

cargo run --example example

该命令将根据 examples 目录中的配置细节生成静态网站。

use ssg::compiler::compile;
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Define the paths to the build, site, content and template directories.
    let build_path = Path::new("examples/example.com/build");
    let content_path = Path::new("examples/example.com/content");
    let site_path = Path::new("examples/example.com/public");
    let template_path = Path::new("examples/example.com/template");

    compile(build_path, content_path, site_path, template_path)?;

    Ok(())
}

此代码中的 main() 函数使用 template 目录生成网站文件，从 content 目录编译网站。编译后的网站保存在 build 目录中，并直接从 example.com 目录中提供。

参数

• build_path: 编译后网站将被保存的目录路径。
• content_path: 包含网站内容的目录路径。
• site_path: 从中提供生成的网站文件的目录路径。
• template_path: 包含网站模板的目录路径。

语义化版本控制策略

为了提高透明度并努力保持向后兼容性，Shokunin 静态网站生成器 (SSG) 遵循 语义化版本控制。

许可证

该项目根据 MIT 许可证和 Apache 许可证（版本 2.0）的条款进行许可。

• Apache 许可证，版本 2.0
• MIT 许可证

贡献

我们欢迎所有想贡献的人。有关更多信息，请参阅贡献说明。

向此项目的任何形式（问题、拉取请求等）的贡献都必须遵守 Rust 的行为准则。

除非您明确声明，否则任何根据 Apache-2.0 许可证定义的、有意提交以包含在作品中的贡献，将根据上述条款双重许可，不附加任何额外条款或条件。

鸣谢

衷心感谢所有为 Shokunin 做出贡献和支持的杰出贡献者。

特别感谢 Rust Reddit 社区为提供大量有关如何改进此项目的有用建议。