README

使用 PHP 生成静态网站的工具。

Meduza 是一个使用静态网页开发的 PHP 8 静态网站生成器，支持主题和插件。

为什么选择 Meduza？

开发 Meduza 的动机是挑战自我，同时，现有的其他静态网站生成器——例如 Hugo、Jekyll 和 Pelican——要么配置复杂，要么主题选择有限。

Meduza 可能只是一个静态网站生成器，但完成这个挑战本身就值得了。

要求

目前，要求在 composer.json 文件中指定，具体如下

"require": {
    "twig/twig": "3.x-dev",
    "ext-yaml": "^2.2",
    "php": ">=8.0.3",
    "league/commonmark": "2.1.x-dev"
},

安装

Meduza 被创建为一个项目，因此标准安装程序是

composer create-project meduza-static-site-generator/meduza my-site "@dev"

其中，my-site 是您将用作网站基础目录的目录名称。

之后，您需要创建用于构建静态文件的目录。默认是 ./build，但您可以使用任何其他目录，甚至不在项目目录结构中。只需确保更新配置

build:
    input: "./content"

要创建项目根目录下的 build 目录，请执行以下操作

cd my-site
mkdir build

配置

Meduza 支持多种格式的配置文件，如 YAML。我们提供了带有文档选项的示例文件。

一个标准项目包含两个基本文件——dev.yml 和 prod.yml。前者包含开发环境配置，后者包含生产环境配置。当然，dev.yml 包含大多数配置。

我们还提供了一些与插件和默认主题相关的辅助配置文件。它们位于 config 目录中。

可以使用 import 选项合并任何配置文件

import:
    - "./config/theme/alembic.yml"
    - "./config/plugin/catloger.yml"
    - "./config/plugin/time-read.yml"
    - "./config/plugin/resumizer.yml"

导入配置文件将覆盖任何已加载的配置。例如，在 prod.yml 文件中，它导入 dev.yaml 并覆盖一些配置。因此，重要的是要注意 import 在每个文件中的位置。

配置文件可以位于任何位置。

主题和插件

Meduza 支持主题和插件（在创建项目时未安装）。可以通过查询以 meduza-theme-* 和 meduza-plugin-* 开头的存储库来获取可用主题的列表。

要安装主题，建议的步骤是

composer require meduza-static-site-generator/meduza-theme-alembic

在这个例子中，将安装 Alembic 主题。

主题可能需要一些插件。为了方便，所需插件已在主题的 composer.json 文件中的 require 部分指定。

要安装与主题一起未自动安装的插件，请执行以下操作

composer require meduza-static-site-generator/meduza-plugin-catloger

此外，主题和插件都需要进行配置。因此，每个主题/插件都有一个带有支持选项和文档注释的默认配置文件。

因此，只需使用 import 导入主题/plugins 的配置文件即可使一切正常运行。

静态内容

您可能想向您的网站添加一些静态内容。

为此，只需将其放入 static 目录中，包括所需的目录结构。所有这些内容都将复制到 build 中。

网站内容

网站本身的实际内容是通过 Markdown 文件制作的。这些文件可以放在任何地方，但标准是 content 目录。

markdown 文件有两个部分：frontmatter 和实际的 markdown。

frontmatter 示例（应位于文件开头）。

---
title: "Blog de exemplo"
layout: "index"
---

frontmatter 只有两个必选项

title：文档的标题
layout：文档的布局，必须与所选主题提供的布局之一相匹配。

注意，layout 可以通过配置中的 defaults 选项来定义。

content 目录可以有任何文件和子目录结构。标准是

请注意，这个结构是任意的，并且将在 build 中复制。您可以指定所需的任何结构。但是，配置选项 defaults 与该结构相关联，因此如果需要，请记得更新它。

至于 markdown，我们使用 The PHP League/CommonMark 作为 parser，并使用 GitHub Flavored Markdown (GFM) 选项。

实用工具

目前，Meduza 在 bin 目录中提供了两个 scripts 实用工具，分别为 Windows 和 Linux 版本。

build.bat 和 build.sh：构建静态内容。应提供基本配置文件作为 build 的参数

对于 Linux...

bin/build.sh dev.yml

... 或者对于 Windows...

bin\build.bat dev.yml

serve.bat 和 serve.sh：在 localhost:8000 的主机/端口上执行内置的 PHP HTTP 实例，并以 build 作为根目录。因此，如果您已更改 build 目录（或希望更改主机/端口），则必须手动使用 php -S localhost:8000 -t meu_outro_diretorio 来运行服务器。

如何贡献

要为项目做出贡献，请按照以下步骤操作

创建一个 fork；
克隆 fork 并为您的贡献创建一个新的 branch；
将您的更改发送到 fork；
创建一个 pull request。

创建一个针对您的更改的 issue 在官方存储库中，并在您的 branch 和 commits 中引用它。还要在 issue 中引用您的 pull request。这将加快对您的贡献的分析。

许可证

Meduza、其主题和插件均根据 MIT 许可证许可

meduza-static-site-generator / meduza

维护者

详细信息