Nousk AD: Inserting ads easily and quickly

Nousk AD is a WordPress plugin for ad insertion with manual and automatic control. It operates without external dependencies, using content parsing with a deep focus on the editor's experience.

nousk-plugin
wordpress

Notice: This plugin interface and documentation are currently available only in Portuguese. English translation is planned for a future update.

How to build a WordPress ad plugin with automatic and manual control

For a long time, inserting ads into WordPress posts followed the same old story: rigid solutions, bloated plugins, or code scattered throughout the theme. In a past project, I had to solve a simple problem that ended up completely changing my perspective on development.

The requirement was: insert ads automatically within the content, but without losing manual control when necessary.

That’s how the idea of building logic based on the content itself was born. Later, I transformed that logic into a plugin.

The Problem

Initially, the rule was simple: insert an ad every 8 paragraphs.

But in practice, this didn’t work for every post.

Some content became cluttered.
Others didn’t have enough paragraphs.
In some cases, the ad needed to appear at a very specific spot.

In other words, there was no “one-size-fits-all” solution.

The Solution: Three Operating Modes

The plugin was designed to solve this with flexibility. It offers three modes:

No Ads: The content is displayed without any changes.
Automatic: The plugin inserts ads based on the paragraph count.
Manual: The editor decides exactly where the ad should appear.

Manual Mode: Total Control

In manual mode, the editor uses a shortcode within the content: `[nousk_ads]`. The plugin then replaces this shortcode with the ad code.

It’s simple. No complicated interface. No extra configuration. No dependency on specific blocks. This gives full control to the person writing the piece.

Automatic Mode: Where the Parser Comes In

In automatic mode, the plugin needs to:

Understand the content.
Count valid paragraphs.
Insert ads without breaking the HTML.

This is where the concept of parsingcomes in.

What is “Parsing” in this context?

In this case, parsing is the logic used to read the post content, identify the paragraphs, and reconstruct that content with ads inserted at the right points.

In WordPress, the post content is essentially a string of HTML. The plugin:
1. Reads this content.
2. Splits it into parts.
3. Identifies what is relevant.
4. Reconstructs the content based on new rules.

How the plugin analyzes content

The current logic processes content based on paragraph closing tags (``), using this structure as a reference to identify where ads can be safely inserted.

Empty paragraphs are ignored, such as:

Ad Insertion

After counting the valid paragraphs, the plugin:

Inserts an ad every X paragraphs.
Avoids inserting consecutive ads.
Maintains the original content structure.

There is also an important rule: it always ensures an ad appears at the end of the post, even if the content is short.

Validation: Preventing errors before breaking content

A crucial part of the plugin is the admin-side validation.

In Automatic Mode:

Errors (Block saving):

Empty interval.
Interval less than 1.

Warnings (Do not block):
Interval greater than the number of valid paragraphs. In this case, the plugin warns: “The ad will only appear at the end.”

This prevents unexpected behavior and makes the plugin’s usage clearer for the editor.

Plugin Structure

The plugin is divided into classes, each with its own responsibility:

Admin:Global configuration.
Metabox:Post-specific control.
Shortcode:Manual mode handling.
Parser:Automatic insertion logic.
Validator:Rules and admin messaging.

This keeps the code organized and easy to evolve.

The Most Important Point: Thinking of the Editor

This plugin wasn’t born just as a technical solution; it was born from a real content editing problem. The goal wasn’t just to “insert ads.” It was to allow the writer to have control without needing to understand code.