PageFactory (Kirby Plugin)

Good to Know

Frontmatter

The Frontmatter section is optional. But if present, must be at the top of a .md file. It can contain several Frontmatter elements.

Each Frontmatter element must start with a keyword: and end with a line ----. The value in between can occupy multiple lines.

The syntax is:

keyword:
value...
----
...

Most important keywords are:

  • css or scss
    → to inject styling instructions
  • js or jq
    → to inject script code
  • assets
    → to load .css and .js files
  • variables
    → to add local variables, which can be used with the page as {{ x }}

→ See chapter Frontmatter.

Example

scss:
body { color: blue; }
.page { padding: 1em; }
----
js:
const x = 1;
----
// Page content in MarkdownPlus from here on:
# Home
...

SCSS

SCSS (also know as SASS) is a stylesheet language that compiles to CSS. It lets you to use variables, nested rules, mixins, functions, and more.

PageFactory comes with a SCSS-compiler on board. Thus, you can use SCSS style sheets or use SCSS code within Frontmatter etc.

→ See SCSS Doc

MarkdownPlus

PageFactory provides a compiler for an extended variant of Markdown, named MarkdownPlus.

MarkdownPlus provides few but powerful syntax elements beyond Markdown/MarkdownExtra, such as DivBlocks, Tabulators, Attribute Injection and more.

→ See MarkdownPlus Documentation.

Multi-Langauage Support

PageFactory extends Kirby's multi-language support.

Beyond defining entire source files for different languages, you can define language dependent content in a more fine grained way:

  • per source file
  • per text segment (titles, paragraphs, DivBlocks etc.)
  • per Variable (as in {{ varname }})

Language Variants

PageFactory supports "language variants". Many languages distinguish between formal and informal speech, for instance. PageFactory lets you maintain such variants in parallel with minimum additional effort.

→ See chapter Multi-Language Content.

 

BTW: All elements and widgets shipped with PageFactory come with translations for English and German (formal and informal), ready for use.

URL Patterns

Paths and URLs within a website can be ambiguous or at least confusing, in particular when they should be relative to the current page. Moreover, they depend on the context, namely whether used locally for filesystem accesses (in PHP) or remotely in HTTP(S) requests (in HTML).

→ You can use them in both contexts, PageFactory will sort out the details.

PageFactory supports a simple pattern for unambiguous paths and URLs:

~/          app-root
~page/      current page
~assets/    content/assets/
~cache/     site/cache/pagefactory/
~config/    site/config/
~custom/    site/custom/
~data/      site/custom/data/
~download/  download/

You can use these patterns both in URLs and in filesystem paths (i.e. in custom macros). PageFactory will resolve them in the propre way. If used in URLs*), they will be prepended with the absolute path to the app-root.

Examples:

![Image caption](~page/pic.jpg)     image file in current page folder
<link href='~assets/css/-my.css'>   stylesheet in assets/css/ folder

*) Of course, some of the patterns like ~cache/ make no sense in URLs.

Asset-Loading

Auto-Loading Folders

CSS/JS files in specific folders are loaded automatically.

  • content/assets/css/autoload/
  • content/assets/js/autoload/
  • current page folder ~page/

That means, the necessary HTML code is automatically injected into the <head> tag (via variable {{ pfy-head-injections }}).

 
Check that custom assets have been loaded

→ If the test worked, you'll see colored text below:

This text is blue due to the stylesteet content/assets/css/scss/my.scss
(which was loaded via Frontmatter as assets: ~assets/css/-my.css).

 

Explicit Asset Loading

In the Frontmatter section of each .md source file you can state assets which will be queued and finally loaded by the browser.

Example:

assets: 
~assets/css/my.css
~assets/ds/my.js
----
HTML...

In Macro Definitions

If ever you write your own Macro, you can queue assets for loading by PHP code:

PageFactory::$pg->addAssets('~assets/js/sample.jq');
PageFactory::$pg->addAssets('~assets/css/-sample.css');

Note:
if placed in content/assets/css/scss/, .scss files will be compiled automatically to CSS.
Compiled file names have a leading "-", thus content/assets/css/scss/my.scss is compiled to
content/assets/css/-my.css.

Note:
If a CSS filename contains -async (as in site/assets/css/-my-async.css) that file is loaded by the browser asynchronously. I.e. the browser does not stall until the file is loaded but proceeds rendering the page.

Commenting Out

In various situations you can easily comment out elements:

Within MarkdownPlus:
//… or /* … */
→ C-style comments
__END__
→ cuts off rest of file
Within YAML-files:
#…
→ skip line
__END__
→ cuts off rest of file
In Folders:
#filename.xy
→ file will be ignored
In Twig Templates:
{# …}
→ text will be skipped

URL Commands

PageFactory supports various URL commands invoked by url?command. They are meant to be useful while developing a website.

Note: most of them only work while you are logged in as admin or working on a localhost.

?help                   this information
?variables              show currently defined variables
?macros                 show currently defined macros()
?lang=xy                activate given language
?login                  log in user
?logout                 log out user
?debug                  activate debug mode
?localhost=false        mimick running on a remote host
?print                  starts printing mode and launches the printing dialog
?printpreview           presents the page in print-view mode
?reset                  resets all state-defining information: 
                        caches, tokens, session-vars.

→ ?help

PageFactory