AstroPress Banner Ads: A Guide to Simple, Performant Monetization

Monetizing your blog with display ads is a proven strategy, but it often comes at a cost.

In the world of WordPress, this usually means installing heavy ad management plugins that inject intrusive, performance-killing scripts from third-party networks.

These plugins can slow your site to a crawl, compromise user privacy, and offer a clunky management experience.

AstroPress provides a refreshingly modern alternative.

This guide will walk you through the powerful, built-in banner ad system in AstroPress.

You’ll learn how to manage your entire ad inventory from a single JSON file, display ads exactly where you want them, and maintain a lightning-fast user experience—all without a single third-party plugin.

The Problem with Traditional Ad Plugins

If you’ve ever used an ad plugin on WordPress, you’re likely familiar with the pain points:

• Performance Hit: Ad plugins are notorious for adding significant bloat, increasing page load times and hurting your Core Web Vitals scores.
• Lack of Control: You’re often at the mercy of the ad network’s algorithms, with little say over the quality or relevance of the ads shown.
• Security & Privacy Risks: Third-party ad scripts can be a vector for malware and often rely on invasive user tracking.
• Complex Dashboards: Managing your ad units often involves navigating a complicated, slow, and non-intuitive UI within the WordPress admin.

AstroPress sidesteps these issues by treating your ad inventory as structured content, giving you full control and unparalleled performance.

The AstroPress Ad System: ads.json

Just like other features in AstroPress, the ad system is powered by a simple, centralized JSON file: /src/content/data/ads.json. This file is your command center for your entire ad inventory.

Here’s a snippet of its structure:

json
{
  "global": {
    "enabled": true,
    "testMode": true,
    "security": {
      "allowHtmlAds": true
    }
  },
  "banners": [
    {
      "id": "article-banner",
      "name": "Article Content Banner",
      "enabled": true,
      "image": "https://example.com/your-ad-image.webp",
      "link": "https://your-affiliate-link.com",
      "alt": "An amazing product you should buy",
      "placement": "article-content"
    },
    {
      "id": "article-sidebar",
      "name": "Article Sidebar Banner",
      "enabled": true,
      "image": "https://example.com/your-sidebar-ad.webp",
      "link": "https://your-other-link.com",
      "alt": "Another great product",
      "placement": "article-sidebar"
    }
  ]
}

This git-based approach offers tremendous benefits:

• Total Control: You define exactly which ads run and where they link. No surprises.
• Version Controlled: Track every change to your ad inventory, A/B test different banners, and roll back changes with ease.
• Blazing Fast: Since ads are just data, they add zero bloat to your site until they are rendered.
• Easy to Manage: Edit a single text file to update ads across your entire site.

Anatomy of the ads.json Configuration

Let’s break down the key parts of the file.

The global Object

This section controls the sitewide behavior of your ad system.

• enabled: The master switch. Set this to false to instantly disable all ads on your site.
• testMode: When true, it can enable placeholder UIs or other debugging features.
• security: A crucial object for controlling the types of ads you allow.
• allowHtmlAds: Set to false to disable raw HTML ads, enhancing your site’s security.

The banners Array

This is a list of all your individual ad units. Each banner ad is an object with the following properties:

• id** (required):** A unique identifier for the ad (e.g., main-header-banner).
• name** (required):** A human-readable name for easy identification.
• enabled** (required):** A switch to turn this specific ad on or off.
• type** (optional, defaults to ‘image’):** Can be image or html.
• image** (for image ads):** The URL for your banner image.
• link** (for image ads):** The destination URL the ad should link to.
• alt** (for image ads):** The alt text for the image, important for accessibility and SEO.
• htmlContent** (for HTML ads):** A string containing the raw HTML for your ad (e.g., from Google AdSense).
• placement** (required):** This is the magic property. It tells AstroPress where this ad should appear on your site.

Displaying Ads with the SimpleBannerAd Component

AstroPress includes a versatile component for displaying your ads: /src/components/ads/SimpleBannerAd.astro.

This component is the bridge between your ads.json configuration and the front end of your site. You can place it anywhere in your theme’s layout files.

How to Use It:

The component can be used in two primary ways:

1. By Placement:

This is the most common and powerful method. You specify a placement string, and the component will automatically render any enabled banners from ads.json that match that placement.

For example, to show all ads designated for the article-sidebar placement, you would add this to your layout:

astro
---
import SimpleBannerAd from '~/components/ads/SimpleBannerAd.astro';
---

2. By ID:

If you want to render a single, specific ad in a unique location, you can call it by its id.

astro
---
import SimpleBannerAd from '~/components/ads/SimpleBannerAd.astro';
---

Ad Types: Image vs. HTML

The AstroPress ad system supports two primary types of ads, giving you flexibility in your monetization strategy.

Image Ads

This is the simplest and most secure type of ad. You provide an image and a link. These are perfect for:

• Direct affiliate promotions: Create your own custom banners for products you love.
• Selling ad space directly: Offer sponsors a simple image banner spot.
• Internal promotions: Advertise your own products, courses, or newsletter.

Because you control the image and the link, they are incredibly fast and completely secure.

HTML Ads

This option allows you to paste raw HTML code, which is typically provided by third-party ad networks like Google AdSense, Carbon Ads, or EthicalAds.

Example html ad in ads.json:

json
{
  "id": "adsense-sidebar",
  "name": "AdSense Sidebar Unit",
  "enabled": true,
  "type": "html",
  "htmlContent": "",
  "placement": "article-sidebar"
}

The SimpleBannerAd component will safely render this HTML. For security, you can globally disable all HTML ads via the global.security.allowHtmlAds flag in ads.json.

The AstroPress Advantage for Ads

Let’s summarize why the AstroPress ad system is superior to traditional ad plugins.

Feature	AstroPress Banner Ads	WordPress Ad Plugin
Performance	Near-zero impact. Ads are static content.	Adds significant JS/CSS bloat, slowing down pages.
Control	100% control over ad content and placement.	Often relies on unpredictable network algorithms.
Security	High. You control the code. Can disable HTML ads.	Third-party scripts can be a security risk.
Management	Simple, centralized ads.json file.	Complex, slow, and fragmented admin dashboards.
Cost	Free and built-in.	Premium features often require a paid subscription.
Flexibility	Supports both direct-sold image ads and network HTML.	Often locks you into a specific ad network or model.

Start Monetizing with Banner Ads Today

With AstroPress, implementing a fast, secure, and effective ad strategy is incredibly straightforward.

1. Configure ads.json: Open /src/content/data/ads.json and define your global settings and banner inventory.
2. Upload Your Creatives: Add your banner images to the /public/ directory or an external host.
3. Place the Component: Add the component to your layout files, specifying the desired placement.
4. Deploy: Commit your changes, and your ads will be live instantly, served at the edge with the rest of your high-performance site.

By decoupling ad management from bloated plugins and third-party scripts, AstroPress puts the power back in your hands, allowing you to monetize effectively without sacrificing the user experience.