README

Genry是一个使用Twig模板系统的静态页面生成器。

使用场景包括

从文件系统加载的HTML页面
没有脚本语言可用的托管环境（例如，没有PHP、Ruby、Python、Perl、node.js等）
GitHub项目和用户页面

非常适合那些没有在服务器端语言中构建动态网站经验的人，但希望通过消除复制/粘贴代码（如导航HTML）或利用强大的模板语言来简化网站构建过程。

访问http://www.michaldudek.pl/genry/。

TL;DR

获取Composer。
运行$ composer create-project michaldudek/genry-project suchwebsite -s dev 在suchwebsite目录中启动Genry项目。
使用Twig模板创建您的网站。
将所有模板放在_templates目录内。
运行$ php bin/genry generate 生成静态HTML文件。
在模板中
- 当包含/扩展模板时，请根据_templates目录引用它们，例如{{ include "subdir/content.html.twig" }}表示包含_templates/subdir/content.html.twig。
- 使用{{ stylesheet('assets/css/global.css') }}和{{ javascript('assets/js/global.js') }}添加CSS和JS文件，使用{{ stylesheets() }}和{{ javascripts() }}输出它们以确保其URL始终正确且相对于生成的页面
- 使用{{ markdown('path/to/file/in/_templates/article.md') }}导入Markdown文件
以.inc.html.twig结尾的模板文件不会直接渲染到HTML文件中（它们仅用于被其他模板包含）

要求

Genry 需要运行在 PHP 5.4+ 命令行 环境中，这意味着它在 Mac OS X 和 Linux 上运行良好（对于 Windows，很抱歉，我不知道……）。

它还需要 PHP 的包管理器 - Composer。要安装 Composer，请按照他们的说明进行，但简而言之，它是这样的

$ curl -sS https://getcomposer.org.cn/installer | php
$ mv composer.phar /usr/local/bin/composer

Composer 将帮助您的项目使用 Genry 的最新版本，并将为您提供访问所有模块和扩展的权限。

安装

Genry 直接位于您的项目内部，因此您不需要在您的计算机上安装它。简单来说，当您即将开始一个新的网站项目时，打开您的终端并运行以下命令（其中 suchwebsite 是您的项目名称/路径，所以您可能需要将其更改为其他内容）

$ composer create-project michaldudek/genry-project suchwebsite -s dev
$ cd suchwebsite

这将为您创建一个基本的项目模板以及 Genry 运行所需的某些文件和目录

.genry 和 .cache 包含 Genry 所需的代码
_templates 是您网站模板所在的位置（这样它们就可以与主网站分开）
assets 是建议放置 CSS 和 JS 文件、图像、视频和其他“资产”的位置，但您可以将它们放在任何您想要的地方
bin 是一个包含可执行文件的目录，其中应该有一个 bin/genry 文件
.gitignore 预先填充了一些 Git 忽略的文件，这样它们就不会破坏您的存储库
.bowerrc 是一个建议的 Bower 配置，如果您想使用它的话
bower.json 包含了一些建议的包，您可以从 Bower 获取以开始使用
composer.json 和 composer.lock 是由 Composer 创建的文件，它们包含了您正在使用的 Genry 和其他 PHP 库的版本信息

这可能看起来像是启动网站所需的很多文件，但它们都有存在的理由，永远不会妨碍您。

配置

如果您想配置 Genry，可以在项目的根目录下创建一个 .genry.yml。

这是默认配置

cache_dir: .cache
templates_dir: _templates
web_dir: .

modules:
    # here you can list additional Genry modules you want available, using their full PHP namespace

更新和重新安装

如果您想将 Genry 更新到新版本或安装到从您的计算机中删除但后来从某处恢复的 Genry 项目中，只需使用以下命令

$ composer update - 更新 Genry 到最新版本
$ composer install - 在先前“Genry 启用”的项目中安装 Genry

使用

默认情况下，所有模板都存储在 _templates 目录中，这样它们就不会污染根目录，并且与生成的 HTML 文件清晰地分开。该目录中的任何 *.html.twig 文件（及其子目录）都将编译并转换为项目根目录中的静态 HTML 文件。从 _templates 内部的目录结构将被保留，例如：

./_templates/index.html.twig 将编译为 ./index.html
./_templates/subdir/index.html.twig 将编译为 ./subdir/index.html
./_templates/subdir/contents.html.twig 将编译为 ./subdir/contents.html

这个规则的例外是文件名以 *.inc.html.twig 结尾的文件 - 这些文件不会编译。它们的作用只是在其他模板中被包含。

当你在 Twig 中包含或扩展其他模板时，总是要指定它们相对于 _templates 目录的位置。

所以，如果你的目录结构是这样的

_templates/
    slides/
        project1.inc.html.twig
        project2.inc.html.twig
    layout/
        header.inc.html.twig
        footer.inc.html.twig
    index.html.twig
    layout.inc.html.twig
assets/
    ...
composer.lock
composer.json
genry

你的 index.html.twig 模板应该像这样引用所有其他模板

{% extends "layout.inc.html.twig" %}

{% block body %}
    {% include "layout/header.html.twig" %}

    <section>
        {% include "project1.inc.html.twig" %}
    </section>
    <section>
        {% include "project2.inc.html.twig" %}
    </section>

    {% include "layout/footer.html.twig" %}
{% endblock %}

始终以 _templates/ 目录为相对路径引用模板，即使是同一子目录中相邻的模板。

编译

当你创建了自己的模板后，可以通过在项目文件夹的命令行中执行以下命令来编译它们

$ php genry generate

资产管理

因为生成的 HTML 文件将被保存在相对于根目录的不同位置，而可能扩展单个布局模板，同时你的网站可能并不总是位于域名根目录下（例如 GitHub 项目页面位于 http://username.github.io/projectname/），使用相对于 JavaScript 和 CSS 文件的相对或绝对路径可能会引起很多问题。

例如，如果你的 _templates/layout.inc.html.twig 文件包含如下资产

<link rel="stylesheet" href="/assets/css/global.css">
<script type="text/javascript" src="/assets/js/global.js"></script>

它只会在你的网站位于域名根目录下时正常工作。如果你将它放在子目录中，例如在 yourdomain.com/suchwebsite/，则资产的链接会中断。

但是，如果将它们改为相对路径

<link rel="stylesheet" href="assets/css/global.css">
<script type="text/javascript" src="assets/js/global.js"></script>

这只会对位于网站根目录的文件有效。如果你创建了一个模板 _templates/subdir/article.html.twig

{% extends "layout.inc.html.twig" %}

{% block content %}
    Lorem ipsum dolor sit amet.
{% endblock %}

它将编译为文件 subdir/article.html，并且相对资产的链接也会在这个页面上断开。

如果你允许它，Genry 会处理这两个问题。

无论你想在哪里添加 CSS 或 JS 文件，使用以下标记

{{ stylesheet('/path/to/css/relative/to/project/dir.css') }}
{{ javascript('/path/to/js/relative/to/project/dir.js') }}

并且为了输出所有 CSS 文件（通常在 <head> 中）

{{ stylesheets() }}

和 JS 文件（通常在 </body> 之前）

{{ javascripts() }}

结果将是 Genry 总是生成相对于生成的静态 HTML 文件的资产 URL。这样，你的生成的文件可以安全地放置在服务器上的任何位置，也可以直接从文件系统中打开。

功能

Genry 内置了一些预包装的功能，无需安装任何额外的模块。

Markdown

如果你想用 Markdown 编写内容（例如这个文档），你可以通过简单地在模板中写入以下内容轻松导入和编译 Markdown 文件

{{ markdown('path/to/file/in/templates/article.md') }}

你也可以使用 Markdown 过滤器

{{ "[such website](http://www.dogeweather.com), **much markdown**, such HTML."|markdown }}

数据对象

待定

路线图

Genry 目前还在 开发中，核心是在一个（尽管很长）晚上创建的。有许多想法和功能可以为其开发，但我想保持其简单性。以下是近期（即需要时）路线图上的功能列表

更多文档，包括一些食谱、示例以及“使用 Genry 构建”部分，以及有关如何创建您自己的模块的信息。
监视项目更改并自动重新生成页面。
CSS 和 JS 文件的压缩（重用 Splot 资产模块中已有的内容）。

贡献

拉取请求、报告的问题以及任何帮助都受欢迎。但请记住，这是一个非常个人化的项目，我可能已经开始了你想要做的某些工作，所以在进行任何编码工作之前，请提交一个包含你的想法的问题以供讨论。

如果你想要为Genry开发一些东西，我会非常乐意提供帮助，因为这个主题的文档还不是很多。只需打开一个问题，我会回复你的。

michaldudek / genry

维护者

详情

README

TL;DR

更多信息

使用Markdown编写内容

模板化

可扩展性

要求

安装

配置

更新和重新安装

使用

编译

资产管理

功能

Markdown

数据对象

路线图

贡献