ilmiont/ardea

Ardea 是一个使用 PHP 的最小静态网站生成器。

维护者

详细信息

gitlab.ilmiont.net/ilmiont/ardea

安装: 427

依赖项: 0

建议者: 0

安全性: 0

1.1.2 2022-06-10 19:30 UTC

Requires

Requires (Dev)

MIT 7c8e6040abe6be0d609ba48e3b353f2941b7b74d

  • James Walker <jh_walker.woop@outlook.com>

This package is auto-updated.

Last update: 2024-09-11 00:40:44 UTC

README

Ardea 是一个使用 PHP 的最小静态网站生成器。它专注于加载和渲染网站页面和内容的基本功能。可扩展的基础设施允许您添加自定义内容发现机制和模板渲染器。

用法

使用 Composer 在您的项目中安装 Ardea

$ composer require ilmiont/ardea

在您的工作目录中创建一个 ardea.json 文件

{
	"content": {
		"pages": {
			"template": "tpl/page.php",
			"items": [
				{
					"uri": "/index.html",
					"title": "Home",
					"body": "Welcome to my website."
				},
				{
					"uri": "/about.html",
					"title": "About Me",
					"body": "I'm a developer."
				},
				{
					"uri": "/contact.html",
					"title": "Contact Me",
					"body": "You can contact me by email."
				}
			]
		}
	}
}

接下来，在您的工作目录中创建一个 tpl/page.php 文件

<!DOCTYPE html>

<html>
	<head>
		<meta charset="utf-8">
		<title><?= $i -> prop("title"); ?></title>
	</head>
	<body>
		<h1><?= $i -> prop("title"); ?></h1>
		<p><?= $i -> prop("body"); ?></p>
	</body>
</html>

现在您可以运行 Ardea 来渲染您的网站

$ vendor/bin/ardea

您的页面将被渲染到您的工作目录中的 build

$ ls build
about.html  contact.html  index.html

就是这样！这个例子演示了使用 Ardea 的基本方法。

入门

Ardea 使用您工作目录中的 ardea.json 文件进行配置。在此文件中，content 属性是最重要的，因为它定义了 Ardea 将渲染以创建网站的内容项。

content 内部嵌套的每个属性定义了一个“内容类型”。同一内容类型内的内容项在逻辑上分组在一起，并使用相同的模板进行渲染。

用于内容类型的模板由其定义对象内的 template 属性定义。属性的值应该是您工作目录内的 PHP 文件的相对路径。

如果内容类型省略了 template 属性，将使用配置文件中设置的默认模板。有关更多信息，请参阅下面的 配置 部分。

可以通过多种方式将内容项添加到内容类型中。在上面的示例中，内容项定义为内容类型内的 items 数组中的静态对象。每个对象将单独渲染并保存到其 uri 属性指定的路径，该路径相对于活动输出目录解析。

静态内容项

可以将内容项作为静态对象添加到内容类型中，方法是在内容类型上定义一个 items 属性，该属性是一个内容对象的数组。每个内容对象都需要一个 uri 属性，该属性定义了将内容项的渲染输出保存到相对于活动输出目录的路径。

每个内容项对象的其余属性成为项目属性，在您的 模板 中可以访问。

静态内容项的示例包括在上面的 用法 部分中。

Markdown 内容项

Ardea 具有内置的渲染磁盘上的 Markdown 文件的支持。每个 Markdown 文件的名称必须以 .md 结尾，并且文件必须显示有效的 Markdown MIME 类型。

要将 Markdown 源内容项添加到内容类型中，在配置对象中提供 markdown 属性。将加载 Markdown 内容项的路径作为属性的值提供。路径相对于您的工作目录解析。

{
	"content": {
		"posts": {
			"template": "tpl/post.php",
			"markdown": "content/blog"
		}
	}
}

将递归搜索目录以查找有效的 Markdown 文件。每个找到的文件都将使用指定的模板进行渲染，并输出到相对于输出目录的路径。例如，使用上面的示例配置，Markdown 文件 content/blog/demo-post.md 将输出到输出目录中的 content/blog/demo-post.html。您可以通过在文件的前端元数据中提供 uri 属性来更改特定 Markdown 文件的输出路径 URI。

Markdown 内容加载器为每个渲染的文件提供以下模板属性

属性类型描述
file字符串文件在搜索目录根部的相对路径（例如 2022/05/01/demo-post.md）。
文件名字符串文件的名称（例如：demo-post.md）。
html字符串Markdown文件的內容，渲染成HTML。
markdown字符串Markdown文件的內容。
src字符串文件相对于工作目录的完整相对路径（例如：content/blog/2022/05/01/demo-post.md）。
title字符串假设的内容标题；这是Markdown内容的第1行，去除了所有标签。

Markdown内容加载器支持Front Matter。任何Front Matter都将从markdown和html属性中去除。Front Matter将被提取，并以键/值属性的形式在您的模板中提供；如果Front Matter键与上述属性之一相同，则Front Matter的值将覆盖Ardea提供的值。

Ardea使用Parsedown来渲染Markdown文件。您可以通过手动构建MarkdownContentLoader实例来提供自定义Parsedown实例。

use Ardea\MarkdownContentLoader;
use Parsedown;

$markdownLoader = new MarkdownContentLoader(new Parsedown());

有关如何向Ardea提供您自定义的内容加载器实例的详细信息，请参阅下文中的编写扩展部分。

模板

Ardea默认使用纯PHP模板，由包含的PhpRenderer渲染。您可以根据下文中的编写扩展部分的指导来实现自己的渲染器。

当使用默认的PhpRenderer时，您可以在模板中访问以下变量

变量类型描述
$iArdea\ContentItem正在渲染的内容项。
$itemArdea\Content正在渲染的内容项及其内容类型的聚合。
$contentArdea\ContentCollection所有正在渲染的内容项。
$ardea / $config / $propsArdea\PropStore您ardea.json文件的内容。
$tpl字符串使用内容项渲染的模板的路径。
$dst字符串内容项渲染输出将被保存的路径。
$thisArdea\PhpRenderer活动的渲染器实例。

请参阅下文中的API参考，了解内容、内容集合和配置属性存储对象上的可用方法。您将普遍使用这些方法来访问您活动的配置值和内容项属性。

示例：按date Front Matter属性顺序渲染Markdown来源的博客帖子列表

ardea.json

{
	"content": {
		"posts": {
			"template": "tpl/post.php",
			"markdown": "content/blog"
		}
	}
}

tpl/post.php

// ...
<?php foreach ($content -> getByContentType("posts") -> sortByContentProp("date") as $post): ?>
	<li><a href="<?= $post -> ContentItem -> uri(); ?>"><?= $post -> ContentItem -> prop("title"); ></a></li>
<?php endforeach; ?>
// ...

示例：访问自定义配置属性

ardea.json

{
	"site": {
		"theme": {
			"palette": {
				"accent": "##bbddff"
			}
		}
	},
	"content": {
		"pages": {
			"template": "tpl/page.php",
			"items": [
				{
					"uri": "/index.html"
				}
			]
		}
	}
}

tpl/page.php

// ...
<head>
	<meta name="theme-color" content="<?= $props -> prop("site.theme.palette.accent"); ?>">
</head>
// ...

配置

所有配置属性都在您的ardea.json文件中的ardea属性中设置

{
	"ardea": {
		"template": "tpl/page.php",
		"outputDir": "build",
		"workDir": "/tmp/my-site"
	}
}
属性类型描述默认值
ardea.template字符串当内容类型没有定义时，渲染内容项的模板文件路径（相对于工作目录）。-
ardea.outputDir字符串渲染输出内容的路径，相对于工作目录。build
ardea.workDir字符串将工作目录解释为的路径。仅在Ardea核心内部可靠 - 内容加载器和渲染器（包括内置的）可能目前不支持它，并且可能使用您的实际工作目录。PHP的getcwd()函数的调用。

API参考

建议您目前参考源代码以获取完整的API参考。检查Content、ContentCollection、ContentItem、ContentItemCollection、ContentType、ContentTypeCollection、ContentTypeDefinition、HasProps和PropStore对象将告诉您如何在模板中访问内容和配置值。

在编写扩展时，主要参考应用程序入口点（存储库根目录中的ardea），以及PropStore、ContentLoader和Renderer接口。

编写扩展

Ardea 可以通过新的内容加载器和渲染器进行扩展。

要编写和使用自己的扩展，创建一个自己的入口点来构造一个 Ardea\Ardea 实例。其签名如下

namespace Ardea;

final class Ardea {

	public function __construct(
		protected readonly PropStore $Config,
		protected readonly ContentLoaderCollection $ContentLoaders,
		protected readonly Renderer $Renderer) {}

}
  • $Config - 此 PropStore 实例为 Ardea 提供其配置值（默认为 ardea.json 内容）。
  • $ContentLoaders - 这里提供的 ContentLoader 实例将用于发现您的内容类型中要渲染的内容。
  • Renderer - 此 Renderer 实例被 Ardea 用于渲染您的内容项。

有关如何配置 Ardea 的默认内容加载器和渲染器的示例，请参考存储库根目录下的标准应用程序入口点 ardea。

编写内容加载器

内容加载器将内容项添加到您的内容类型中。Ardea 支持内联静态定义的内容项和来自磁盘上的 Markdown 文件的源内容项。

要创建新的内容加载器，实现 ContentLoader 接口，并在构造 Ardea 时将其实例作为 $ContentLoaders 集合的成员提供。

渲染器

渲染器将内容项转换为渲染输出。Ardea 内置了一个默认的渲染器，支持 PHP 模板语法。

要创建新的渲染器，实现 Renderer 接口，并在构造 Ardea 时将其实例作为 $Renderer 参数提供。

自定义默认渲染器

默认的 PHP 模板渲染器有两个构造参数

namespace Ardea;

final class PhpRenderer {

	public function __construct(

		/**
		 * Props to make available to templates
		 */
		protected readonly PropStore $Props,

		/**
		 * Writer instance that saves rendered output
		 */
		protected readonly Writer $Writer) {}

}

$Props 作为 $ardea、$config 和 $props 变量在您的 模板 中可用。

作为 $Writer 提供的 Writer 实例负责将渲染的模板写入目标输出路径。默认的写入器将保存到本地文件系统。您可以通过实现 Writer 接口来创建自己的写入器。

©James Walker. 许可证：MIT 许可。