README

概述

Gyokuto 使用 PHP 和 Twig 将本地 Markdown 内容渲染为静态网站。它可以单独使用，也可以与其他 PHP 模块结合使用。

安装

Composer（推荐）

在您的项目中，使用以下命令安装模块

composer require ordinalm/gyokuto dev-master

页面渲染

使用以下命令开始构建

vendor/ordinalm/gyokuto/bin/build

默认情况下，这将查找位于 ./content 中的内容，并将输出到 ./www，读取配置来自 ./gyokuto.yml。

使用 -o /path/to/config/YOUR_CONFIG_FILE.yml 在启动时使用不同的配置文件。

使用 -v1 以详细输出。

Markdown 页面结构

Gyokuto 可以无问题地处理没有元数据的平面 Markdown 文件，但您可能希望使用 Multimarkdown 页面标题系统包含元数据。

---
title: About this site
date: 2020-10-18 13:30
header: true
---
Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Curabitur
blandit tempus porttitor. Maecenas faucibus mollis interdum. Cras justo
odio, dapibus ac facilisis in, egestas eget quam.

Markdown 标题被解析为 YAML 数据，然后可供 Twig 模板使用。

您还可以在页面内容中包含 Twig 代码 - 例如。

---
foo: bar
---
The value of "foo" is "{{ current_page.meta.foo }}".

将渲染为

"foo" 的值是 "bar"。

下面列出了自动可用于 Twig 的值。

特殊元数据变量

以下元数据变量对 Gyokuto 有特殊意义。

• draft - 如果设置为评估为 true 的值，则此页面将 不会 被复制或包含在任何页面列表或索引中。
• template - 这确定用于处理此页面的模板。如果没有设置，则值为 default.twig。
• path - 如果设置，则页面将输出到相对于输出目录根的此路径。这也可以更改文件扩展名，例如 path: "sitemap.xml"
• hidden - 如果设置为评估为 true 的值，则页面将在输出中创建，但不会包含在索引过程中，因此不会出现在 index 或 pages 列表（见下面的 Twig 变量）中。

构建过程

编译阶段

内容目录中的所有文件都被标记为可解析（.md 或 .markdown 扩展名）或只需复制。

所有可解析文件都被解析，它们的元数据包含在整体页面列表中，如果适当，则使用元数据构建索引。

构建阶段

不可解析的文件被简单地复制到输出目录中的相同文件名，这些文件可以是任何类型 - 图片、CSS、PHP 代码等。

Markdown 文件的解析步骤如下

1. 页面主体中的所有 Twig 代码都被评估。
2. 页面主体从 Markdown 转换为 HTML。
3. 为该页面选择由 template 元数据值定义的 Twig 模板运行。

渲染期间可用的 Twig 变量

• current_page - 正在被渲染的页面
  • meta
    • title - 一个未转义的字符串，从 title Markdown 标题字段或文件名中获取
    • date - 从 Markdown 标题中的 date 字段获取的 UNIX 时间戳
    • 页面 Markdown 标题中设置的任何其他变量
  • path - 从站点根目录开始，以 / 开头
  • content - 从页面 Markdown 主体中处理的 HTML（在页面中不可用）
• pages - 构建中的所有页面，按路径键排序，按 date 降序排列，不包括 content。可以用于查找在索引中引用的页面元数据。
  • meta
    • 标题
    • 日期
  • 路径
• 配置
  • 配置文件中声明的所有值

如果配置文件中使用index值指定了任何用于索引的元数据字段，它们将显示为

• index - 通过被索引的元变量键控，按该变量的值排序
  • 键 1
    • 路径 1
    • 路径 2
    • ...
  • 键 2
    • 路径 3
    • ... ...

这些路径可以用于在pages列表中查找页面元数据。

示例：按标签列出所有页面

在gyokuto.yml中

index: [ "tags" ]

在页面或模板中

{% for tag, pagelist in index.tags %}
<h3>{{ tag|escape }}</h3>
<ul>
{% for path in pagelist %}
<li><a href="{{ path }}">{{ pages[path].meta.title|escape }}</a></li>
{% endfor %}
</ul>
{% endfor %}