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]
Attribute rules:
- Values go in double or single quotes. Each style may contain the other, so
caption="Scary's trailer"works. - A bare word with no value is a flag and is read as
="true":[video src="v.mp4" loop]is the same asloop="true". - Shortcodes that accept booleans take
true/false,yes/no,on/offor1/0.
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
Off by default. To use it, set in config/config.php:
$allowPhpShortcode = true;
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]
Why it is off: this shortcode turns "can change a page" into "can run any code on the server". While it is off, a [php] block in a page renders as an HTML comment instead of running, and the editor refuses to save, publish or preview content that contains one — so neither a mistake nor a script riding a logged-in editor session can put code into a page. Switch it on only if you need it and you are the only person who can change page content, and switch it off again when you are done.
Other notes:
- There is no sandboxing or function whitelist.
- Syntax errors in the evaluated code will cause a fatal error on that page.
[video] — Play a Video Hosted on Your Site
Embeds a video file that lives on your own server in a responsive frame that holds its shape before the file loads, so the page doesn't jump. Output is a plain HTML5 <video> element — no player library, no third-party embed, no tracking. Layout comes from the Video block in css/base.css, so it works in every theme, and themes can restyle the .swf-video classes.
This is for files you host. For YouTube or Vimeo, paste their embed code into the page directly.
Simplest use:
[video src="videos/trailer.mp4"]
The path can also go between the tags, like [rss]:
[video]videos/trailer.mp4[/video]
Everything at once:
[video src="videos/trailer.webm, videos/trailer.mp4"
poster="images/trailer.jpg"
ratio="16:9"
width="900"
caption="Launch trailer"
captions="videos/trailer.en.vtt"
start="12"
loop muted]
Attributes:
| Attribute | Default | Description |
|---|---|---|
src |
— | Path or URL of the video file. Required (or put it between the tags). Comma-separate several encodings, best first, and the browser plays the first one it supports: src="trailer.webm, trailer.mp4". Recognised types: mp4, m4v, webm, ogv, ogg, mov. |
poster |
none | Image shown in the frame before playback starts. |
ratio |
16:9 |
Shape of the frame: 16:9, 4:3, 21:9, 9:16, or any width:height. auto sizes the frame to the file itself once it loads. |
fit |
contain |
contain letterboxes a video whose shape doesn't match the frame; cover fills the frame and crops the edges. |
width |
full width | Maximum width: 640 (pixels), 60%, 40rem. The frame is centred when it is narrower than the content column, and never wider than it. |
caption |
none | Text shown under the video in a <figcaption>. |
title |
the caption | Accessible name for screen readers, if you want it to differ from the caption. |
captions |
none | Path to a WebVTT subtitle file (.vtt). Shown by default; viewers can switch it off in the player. |
captionslang, captionslabel |
en, English |
Language code and menu label for the subtitle track. |
start |
0 |
Start position in seconds. Uses a media fragment (#t=12) on the source URL, so it needs no JavaScript. |
controls |
true |
Show the browser's play/pause/volume controls. |
autoplay |
false |
Start playing as soon as it can. Forces muted, because browsers block autoplay with sound. Visitors who have asked their system for reduced motion get the video paused with controls instead. |
loop |
false |
Start again when it reaches the end. |
muted |
false |
Start with the sound off. |
preload |
metadata |
How much to fetch before the visitor presses play: none, metadata (duration and first frame) or auto (the whole file). Autoplay defaults to auto. |
nodownload |
false |
Hide the download button from the browser's controls. A deterrent only — the file is still a plain URL. |
class, id |
none | Added to the outer <figure> so a theme or page can style one video differently. |
Common recipes:
A silent looping background clip, like a GIF but much smaller:
[video src="videos/hero.mp4" autoplay loop controls="false" fit="cover" ratio="21:9"]
A phone-shaped vertical clip, centred:
[video src="videos/demo.mp4" ratio="9:16" width="360" caption="Recorded on a phone"]
Two encodings with subtitles:
[video src="videos/talk.webm, videos/talk.mp4" captions="videos/talk.en.vtt" poster="images/talk.jpg"]
Output structure:
<figure class="swf-video">
<div class="swf-video-frame">
<video controls preload="metadata" playsinline>
<source src="videos/trailer.mp4" type="video/mp4">
<p>Your browser can't play this video. <a href="videos/trailer.mp4">Download it instead</a>.</p>
</video>
</div>
<figcaption>…</figcaption>
</figure>
The frame's shape is set with the --swf-video-ratio custom property and its maximum width with --swf-video-width. width adds swf-video-sized, ratio="auto" adds swf-video-auto, and fit="cover" adds swf-video-cover to the figure. A theme that wants a different default shape for every video can set --swf-video-ratio on .swf-video-frame in its own stylesheet.
Notes:
- Paths are relative to the site root, the same as image paths in page metadata. A
videos/folder next topages/is a sensible home. - The output is written as a single line so the Markdown parser treats it as one HTML block; it works in
page-mdlayouts as well aspage-html. - If
srcis missing, a visibleVideo error: no src given.message is printed in its place rather than failing silently. - Several videos on one page are fine; the small reduced-motion script for autoplay is printed once at most.
[feeds] — List the Site's RSS Feeds
Renders the feeds the site offers — the whole-site feed and one per category — as a list with post counts. It is built from the categories that exist, so a new category appears on its own. Put it on an archives page, in a footer column or on a "Subscribe" page.
[feeds] [feeds title="Subscribe" counts="false"]
| Attribute | Default | Description |
|---|---|---|
title | none | A heading above the list. |
counts | true | Show the number of posts after each feed. |
class | none | Added to the <ul>. |
Output: <ul class="swf-feeds"> with one <li> per feed, each an <a type="application/rss+xml"> followed by <span class="swf-feed-count">. See The RSS Feed.
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 (a bare flag like loop arrives as 'loop' => 'true'), 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',
'video' => 'shortcode_video',
'feeds' => 'shortcode_feeds',
'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)