ordinalm / gyokuto
A static site generator module, using PHP, Markdown, and Twig.
Requires
- php: ^8.1
- ext-gd: *
- michelf/php-markdown: ^1.9
- monolog/monolog: ^2.1
- symfony/yaml: ^5.0
- twig/markdown-extra: ^3.0
- twig/twig: ^3.4.3
This package is auto-updated.
Last update: 2024-04-11 12:39:30 UTC
README
Overview
Gyokuto uses PHP and Twig to render local Markdown content to produce a static site. It can be used as is, or combined with other PHP modules.
Installation
Composer (recommended)
In your project, install the module with:
composer require ordinalm/gyokuto dev-master
Page rendering
Start a build with:
vendor/ordinalm/gyokuto/bin/build
By default, this will look for content in ./content
and output to ./www
, reading config from ./gyokuto.yml
.
Use -o /path/to/config/YOUR_CONFIG_FILE.yml
to use a different config file on startup.
Use -v1
for verbose output.
Markdown page structure
Gyokuto will process flat Markdown files without metadata with no problems, but you may wish to include metadata using the Multimarkdown page header system.
---
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 headers are parsed as YAML data and are then available to Twig templates.
You may also include Twig code within page content - e.g.
---
foo: bar
---
The value of "foo" is "{{ current_page.meta.foo }}".
will render as
The value of "foo" is "bar".
See below for the values that are automatically available to Twig.
Special metadata variables
The following metadata variables have special meaning to Gyokuto.
draft
- if set to a value evaluating totrue
, this page will not be copied over or included in any page lists or indexes.template
- this determines the template used to process this page. If not set, the value isdefault.twig
.path
- if set, the page will be output to this path relative to the root of the output directory. This can also change the file extension e.g.path: "sitemap.xml"
hidden
- if set to a value evaluating totrue
, the page will be created in output, but won't be included in the indexing process, so will not appear in eitherindex
orpages
lists (see Twig variables, below).
Build process
Compile phase
All files in the content directory are marked as either parsable (.md
or .markdown
extension) or to simply be copied.
All parseable files are parsed, their metadata included in the overall page list, and, if appropriate, the metadata used to construct indexes.
Build phase
Non-parsable files are simply copied unchanged to the same filename in the output directory. These can be of any type - images, CSS, PHP code etc.
Markdown files are parsed with the following steps:
- All Twig code in the page body is evaluated.
- The page body is converted into HTML from Markdown.
- The chosen Twig template for that page, as defined in the
template
metadata value, is run.
Twig variables available during rendering
current_page
- the page being rendered nowmeta
title
- an unescaped string, taken either from thetitle
Markdown header field or from the filenamedate
- a UNIX timestamp taken either from thedate
field in the Markdown header- any other variables set in the page's Markdown header
path
- from site root, beginning with/
content
- processed HTML from page Markdown body (not available within pages)
pages
- all pages in the build, keyed by path, in descending order ofdate
, do not includecontent
. Can be used to look up page metadata referred to in indexes.meta
title
date
path
config
- all values declared in the config file
If any metadata fields have been specified for indexing using the index
value in the config file, they will appear as:
index
- keyed by the meta variable being indexed, sorted by the value of that variable- key 1
- path 1
- path 2
- ...
- key 2
- path 3
- ... ...
- key 1
The paths can be used to look up page metadata in the pages
list.
Example: list of all pages by tag
In gyokuto.yml
:
index: [ "tags" ]
In a page or template:
{% 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 %}