README

Stagger 是用 PHP 编写的极简静态网站生成器。

它使用 Markdown 作为内容，使用 YAML 进行配置，使用 Twig 进行 HTML 模板。

理由

目前市面上有很多静态网站生成器，但其中许多流行的生成器在创建简单的网站或博客时过于复杂。它们功能繁杂，文档众多，这意味着您需要花费大量时间学习如何使用工具，而不是仅仅使用工具，并将这些时间用于创建网站内容。

相比之下，Stagger 致力于保持极简，并提供最小化的功能集和这个 README 文件作为唯一的文档。目标是让您能够立即开始编写内容，并花费最少的时间进行配置或阅读文档。

示例网站

Stagger 包含一个位于 sites/example 的示例网站，它展示了网站的架构和一些示例页面和博客文章。只有一个配置文件，位于根目录下的 site.yml。页面位于 pages 目录中，每个页面都有自己的子目录。如果子目录包含 blog.md、page.md 或 post.md，它将分别被识别为博客索引、普通页面或博客文章。

该示例网站使用 Spectre.css。它为 CSS 样式提供了一些合理的默认值，是一个良好的起点。您可以选择使用或不使用它。

要求

您需要了解 HTML、CSS 和 Markdown 才能使用 Stagger 创建网站。除非您想修改工具的内部结构，否则不需要了解 PHP。

您需要一个命令行界面来使用 Stagger。最好是 Linux 或 Mac 中的 Bash shell。

首先，确保在命令行上已安装 PHP

$ php --version
PHP 8.0.8 (cli) (built: Jun 29 2021 16:09:21) ( NTS )

其次，确保您已安装 Composer。如果没有，请按照 说明 进行操作。

$ composer --version
Composer version 2.1.3 2021-06-09 16:31:20

基本用法

要开始，请使用 Composer 创建一个新的项目

$ composer create-project peklaiho/stagger mysite
Creating a "peklaiho/stagger" project at "./mysite"
$ cd mysite

您可以通过以下方式生成示例网站

$ bin/stagger example
...
Generated site in /home/pekka/mysite/bin/../output/example.

完成的网站位于 output/example。您可以使用 PHP 内置的 web 服务器来查看它

$ php -S 127.0.0.1:8000 -t output/example/
[Sun Jul 25 12:20:26 2021] PHP 8.0.8 Development Server (http://127.0.0.1:8000) started

在您的网络浏览器中导航到 http://127.0.0.1:8000。

这就是全部！将 sites/example 中的文件与 output/example 中的文件进行比较，了解工具的工作原理。大部分应该都很明显。

您可以将示例网站复制过来，作为构建自己网站的起点

$ cd sites
$ cp -r example mysite

高级用法

Stagger 使用 highlight.php 在服务器端进行源代码语法高亮，因此不需要 JavaScript。从 vendor/scrivo/highlight.php/styles 目录中选择一个 CSS 文件并将其包含到您的网站中。

如果您需要Markdown的额外功能，请查看可以启用的CommonMark扩展。

代码

代码行数少于1000行（包括注释和空白），并会保持在此限制之下。

它包含5个类，代表网站处理过程中的数据

• 网站 - 整个网站
• 页面 - 普通页面
• 博客 - 博客文章索引页
• 文章 - 博客文章
• 文件 - 普通文件（CSS、JS、图片等）

其他类包含主要功能。它们大致按以下顺序使用

• 解析器 - 读取网站并解析site.yml文件
• 读取器 - 读取文件并处理Markdown内容
• 验证器 - 检查网站不包含错误
• 生成器 - 将网站写入磁盘
• 处理器 - 在写入之前操纵HTML代码

限制

目前Stagger仅支持位于域名根目录的网站。要支持子目录中的网站，以便正确生成链接和URL，需要进行少量修改。

在Windows上的功能尚未测试，可能需要少量修改来处理不同的目录分隔符。

许可证

MIT

如果您使用此工具制作网站，如果您在此repo中添加提及（例如“使用Stagger制作”或类似）并附上链接，将会非常感谢！谢谢！