Whether you use Blogger or WordPress, Github Pages or Ghost — even if you painstakingly craft every tab stop and angle bracket of your pure-HTML static site — if you post “actual play” reports of your role-playing adventures online, then you surely know the incessant struggle of separating narration from mechanics and die rolls from commentary. Woe are we who endure these pains and wish there were some other way! Surely some kind soul will deliver us from this blogging purgatory, this persecution of play reports, the secret, sorrowful soliloquy of our social shares, this —
Anyways…
Introducing ap_shortcodes.js
A drop-in JavaScript solution for formatting your RPG actual-play reports. Add 3 lines to your website’s <head>
and you’re good to go.
- Wrap your narrative bits in
[story]
tags - Set die rolls apart, inline or block, with the
[dice]
tag. - Hide mechanics and more behind expanding
[spoiler]
tags.
A fork of Shortcode.js, which does all the heavy lifting, ap_shortcodes.js is simply a definition and styles for tags to meet the most common actual play formatting needs.
Usage
- Include references to shortcode.js, ap_shortcodes.js, and ap_shortcodes.css in your page’s
<head>
tag.
<script src="https://cdn.rawgit.com/sdsalyer/ap_shortcodes.js/master/js/shortcode.js"></script>
<script src="https://cdn.rawgit.com/sdsalyer/ap_shortcodes.js/master/js/ap_shortcodes.js"></script>
<link rel="stylesheet" href="https://cdn.rawgit.com/sdsalyer/ap_shortcodes.js/master/css/ap_shortcodes.css">
- (Optional) If you downloaded the files, alter ap_shortcodes.js to add/edit shortcodes. Alter ap_shortcodes.css to add/edit the associated styles.
- Use the shortcodes in your actual play report, then ooh and ahh at the results!
What is an Actual Play and Why Should I Care?
An “actual play” report, or AP, is a blog or forum post sharing the details of a pen and paper role-playing adventure for others to enjoy online. These posts typically involve the expected blog-style setup and commentary amidst a mixture of narration and game play elements. It’s not always easy or straightforward for blog authors to distinctly style (or obfuscate, if you’re trying to avoid spoilers) these separate elements to better distinguish them for readability, aesthetics, or even dramatic effect.
If you post your actual plays online and are permitted to add JavaScript to your site, ap_shortcodes.js can simplify this task for you. It supplies the styles to distinguish the separate portions of your actual plays, packaged in BBCode / WordPress-style shortcodes, convyed by JavaScript.
What are Shortcodes and Why Should I Care?
The term “shortcode” is attributed to WordPress, but if you’ve ever posted on an internet forum or message board then you’ve probably seen or used BBCode — those tags in square brackets that allow you to format your post, insert a link, or create an enormous chain of animated gif emoticons to troll your pals.
Same idea here, but we’re focused on a drop-in solution for most any blog or website which is tailor-made to actual play posts.
Why JavaScript?
ap_shortcodes.js uses common client-side JavaScript to read your post and replace the shortcode tags, rather than server-side scripts that you may not have the expertise or permissions to implement, depending on your blogging platform or web host.
JavaScript has its drawbacks — it runs every time the page loads, and could potentially be slow to parse your entire post, not to mention your site users could simply have it turned off entirely (in which case, the tags would be visible in your post and the styling would not be applied)!
That being said, very few users browse the web without JavaScript enabled and most modern browsers are extremely capable and fast in interpreting and executing JavaScript. Consider these things
Check it out on GitHub
Head on over to GitHub to check it out. If you’re JavaScript-savvy, contribute your shortcodes in the Wiki, or if you run into bugs, create an issue ticket. If you want to contribute to the code, create a topic/feature branch and submit a pull request to the develop branch (I tend to follow the nvie method here). If there is an issue in shortcode.js, consider contributing there.
The project is licensed under the MIT License, inherited from shortcode.js.
An Actual Play Example
Wisps of Time is a WordPress site, and I actually already have plugins installed that use the [dice] and [spoiler] tags, so it’s a bit difficult to post the actual play example here. You can check out the example.html that’s in the GitHub repo, or head over to this Blogger site I created, just for this very purpose!
Check it out on Blogger!