The framework includes a shortcode system that lets you embed dynamic functionality directly inside your page content files. Shortcodes are processed before Markdown rendering, so they work in both Markdown and HTML page layouts.
The shortcode parser lives in required/shortcode-parser.php and is loaded automatically on every request. Individual shortcode functions are stored in required/shortcode-functions/ as separate PHP files, which are all auto-loaded by the parser.
Shortcode Syntax
Shortcodes follow a simple syntax. They can be self-closing (no content between tags) or enclosing (wrapping content between an opening and closing tag).
Self-closing with attributes:
[shortcode_name attribute="value"]
Enclosing with content:
[shortcode_name] content goes here [/shortcode_name]
Enclosing with both attributes and content:
[shortcode_name attribute="value"] content goes here [/shortcode_name]
Built-in Shortcodes
[rss] — Embed an RSS Feed
Fetches an external RSS feed and renders it as an HTML list of items. Useful for displaying posts from another site, a podcast feed, or your own site's RSS output.
Attributes:
| Attribute | Required | Description |
|---|---|---|
url |
Yes | The full URL of the RSS feed to fetch |
limit |
No | Maximum number of items to display. Defaults to all items |
Example — fetch 5 items from a feed:
[rss url="https://example.com/?rss" limit="5"]
Output structure:
Each feed item is wrapped in a <div class="rss-item"> and contains:
<div class="rss-title">— linked item title<div class="rss-date">— publication date<div class="rss-image">— thumbnail image (if the feed provides one viaenclosureormedia:content)<div class="rss-description">— item excerpt/description
The whole output is wrapped in <div class="rss-feed-container"> which you can target with CSS.
[pre] — Preformatted Text Block
Wraps content in a <pre> tag with HTML entities escaped. Use this to display code or any content where whitespace and special characters should be preserved exactly as written.
Example:
[pre]
function hello() {
echo "Hello, world!";
}
[/pre]
This is equivalent to writing <pre> directly in an HTML layout, but is more convenient in Markdown pages where raw HTML blocks can sometimes be tricky.
[php] — Execute PHP Code
Evaluates PHP code and inserts the output into the page at the point where the shortcode appears. The code runs via eval() inside an output buffer, so anything you echo will appear in the page.
Example:
[php]
echo "The current year is: " . date('Y');
[/php]
Important notes:
- This shortcode executes arbitrary PHP. Only use it in page files you control. Anyone with write access to
pages/can run any PHP code on the server using this shortcode. - There is no sandboxing or function whitelist.
- Syntax errors in the evaluated code will cause a fatal error on that page.
Adding a New Shortcode
New shortcodes are easy to add. All files in required/shortcode-functions/ are auto-loaded, so you just need to:
1. Create a new file in required/shortcode-functions/, e.g. my-shortcode.php.
2. Define your function inside it. The function receives two arguments: an associative array of attributes, and a string of inner content (empty string if the shortcode is self-closing):
<?php
function shortcode_myshortcode($attributes, $content) {
$color = isset($attributes['color']) ? $attributes['color'] : 'blue';
return '<span style="color:' . htmlspecialchars($color) . '">' . htmlspecialchars($content) . '</span>';
}
?>
3. Register the shortcode in the $shortcodes array inside required/shortcode-parser.php:
$shortcodes = [
'rss' => 'shortcode_rss_feed',
'pre' => 'shortcode_pre',
'php' => 'shortcode_php',
'myshortcode' => 'shortcode_myshortcode', // add this line
];
4. Use it in any page file:
[myshortcode color="red"]Hello![/myshortcode]
Helper Functions Available to Shortcodes
Since shortcode functions are loaded within the framework's context, they have access to all PHP functions defined elsewhere in the framework, including:
from_markdown($string)— converts a Markdown string to HTMLformatDate($date, $format)— normalises a date string (see Helper Functions)