PageFactory (Kirby Plugin)

Page

This chapter is about writing a page. First off, this means defining the content, text, images, widgets etc.

Occasionally, it also means applying styling etc.

TXT-File

The meta-file or text-file (.txt) is used by Kirby to define the page's name (i.e. Title:) and to select a template.

→ For PageFactory to work, this file must be called z.txt (resp. z.en.txt etc. in a multi-lang app).

If you call it anything else, Kirby selects whatever template matches (default or template with same name), thus leaving PageFactory out of the game.

 

Note: why 'z.txt'?
Sometimes there are multiple .txt files present in a page folder, e.g. if you use images with meta information.

Kirby is pretty clever in spotting the right .txt file as the meta-file. However, in rare cases this can go wrong.

In such cases, the alphabetically last file is chosen. Thus, 'z' has the best chance to overcome mentioned problem.
Moreover, files beginning with 'z' will be listed last in folders, so they are out of the way.

MD-Files

When working with PageFactory you define page content in markdown files inside page folders.

File extension: .md.

Multiple MD-Files

If PageFactory finds multiple markdown files in a page folder, it simply renders them all.

Their filename have no significants apart of defining the rendering sequence.

The content of each file will be wrapped in a <section> tag. These tags automatically get ID and Class attributes for styling.

Note: if ever needed, you can select another wrapper tag by using option wrapperTag: mytag in Frontmatter.

Templates

PageFactory uses Twig as Template Engine. Thus, the template site/templates/z.twig used by PageFactory follows Twig syntax, rather than raw PHP. The Twig template can use a wide variaty of "page fields" (resp. variables) prepared by PageFactory.

In most cases you won't need to worry about that as the default template provided by PageFactory covers basic needs.

The most important variable for Twig is page.pageContent. That variable contains the actual content of a page as assembled by PageFactory. Thus, in the Twig template you'll find the line

{{ page.pageContent | raw }}

All the rest is nuts and bolts shared by other pages (using the same template).

Frontmatter

The term "Frontmatter" is used to refer to meta-data placed inside MD-Files. The syntax is the same as in Kirby's .txt files.

Meta-data let's you define and control a variaty of things, such as

  • defining CSS or JS instructions embedded in the page
  • loading of JS/CSS files
  • defining variables
  • defining header elements, such as description, keywords or robots etc
  • and much more…

→ See chapter Frontmatter.

 

Note:
In Frontmatter's CSS/SCSS definitions, you can use special selectors #this and .this.
→ They will be replaced with selectors targeting the content of just that particular source file.

Variables

As seen above, PageFactory defines a number of Variables, most notably pageContent. But there are many more.

There are ways by which you can define your own variables or override system variables.

In Markdown files you use variables as {{ varname }}.

In Twig templages you need to write as {{ page.varname |raw }} instead.

 

Note:
Templates are compiled by Twig. Twig supports a powerful and versatile syntax. But at the same time Twig has some restrictions: you cannot nest variables and they are not (directly) language aware.

For these reasons, PageFactory uses its own template engine, which uses the same basic syntax as Twig. (Thus the variable {{ page.pageContent }} used in templates has variables already replaced.)

→ See separate chapter Variables

Macros()

PageFactory's template engine supports Macros (which correspond to and are compatible with Twig's functions).

Macros are conceptually similar to Variables in that you can look at them as "parameterized Variables". Each one is implemented as a PHP-function and resides in its own file in a specific folder.

PageFactory ships with a number of useful macros, such as lorem(), import() or nav(), just to mention a few.

Typically, you'll define your own Macros for specific content that cannot be handled by Markdown or Variables. They serve a similar purpose as Kirby's Snippets.

→ See chapter Macros

Preview: at a later stage there will be a PageFactory-extension-mechanism, where extensions can provide additional functionality and Macros, etc.

Markdown Plus

(The original) Markdown is a simple and useful notation to define webpage content. It can be automatically translated to HTML. Kirby makes use of markdown – like many other content management systems.

This way, authors are not required to code content in HTML notation – which is not very user-friendly, to put it mildly.

Standard Markdown (including commonly known extensions) are rather limited. Which is good – but sometimes too limiting.

That's why PageFactory relies on a variant called MarkdownPlus. That supports few but powerful additional features. Due to these extensions, in many situations there is no need for dedicated templates, significantly simplifying web authoring.

→ See MarkdownPlus Documentation.

Multi-Language Content

PageFactory supports creation of web-pages in multiple languages. That support goes beyond the level provided by Kirby itself.

→ See chapter Multi-Language Content