Skip to content

Pressroom Engineering

Shortcodes, Leaflet Maps, and JSON-LD: Turning Plain Markdown into Multi-Theme Publications

From Pressroom Engineering · 6 articles · latest

Diagram showing Markdown and shortcodes flowing through Pressroom AST engine into three themes
Author once in Markdown without inline color hacks: Pressroom adapts layout, responsive WebP media, interactive maps, and JSON-LD per theme.

The fastest way to ruin a multi-tenant publishing platform is to let writers—especially AI agents—emit raw HTML full of inline styles. When we ran our first dozen posts through our Blogger Agent onto Pressroom, the markup looked fine on a white-background Blogger page and immediately broke on Pressroom's dark portfolio theme. White #f0f7ff tip boxes glowed like headlights on #0e0e10 charcoal, and hardcoded #666 figure captions turned nearly unreadable.

That failure forced us to draw a hard architectural boundary between authoring intent and theme presentation. Today, Pressroom powers nine active blogs across three radically different themes—dark portfolio (wikantik, pressroom), editorial journal (investing, marketupdates, agenticdev), and warm-cream travel (sandiego, foothills, exploringberlin, berlinwiki)—from one canonical CommonMark + shortcode authoring format.

Why Inline HTML Colors Always Rot

Whenever an agent writes <div style="background-color: #f0f7ff; border-left: 4px solid #0066cc;">, it implicitly assumes a light background. That assumption dies the moment a publication switches themes or a reader enables prefers-color-scheme: dark in journal. Worse, inline style="..." attributes defeat CSS custom properties (--pf-surface, --qj-ink, --tg-accent) and force brittle CSS hacks downstream.

Pressroom's answer is straightforward: author in CommonMark Markdown, use GitHub alerts for callouts, and let the rendering pipeline own colors, syntax highlighting, and spacing.

> [!TIP]
> **Keep Presentation Out of Body Text:** A GitHub alert compiles into
> `.markdown-alert-tip` with light-dark CSS tokens and inline SVG icons,
> adapting cleanly across Portfolio, Journal, and Travel.

When entries preview or the permalink controller renders that block, Pressroom generates semantic .markdown-alert containers, fenced .pressroom-code blocks with line numbers and a copy button, and responsive striped tables—without a single hardcoded hex color in the stored post.

Shortcodes as Typed Layout Primitives

Plain Markdown handles prose, lists, and code well, but real publications need responsive media figures, multi-pin itinerary maps, and structured FAQs. Instead of asking authors to hand-craft fragile Leaflet <script> tags or <picture> elements, Pressroom expands four server-side shortcodes at render time:

ShortcodePurposeRendered Output & Theme Integration
[image id=... caption="..."]Responsive imported mediaEmits <figure> with WebP srcset (480w, 960w, 1376w) and BlurHash placeholder
[map] + [pin]Multi-stop travel itinerariesHydrates an interactive Leaflet map plus numbered accessible stop list
[faq] + [q] / [a]Structured visitor logisticsRenders collapsible Q&A and feeds FAQ_PAGE structured data
[video url="..."]Embedded walkthroughsTheme-framed responsive container without layout shift

Look at how [map] transforms our regional travel hubs on San Diego Local Wiki and Berlin Local Wiki. Previously, our pipeline embedded a single static Google Maps image card per landmark. For multi-stop routes—like connecting eight Cold War checkpoints along Berlin's S-Bahn or linking Coronado Ferry to Balboa Park—a static PNG cannot show spatial flow.

In Markdown, an author writes only the coordinates and stop names:

[map]
[pin lat=32.7174 lng=-117.1731 label="Broadway Pier Ferry Landing"]
[pin lat=32.7316 lng=-117.1522 label="Balboa Park California Tower"]
[pin lat=32.7289 lng=-117.1636 label="Spruce Street Suspension Bridge"]
[/map]

At render time, Pressroom translates that block into a div.travel-map container carrying a serialized JSON data-pins payload plus a semantic <ol class="travel-map-pins"> fallback list. If JavaScript is blocked or an RSS reader strips scripts, the reader still gets the ordered itinerary; in a live browser, Leaflet boots cleanly, auto-fits the bounding box across every pin, and obeys the site's strict Content Security Policy without inline eval or third-party script sprawl in stored entry text.

AST Image Promotion: Pictures by Default Without Duplication

In Pictures by Default, we detailed how Pressroom inspects the CommonMark AST to import external images (importExternalImages) and generate responsive WebP renditions. The subtle rule every publisher should understand is how featured image promotion interacts with shortcodes:

  1. When you import an asset via media import, Pressroom deduplicates by byte hash in the weblog's default directory and returns a canonical media_id.
  2. Passing featuredImageId wires up theme index cards, the site-wide Discovery hero, og:image, and the XML image sitemap.
  3. Placing [image id=<media_id> caption="..."] in the body renders that exact asset responsively inside the article—and Pressroom suppresses any redundant duplicate hero banner above it.

Note

No Plain <img> Tags in Production Posts: Running audits seo_entry flags plain <img> elements with image_not_responsive because readers end up downloading full 2400px master files on mobile connections. Switching to [image id=...] eliminates that warning and cuts mobile image payload by 70%+.

First-Class JSON-LD Beyond Generic BlogPosting

Search engines treat a coastal hiking guide, a weekly engineering architecture note, and an upcoming neighborhood workshop differently—if your markup tells them what the page actually is. Pressroom allows every entry to specify jsonLdType alongside typed domain fields:

  • TECH_ARTICLE: Used across wikantik, pressroom, and agenticdev so code-heavy architecture posts emit TechArticle structured data aligned with Schema.org TechArticle and Google Search structured data guidelines.
  • TOURIST_ATTRACTION & TOURIST_TRIP: Paired with geoLatitude and geoLongitude on sandiego, foothills, exploringberlin, and berlinwiki so single landmarks and multi-stop transit itineraries emit valid geographic JSON-LD.
  • EVENT: Accepts wall-clock eventStart, eventEnd, and eventLocation in the weblog's own timezone.

Separation of Concerns Pays Off on Day Two

When we built this layer, it felt tempting to let agents emit whatever bespoke HTML looked clever in a single draft. Resisting that temptation is why we can refine a theme's typography, switch between light and dark palettes, or enforce responsive WebP delivery across 170+ published posts without touching a single stored entry body. Author in clean Markdown, lean on Pressroom's shortcodes for rich primitives, and let the theme layer do its job.

Keep reading

Comments