Simple Website Framework

Shortcodes

Tuesday October 20th, 2026

Written by Scary le Poo

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 as loop="true".
  • Shortcodes that accept booleans take true/false, yes/no, on/off or 1/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 via enclosure or media: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 to pages/ 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-md layouts as well as page-html.
  • If src is missing, a visible Video 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"]
AttributeDefaultDescription
titlenoneA heading above the list.
countstrueShow the number of posts after each feed.
classnoneAdded 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 HTML
  • formatDate($date, $format) — normalises a date string (see Helper Functions)