AstroPress Shortcodes : Dynamically Insert Sidebar Products in Articles

One of the most powerful monetization features in AstroPress is the shortcode system. While other platforms make you manually insert product widgets into every article, AstroPress lets you configure dynamic sidebar products once then they automatically appear on specific articles.

In this guide, I’ll show you exactly how AstroPress shortcodes work, how to configure them, and how to use them to maximize your affiliate earnings without touching your article content.

What Are Shortcodes in AstroPress?

Shortcodes are configuration files that tell AstroPress which products to display in article sidebars. Think of them as smart product placement rules:

• “Show Product A in the sidebar of Article X”
• “Display Products B, C, and D on all weight loss articles”
• “Feature this product bundle on my review posts”

The key benefit: You configure products in a JSON file, and AstroPress automatically inserts them into the right articles. No need to edit MDX files or touch your content.

Why Shortcodes Are Better Than Manual Product Insertion

Let’s compare the traditional way vs. AstroPress shortcodes:

Traditional Method (WordPress, etc.)

1. Open each article
2. Manually insert product widget code
3. Hope you don’t break the layout
4. Want to swap products? Edit every article individually
5. Products scattered across dozens of files

AstroPress Shortcodes Method

1. Create one JSON entry in shortcodes.json
2. Specify which article to target
3. List which products to show
4. Done - products appear automatically
5. Need to update? Change one JSON entry

Result: 10x faster product management, zero risk of breaking articles, and centralized control over all affiliate placements.

How Shortcodes Work: The Technical Overview

AstroPress’s shortcode system has three main components:

1. Shortcode Configuration (/src/content/data/shortcodes.json)

This JSON file defines all your shortcode rules. Each shortcode contains:

• Unique ID - Identifier for the shortcode
• Article slug - Which article to target
• Placement - Where to show products (sidebar or content)
• Priority - Display order when multiple shortcodes exist
• Enabled status - Turn shortcodes on/off without deleting
• Title - Section heading above products
• Products array - List of products to display

2. Shortcode Logic (/src/core/shortcodeLogic.ts)

This TypeScript module handles all shortcode operations:

• Fetching shortcodes for specific articles
• Filtering by placement (sidebar vs content)
• Sorting by priority
• Validating product IDs
• Providing helper functions for templates

3. Shortcode Section Component (/src/components/ShortcodeSection.astro)

This Astro component renders the actual product displays:

• Loads shortcode configuration for current article
• Renders section headers
• Displays product cards using ProductBlockSidebar
• Handles styling and responsive design

Shortcode Configuration: Complete Anatomy

Let’s break down a real shortcode configuration from the AstroPress demo:

json
{
  "id": "weight-loss-general-sidebar",
  "articleSlug": "Puravive Review",
  "placement": "sidebar",
  "priority": 1,
  "enabled": true,
  "title": "Top Weight Loss Picks",
  "products": [
    {
      "productId": "puravive",
      "variant": "sidebar",
      "title": "Featured Product"
    },
    {
      "productId": "ikaria-juice",
      "variant": "sidebar",
      "title": "Editor's Choice"
    },
    {
      "productId": "leanbiome",
      "variant": "sidebar",
      "title": "Best Seller"
    }
  ]
}

Let’s break this down field by field:

id (required)

Unique identifier for this shortcode. Use descriptive names like:

• product-name-sidebar-products
• category-related-items
• article-recommendations

articleSlug (required)

The exact title of the article where products should appear. Must match the article’s title field in frontmatter.

Examples:

• "Alpha Tonic Review"
• "Best Blogging Tools 2025"
• "SEO Guide for Beginners"

placement (required)

Where to display the products:

• "sidebar" - Shows in article sidebar (most common)
• "content" - Inline with article content (future feature)

priority (required)

Determines display order when multiple shortcodes target the same article:

• 1 - Displays first (highest priority)
• 2 - Displays second
• 3 - Displays third, etc.

Lower numbers = higher priority.

enabled (required)

Control visibility without deleting the shortcode:

• true - Shortcode is active and displays
• false - Shortcode is disabled but configuration preserved

This is perfect for seasonal promotions or A/B testing.

title (optional)

Section heading that appears above the products:

• "Related Supplements"
• "You Might Also Like"
• "Top Picks"
• "Editor's Choice"

Leave empty for no heading.

products (required)

Array of product objects to display. Each product contains:

productId (required) - Must match a product ID in /src/content/data/products/

variant (required) - Display style:

• "sidebar" - Compact sidebar card (recommended)
• "card" - Full card layout
• "compact" - Minimal display

title (optional) - Label above this specific product:

• "Featured Product"
• "Best Seller"
• "Editor's Choice"
• "Budget Pick"

How to Create Your First Shortcode

Let’s walk through creating a shortcode step-by-step.

Scenario: You wrote a review of “AstroPress Pro Theme” and want to show related products in the sidebar.

Step 1: Identify Your Products

First, check which products exist in /src/content/data/products/:

• astropress-pro-theme.json
• seo-toolkit-digital.json
• content-planner-template.json

These are your available productId values.

Step 2: Get Your Article Slug

Open your article MDX file and find the title in frontmatter:

mdx
---
title: How to Showcase Affiliate Products in AstroPress
description: ...
---

Your articleSlug is: "How to Showcase Affiliate Products in AstroPress"

Step 3: Create the Shortcode Entry

Open /src/content/data/shortcodes.json and add:

json
{
  "id": "astropress-showcase-sidebar",
  "articleSlug": "How to Showcase Affiliate Products in AstroPress",
  "placement": "sidebar",
  "priority": 1,
  "enabled": true,
  "title": "Featured Products",
  "products": [
    {
      "productId": "astropress-pro-theme",
      "variant": "sidebar",
      "title": "Our Theme"
    },
    {
      "productId": "seo-toolkit-digital",
      "variant": "sidebar",
      "title": "SEO Tools"
    },
    {
      "productId": "content-planner-template",
      "variant": "sidebar",
      "title": "Content Planner"
    }
  ]
}

Step 4: Save and Deploy

That’s it! When you rebuild your site, the article sidebar will automatically show these three products with the heading “Featured Products”.

Advanced Shortcode Strategies

Now let’s explore advanced techniques for maximizing conversions.

Strategy 1: Category-Based Product Display

Create shortcodes that show different products based on article category:

For SEO articles:

json
{
  "id": "seo-category-sidebar",
  "articleSlug": "SEO Structured Data Guide",
  "placement": "sidebar",
  "priority": 1,
  "enabled": true,
  "title": "SEO Tools & Resources",
  "products": [
    {
      "productId": "seo-toolkit-digital",
      "variant": "sidebar",
      "title": "Complete SEO Toolkit"
    }
  ]
}

For monetization articles:

json
{
  "id": "monetization-category-sidebar",
  "articleSlug": "Affiliate Marketing Guide",
  "placement": "sidebar",
  "priority": 1,
  "enabled": true,
  "title": "Monetization Resources",
  "products": [
    {
      "productId": "blog-monetization-course",
      "variant": "sidebar",
      "title": "Monetization Course"
    },
    {
      "productId": "astropress-pro-theme",
      "variant": "sidebar",
      "title": "Professional Theme"
    }
  ]
}

Strategy 2: Funnel-Based Product Sequencing

Use priority to create a conversion funnel:

json
[
  {
    "id": "main-offer",
    "articleSlug": "Product Review Article",
    "placement": "sidebar",
    "priority": 1,
    "title": "Best Choice",
    "products": [
      {
        "productId": "premium-product",
        "variant": "sidebar",
        "title": "Editor's Choice"
      }
    ]
  },
  {
    "id": "alternative-offer",
    "articleSlug": "Product Review Article",
    "placement": "sidebar",
    "priority": 2,
    "title": "Also Consider",
    "products": [
      {
        "productId": "budget-product",
        "variant": "sidebar",
        "title": "Budget Pick"
      }
    ]
  }
]

Strategy 3: Seasonal Shortcode Rotation

Use the enabled flag for seasonal promotions:

json
{
  "id": "holiday-sale-products",
  "articleSlug": "Popular Article",
  "placement": "sidebar",
  "priority": 1,
  "enabled": false,
  "title": "Holiday Sale - Limited Time",
  "products": [
    {
      "productId": "sale-product",
      "variant": "sidebar",
      "title": "50% Off Today"
    }
  ]
}

Set enabled: true during sales, enabled: false after.

Strategy 4: Multiple Product Tiers

Show good/better/best options:

json
{
  "id": "tiered-products",
  "articleSlug": "Comparison Article",
  "placement": "sidebar",
  "priority": 1,
  "enabled": true,
  "title": "Choose Your Level",
  "products": [
    {
      "productId": "basic-product",
      "variant": "sidebar",
      "title": "Starter ($29)"
    },
    {
      "productId": "pro-product",
      "variant": "sidebar",
      "title": "Pro ($99)"
    },
    {
      "productId": "enterprise-product",
      "variant": "sidebar",
      "title": "Enterprise ($299)"
    }
  ]
}

Shortcode Best Practices

Here are proven strategies for maximizing conversions with shortcodes:

1. Match Products to Article Intent

Don’t show random products. Match product type to article topic:

• Review articles → Feature the reviewed product first
• Comparison articles → Show all compared products
• How-to guides → Display tools mentioned in the tutorial
• Problem/solution articles → Offer relevant solutions

2. Use Compelling Section Titles

Generic titles like “Related Products” convert poorly. Use specific, benefit-driven titles:

Bad:

• “Products”
• “Related Items”
• “Check These Out”

Good:

• “Tools I Use Daily”
• “Editor’s Top Picks”
• “Get Started Today”
• “Complete Solution”

3. Limit Sidebar Products

Don’t overwhelm readers. Optimal product counts:

• 1 product - Best for single product reviews
• 2-3 products - Perfect for most articles
• 4-5 products - Maximum before overwhelming users

4. Strategic Product Order

Place your highest-converting products first:

json
"products": [
  {
    "productId": "best-converter",
    "title": "Most Popular"
  },
  {
    "productId": "second-best",
    "title": "Also Great"
  },
  {
    "productId": "budget-option",
    "title": "Budget Pick"
  }
]

5. Use Product Labels Wisely

Labels create urgency and social proof:

• “Best Seller” - Social proof
• “Editor’s Choice” - Authority
• “Limited Time” - Urgency
• “New Release” - Novelty
• “Budget Pick” - Value shoppers

6. Test and Optimize

Use the enabled flag for A/B testing:

1. Create two shortcodes for the same article
2. Enable one at a time
3. Track conversions
4. Keep the winner

7. Regular Maintenance

Review your shortcodes quarterly:

• Disable outdated products
• Update seasonal offerings
• Remove discontinued items
• Refresh product images and descriptions

Shortcode Management Functions

AstroPress provides helper functions for working with shortcodes programmatically:

Get Shortcodes for an Article

typescript
import { getShortcodesForArticle } from '../core/shortcodeLogic';

const shortcodes = await getShortcodesForArticle("Article Title");

Get Only Sidebar Shortcodes

typescript
import { getSidebarShortcodesForArticle } from '../core/shortcodeLogic';

const sidebarShortcodes = await getSidebarShortcodesForArticle("Article Title");

Check if Article Has Shortcodes

typescript
import { hasSidebarShortcodes } from '../core/shortcodeLogic';

const hasProducts = await hasSidebarShortcodes("Article Title");

Get All Enabled Shortcodes

typescript
import { getAllEnabledShortcodes } from '../core/shortcodeLogic';

const allShortcodes = await getAllEnabledShortcodes();

Get Shortcode Summary Statistics

typescript
import { getShortcodeSummary } from '../core/shortcodeLogic';

const summary = await getShortcodeSummary();
// Returns: { totalShortcodes, enabledShortcodes, articlesWithShortcodes, sidebarShortcodes, contentShortcodes }

Real-World Shortcode Examples

Let’s look at practical shortcode configurations from different niches:

Example 1: Tech Blog - Product Review

json
{
  "id": "macbook-review-sidebar",
  "articleSlug": "MacBook Pro M3 Review 2025",
  "placement": "sidebar",
  "priority": 1,
  "enabled": true,
  "title": "Where to Buy",
  "products": [
    {
      "productId": "macbook-pro-m3",
      "variant": "sidebar",
      "title": "Best Price"
    },
    {
      "productId": "macbook-accessories",
      "variant": "sidebar",
      "title": "Essential Accessories"
    }
  ]
}

Example 2: Fitness Blog - Supplement Guide

json
{
  "id": "protein-powder-guide",
  "articleSlug": "Best Protein Powders for Muscle Gain",
  "placement": "sidebar",
  "priority": 1,
  "enabled": true,
  "title": "Top Recommendations",
  "products": [
    {
      "productId": "whey-protein-gold",
      "variant": "sidebar",
      "title": "#1 Pick"
    },
    {
      "productId": "casein-protein",
      "variant": "sidebar",
      "title": "Night Time"
    },
    {
      "productId": "vegan-protein",
      "variant": "sidebar",
      "title": "Plant Based"
    }
  ]
}

Example 3: Marketing Blog - Tool Roundup

json
{
  "id": "email-marketing-tools",
  "articleSlug": "Best Email Marketing Software 2025",
  "placement": "sidebar",
  "priority": 1,
  "enabled": true,
  "title": "Our Top Picks",
  "products": [
    {
      "productId": "convertkit",
      "variant": "sidebar",
      "title": "For Creators"
    },
    {
      "productId": "activecampaign",
      "variant": "sidebar",
      "title": "For Businesses"
    },
    {
      "productId": "mailchimp",
      "variant": "sidebar",
      "title": "Free Option"
    }
  ]
}

Troubleshooting Common Issues

Issue 1: Products Not Appearing

Cause: Article slug doesn’t match exactly

Solution: Check your article frontmatter title matches articleSlug exactly:

json
"articleSlug": "Exact Article Title Here"

Issue 2: Wrong Product Displays

Cause: Invalid productId

Solution: Verify product ID exists in /src/content/data/products/[productId].json

Issue 3: Multiple Shortcodes Conflicting

Cause: Same priority numbers

Solution: Use unique priority values:

json
"priority": 1  // First
"priority": 2  // Second
"priority": 3  // Third

Issue 4: Shortcode Appears on Wrong Article

Cause: Multiple articles with similar titles

Solution: Use complete, unique article titles in frontmatter

Why AstroPress Shortcodes Beat WordPress

Let’s compare AstroPress shortcodes to WordPress plugin alternatives:

Feature	AstroPress Shortcodes	WordPress Plugins
Configuration	Simple JSON	Complex admin UI
Performance	Zero runtime cost	Database queries
Version Control	Git-friendly	Database only
Bulk Updates	Edit one JSON file	Click through UI
Type Safety	TypeScript validated	No validation
Speed Impact	None (static)	Slows page loads
Learning Curve	5 minutes	1-2 hours
Debugging	Read JSON directly	Plugin conflicts

The verdict: AstroPress shortcodes are faster, simpler, and more powerful than any WordPress alternative.

Start Using Shortcodes Today

Shortcodes are one of AstroPress’s most underrated features for affiliate marketers. They give you:

✅ Centralized product management - Update once, apply everywhere

✅ Article-specific targeting - Right products on right articles

✅ Zero content editing - Never touch your MDX files

✅ Easy A/B testing - Enable/disable with one flag

✅ Scalability - Manage hundreds of product placements effortlessly

Ready to boost your affiliate earnings?

1. Open /src/content/data/shortcodes.json
2. Create your first shortcode entry
3. Match products to your top articles
4. Deploy and watch conversions improve

With AstroPress shortcodes, you can test product placements, rotate seasonal offers, and optimize affiliate strategies—all without touching a single article. That’s the power of smart monetization automation.