CMS for Affiliate Marketing

Most affiliate sites run on WordPress with a plugin stack that has grown one problem at a time: ThirstyAffiliates for link cloaking, WP Rocket because the site is too slow without it, Wordfence because the login page gets hammered overnight, Yoast because WordPress doesn't handle meta tags cleanly on its own. Each plugin solves a problem WordPress created, and each one invoices you every January.

Add up the renewals, and you're looking at £300 or more per year just to make the platform functional for affiliate work, before you've written a single article or earned a first commission. Those subscriptions don't stop when the site starts earning. They compound as you add features, and your hosting costs climb with traffic.

What a CMS for Affiliate Marketing Actually Needs

Link cloaking and click tracking are the two non-negotiable operational requirements of any affiliate site. Without them, you can't manage your links cleanly or know which pages are actually driving revenue. On WordPress, both require paid plugin subscriptions. CARL includes both as built-in CMS features with no additional cost.

The Affiliate Link Tracker handles link creation, cloaking, and tracking in one place. You create a link, assign it a slug, and every click gets logged: the count, the referring page, and the traffic source attribution. That data lives in your own database on your own server, not in a plugin's cloud account.

Page Speed Is a Revenue Issue on Affiliate Sites

A slow page costs money in a way that's different from a regular content site. On a blog, a slow load annoys a reader; on an affiliate product comparison page, it drops the visitor right when purchase intent is highest, before they reach your link. The math is direct: faster pages drive more clicks, and more clicks produce more commissions.

CARL generates static PHP files and writes them directly to your server. When a visitor lands, the server delivers a file that already exists on disk. The page is pre-built, so there's nothing to query or assemble on request. Pages load in under a second on standard shared hosting without a caching plugin, because the architecture doesn't need one.

One Payment, All the Features

CARL is a one-time purchase: you pay once and own the license permanently, including all future standard updates and unlimited domain installs. What a WordPress affiliate stack delivers through four separate paid plugins, link tracking, page speed, security, and SEO meta handling, CARL includes as standard. The math closes before year one is out, and from year two onward, the cost difference compounds in your favor.

The pricing page lays out the full comparison: what a functional WordPress affiliate stack costs annually versus the CARL one-time price.

Your Data Belongs on Your Server

Every click record, every redirect, and every piece of link-tracking data that CARL generates lives in your database on your hosting account. If you ever change CMS, migrate hosts, or walk away from a niche entirely, that data comes with you. There's no subscription required to keep your affiliate link history accessible, because the records exist in your database, not on someone else's platform.

The same principle applies to your content. CARL generates real PHP files and saves them to your server. Remove the admin panel entirely, and every page you've published keeps working. The files exist independently of the platform that created them.

For everything CARL does for affiliate sites, the Affiliate Marketing Sites overview is the starting point.

What Site Health Checks For on Every Page

Site Health runs a fixed set of checks against every published page in your CARL install. This article documents exactly what each check looks for, what a pass looks like, and what triggers a flag. If you're working through a Site Health report and want to understand what a specific issue means, this is the reference page.

Page Title

Site Health checks that a title tag is present and that its length falls within an acceptable range. Titles below 30 characters are flagged as too short: they're typically not descriptive enough to compete in search results. Titles above 60 characters are flagged as too long: Google truncates them in search results, cutting off whatever appears after the limit. The target is a title between 30 and 60 characters that leads with the primary keyword and clearly describes the page.

If you're using the Generate Schema workflow, the title Claude uses in the schema block is derived from the page title field. A well-formed title in the editor produces a well-formed title in the schema.

Meta Description

Site Health flags pages where the meta description is missing entirely or exceeds 160 characters. A missing description means Google will pull whatever text it deems relevant from the page body, which may or may not accurately represent the page. A description over 160 characters gets truncated in search results, cutting your message short at exactly the wrong moment.

If you're using Generate Schema, Claude writes the meta description and automatically appends it to the Head Injection field. Site Health checks the Head Injection field for the presence of a description tag, so pages where Generate Schema has been run and the result saved will pass this check.

H1 Tag

Every published page should have exactly one H1 tag. Site Health flags pages where the H1 field in the editor is blank. A missing H1 is a basic on-page SEO issue: it's the strongest heading signal on the page, and Google uses it to understand what the page is about. Fill in the H1 field for every page, and make it descriptive rather than a copy of the title tag.

Canonical Tag

Site Health checks two things about the canonical tag: whether one is present, and whether the URL it declares matches the page's actual URL. A missing canonical is flagged because without it Google makes its own determination about which version of the page to treat as authoritative. A canonical mismatch is flagged because it tells Google to treat a different URL as the authoritative version, usually due to a slug or directory change that wasn't followed by an updated canonical.

For the full process of fixing a canonical mismatch, see How to fix a canonical mismatch in CARL.

Head Injection Content

Site Health flags pages where the Head Injection field is empty. An empty Head Injection field indicates the page has no schema markup, Open Graph tags, Twitter Card tags, or an AI-optimized meta description. These are pages where Generate Schema hasn't been run, or where the Head Injection field was cleared before regenerating. The fix is to open the page, click Generate Schema, save the result, and regenerate.

File Sync Status

Site Health checks whether the PHP file on disk matches the current state of the page record in the database. If a page has been edited and saved in the admin but not regenerated, the file on disk reflects the old version of the content. Site Health flags these out-of-sync pages so you can regenerate them and bring the published file up to date. This check catches pages that were edited but where the regenerate step was skipped before moving on to the next task.

Using the Results

A clean Site Health report means every published page has a valid title, a meta description, an H1, a canonical tag pointing to the right URL, a populated Head Injection field, and a file on disk that matches the current database record. That's the baseline. Run Site Health regularly to keep it there.

How CARL Handles Meta Descriptions

The meta description is the short summary that appears under your page title in search results. It doesn't directly affect rankings, but it affects click-through rates, which in turn affect traffic.

CARL gives you two ways to handle it: the AI-powered Generate Schema button, which is the recommended approach for most pages, and the Manual SEO Override field for the rare cases where you want to write it yourself.

The Recommended Approach: Generate Schema

Once you've written your page content, click the Generate Schema button in the page editor. CARL sends your content to Claude, which reads it and writes an optimized meta description specifically crafted for click-through performance. The result is returned as part of a complete head block and is automatically appended to the Head Injection field. You don't paste anything, you don't copy anything. CARL handles the transfer.

When you click Generate to publish the page, that entire head block, including the meta description, gets baked into the section of the generated PHP file. The tag is present in the published page exactly as Claude wrote it, with no further intervention required from you.

What "Generate Schema" Produces

The meta description is one part of a larger block that Generate Schema produces in a single pass. Along with the description, Claude writes a keywords tag, a full Article JSON-LD schema with Thing entities for knowledge graph enhancement, Twitter Card tags, Open Graph tags, and the canonical tag, all delivered in the correct order and automatically appended to Head Injection. Running Generate Schema once handles everything that belongs in the of your page.

The Manual SEO Override section in the page editor is labeled "Handled Automatically by Generate Schema" for exactly this reason. If you're using Generate Schema, you don't need to touch the manual fields. The AI output covers them.

When to Use the Manual Field Instead

The Manual SEO Override field exists for cases where you have a specific reason to write the meta description yourself: a page with unusual framing that Claude is unlikely to nail without significant prompting, a page where you're testing a specific description against a known search query, or a legacy page you're updating without regenerating the full schema block.

These cases are the exception. For the vast majority of pages, Generate Schema produces a better-optimized description faster than manually writing one.

What Makes a Good Meta Description

Whether you're reviewing Claude's output or writing one manually, the same principles apply. Keep it under 160 characters, or Google will truncate it in search results. Lead with what the page is about, be specific about what the reader will get, and write it as a sentence a person would actually read rather than a string of keywords. The meta description is part of the pitch: someone sees your title and description side by side before deciding whether to click, and a clear, specific description earns that click.

After the Page Is Generated

If you need to update the meta description after a page is live, open the Head Injection field, edit the description tag directly, and regenerate the page. The updated tag will be in the new file immediately. For a deeper look at everything Generate Schema produces and how it fits into CARL's SEO system, see How CARL generates JSON-LD schema markup.

How CARL Handles Canonical URLs

A canonical URL tells search engines which version of a page is the authoritative one. Without it, Google can interpret minor URL variations as separate pages with duplicate content and split the ranking signals that should be concentrated on one URL across several. CARL handles canonicals at the page level, giving you direct control over what gets declared in every generated file.

How CARL Sets the Canonical Tag

Every page in CARL has a Canonical URL field in the page editor. Whatever you enter there gets written into a tag in the section of the generated PHP file. If you use the Generate Schema button, Claude writes the canonical tag as part of the complete head block and automatically appends it to the Head Injection field, along with the meta description, schema, and Open Graph tags. Either way, the canonical is present in the published file exactly as specified.

The canonical tag is written once at generation time and baked into the static file. There's no dynamic canonical generation on each page request, no plugin calculating the URL at runtime, and no risk of the tag being output incorrectly due to a caching layer interfering with PHP execution.

What the Canonical URL Should Be

For most pages, the canonical URL is simply the full URL of the page itself: https://yourdomain.com/directory/slug.php. Setting a page as its own canonical tells Google that this is the preferred version of the content and that there are no other versions it should defer to.

This is the correct setting for any page with unique content that you want indexed at its own URL.

The cases where you'd set a different canonical are less common but worth understanding. If you publish the same article on your site and on Medium, the canonical on the Medium version should point back to your original.

If you have a page accessible at two different URLs for technical reasons, set the canonical on both to point to the URL you want Google to index. CARL's canonical field handles both scenarios: just enter the URL you want declared as authoritative.

Canonicals and the Generate Schema Workflow

When you run Generate Schema, Claude writes the canonical tag based on the page URL and includes it at the end of the head block, after the Open Graph tags. The URL it uses is derived from your domain settings, the page's slug, and the directory. Check the Head Injection field after generating to confirm the canonical URL matches what you expect before publishing the page.

If the generated canonical isn't quite right, you can edit it directly in the Head Injection field before clicking Generate. The Head Injection content is written verbatim into the published file, so what you see in that field is exactly what lands in the page's .

Canonical Mismatches and Site Health

CARL's Site Health checker scans your published pages and flags canonical mismatches: cases where the canonical tag in the file doesn't match the page's actual URL. A mismatch typically means a page was generated with one URL, then moved to a different slug or directory without the canonical being updated. If Site Health flags a mismatch, the fix is straightforward: update the canonical in the Head Injection field and regenerate. For the full process, see How to fix a canonical mismatch in CARL.

How to Use the Head Snippet Field in CARL

The Head Snippet field lets you add custom code to the section of an individual page without modifying the template. Whatever you put in this field gets written directly into the of the generated PHP file, sitting alongside the standard meta tags, title, and schema markup that CARL outputs by default. It's a clean way to add page-specific head content without affecting your other pages.

What Goes in the Head Section

The section of an HTML document is where browsers and crawlers look for instructions about the page: how to render it, what to preload, which scripts to load early, what additional metadata is attached. Things that belong here include custom stylesheet links, preload directives, verification meta tags, third-party script tags that must load in the head, and any other markup that needs to appear before the page content renders.

Most of the standard head content, including the title tag, meta description, canonical URL, Open Graph tags, and JSON-LD schema, is handled automatically by CARL based on the fields you fill in the page editor. The Head Snippet field is for everything else: the one-off additions a specific page needs that don't belong in the template.

How It Differs from the PHP Snippet Field

The PHP Snippet field is for server-side logic that runs before any output is sent to the browser. The Head Snippet field is for client-side markup that sits inside the tag in the rendered HTML. They serve different purposes and appear in different positions in the generated file. If you need a redirect or an access check, that's a PHP snippet. If you need a custom stylesheet or a verification tag, that's a head snippet.

Practical Uses

A common use of the Head Snippet field is to add a page-specific stylesheet. If one page uses a custom layout or a component that needs its own CSS, you link that stylesheet in the head snippet rather than adding it to the template, where it would load on every page unnecessarily. The same logic applies to the JavaScript libraries a single page needs: load them in the head snippet and keep the template clean.

Another frequent use is ownership verification tags. Google Search Console, Pinterest, and other platforms sometimes ask you to add a tag to a specific page to verify ownership. Drop it into the Head Snippet field, regenerate the page, and the tag will appear in the live file within seconds. No template edit required, no other pages affected.

Keeping Templates Clean

The Head Snippet field exists specifically to prevent template bloat. Without it, any page-specific head requirement would mean either editing the template (affecting every page using it) or creating a separate template variant just for that one page. Neither option is clean. The head snippet lets you handle the exception without disturbing the rule.

As with the PHP Snippet field, if the logic or code you're adding is needed on multiple pages, it belongs in the template rather than being repeated in individual snippets. Use the head snippet for genuine one-page requirements. For anything sitewide, put it where sitewide things belong.

Snippets Are Baked In at Generation

Whatever is in the Head Snippet field when you click Generate is what ends up in the published file. Update the snippet, regenerate, and the new code will be in the file. The previous version is gone. There's no version history for snippet content, so if you're making significant changes to a head snippet, keep a copy of the original somewhere before you overwrite it.

How CARL's Affiliate Link Tracker Works

CARL's Link Tracker lets you create, manage, and track every affiliate and outbound link on your site from one place in the admin panel. Every click is logged, bots are automatically filtered out, and the data is stored on your own server with no third-party tracking service involved.

How Links Work

Each link you create gets a unique 6-character short code. When a visitor clicks the link, they're routed through go.php on your site using a URL in the format yoursite.com/go.php?code=XXXXXX. CARL logs the click, resolves the destination, and sends the visitor on their way. The whole process takes milliseconds.

Links can be organized into groups, making it much cleaner to manage large numbers of affiliate links across multiple programs or campaigns. Each group has its own name and slug, and reports can be filtered by group to isolate performance by campaign or affiliate program.

Redirect Types

Each link is assigned one of four redirect types. A 301 sends a permanent redirect to the destination. A 302 sends a temporary redirect. The two cloaking options keep your domain in the browser's address bar throughout the visit: iframe cloaking loads the destination inside a full-screen frame, and JavaScript cloaking bounces the visitor instantly via a client-side redirect while serving a noindex page to search engines. For more details on when to use each option, see How to cloak affiliate links in CARL.

UTM Parameters

Each link has optional UTM fields: source, medium, campaign, term, and content. When a visitor clicks a link with UTM parameters configured, the CARL appends them to the destination URL automatically. This means your affiliate traffic appears correctly segmented in Google Analytics, without you having to manually build UTM URLs for every link.

Click Logging

Every click is logged with the timestamp, referrer URL, country code, and user agent. IP addresses are hashed before storage, so raw visitor IPs are never retained. Bot detection runs on every click using a pattern list that covers search engine crawlers, SEO tools, uptime monitors, and common HTTP clients. Bot clicks are logged separately and excluded from your human-click totals, so your performance data stays clean.

Managing Links

From the Link Tracker dashboard in the admin panel, you can create new links, edit existing ones, toggle any link active or inactive without deleting it, and see a running human click total for each link at a glance. Inactive links return a 404 rather than redirecting, allowing you to pause a link during a campaign without removing it from your pages.

How to Configure CARL's Email Settings

CARL's email settings connect your install to Kit (ConvertKit), the email platform CARL integrates with natively. Once connected, every subscriber who signs up through a CARL signup form is added directly to your Kit account. The setup takes about five minutes and only needs to be done once.

Where to Find the Email Settings

In the CARL admin panel, go to Settings and click the Subscribers tab. This is where all Kit integration settings live. You'll need your Kit API key and the form ID of the form you want subscribers added to. Have your Kit account open in a separate browser tab before you start.

Getting Your Kit API Key

Log in to your Kit account at app.kit.com. Go to Settings> Developer Settings, then copy your API key. Back in CARL, paste it into the Kit API Key field. This key authorizes CARL to communicate with your Kit account and add subscribers on your behalf.

Finding Your Kit Form ID

In Kit, go to Grow, then Landing Pages and Forms. Click the form you want CARL to subscribe people to. Look at the URL in your browser address bar: the number in the URL is your Form ID. Copy that number and paste it into the Default Kit Form ID field in CARL's Subscribers settings.

The Default Kit Form ID is the form CARL uses when a visitor signs up through your site's signup form. If you have multiple forms for different lead magnets or sections of your site, the default applies across the board. Individual signup form embeds can reference specific form IDs if needed.

Customizing the Signup Form Wording

The Subscribers tab also lets you customize the text displayed on CARL's native signup form: the heading, description, button label, and confirmation message shown after someone subscribes. Update these to match your brand voice before the form goes live. The default text is functional but generic. Your subscribers will read it, so write it like you mean it.

Saving and Testing

Click Save All Settings after entering your API key and Form ID. To confirm the connection is working, go to one of your published pages that includes a signup form, enter a test email address, and submit. Check your Kit account to confirm the subscriber was added to the correct form. If the subscriber doesn't appear, go back to the Subscribers tab and verify the API key and Form ID are entered correctly with no extra spaces.

If You're Not Using Kit Yet

You can skip the Subscribers tab during initial setup and return to it when you're ready to connect your email platform. CARL functions fully without Kit integration. The signup form simply won't sync subscribers to an external list until the API key is in place. For more details on how CARL's subscriber system works and how the native signup form connects to your pages, see How CARL integrates with Kit.

How to Configure CARL's General Settings

The first thing to do after logging into CARL for the first time is to open Settings and work through each tab. The General tab contains the most critical settings on the entire install: get these right before you publish a single page. Getting them wrong after pages are already live creates SEO problems that take real effort to clean up.

Site Name

The Site Name field is your website or brand name. CARL uses it in browser tabs, schema markup, and throughout the admin interface. Enter it exactly as you want it to appear publicly. This is not a URL, just the name: "Carl Riedel", "The Takeaway Tuesday", "Acme Plumbing Services", whatever your brand is called.

Base URL

The Base URL is the single most critical setting in CARL. It must be your site's exact root URL with no trailing slash and with the correct HTTPS protocol. The correct format is https://yoursite.com. Not https://yoursite.com/ with a trailing slash. Not http://yoursite.com with HTTP instead of HTTPS.

CARL uses the Base URL to build every canonical URL, every sitemap entry, and every schema link on your site. A wrong Base URL means every SEO signal on every page points to the wrong address. Set it correctly once, click Save All Settings, and don't change it after pages are published.

Admin Recovery Key

The Recovery Key is your emergency access key. If you ever forget your admin password, CARL's Forgot Password page asks for this key before allowing a reset. Set it immediately after your first login, before you need it. Write it down and store it in a password manager. If you lose both your password and your Recovery Key, recovering admin access requires direct access to the database through your hosting provider.

Favicon

The favicon section on the General tab lets you upload your site icon directly through the admin. Click Choose File, select a 32x32 or 64x64-pixel PNG or ICO file, then click Upload Favicon. CARL saves it and automatically injects it into every page. After uploading, use the Regen All button on the Pages list to update all existing published pages with the new favicon tag.

Saving Your Settings

Click Save All Settings before moving to any other tab. CARL doesn't auto-save settings across tabs, so changes on the General tab must be saved explicitly before you navigate elsewhere. Make it a habit: change something, save, then continue.

The Other Settings Tabs

The General tab is the starting point, but the other tabs matter too. The Organization tab powers your Organization JSON-LD schema and should be filled in completely. The System tab contains the Admin Timezone and Cron Secret Key needed for scheduled publishing. The AI Settings tab is where you enter your Claude API key, which enables the Generate Schema button in the page editor. The Subscribers tab connects CARL to your Kit account if you're building an email list.

For full details on the AI settings that power schema generation, see How to use CARL's AI Schema Generator. For email integration, see How CARL integrates with Kit.

How to Create a Product Page for a Digital Download

Every digital product you sell through CARL needs its own page on your site. That page does two jobs: it sells the product to visitors who land there, and it displays the PayPal buy button that starts the purchase flow. Both happen in CARL's page editor, with the Downloads module's product renderer handling the technical side while you focus on the copy.

Set Up the Product in the Downloads Module First

Before you create the page, the product needs to exist in CARL's Downloads module. Go to Downloads in the admin panel, add a new product, and fill in the details: the product name, price, currency, the file you're selling, and the token settings that control how long the download link remains valid after purchase. Save the product record. CARL assigns it an ID that the product renderer uses to pull the buy button and product data onto the page.

Getting the product set up first means you have everything you need when you open the page editor. You won't need to switch back and forth between the Downloads module and the page editor while you're writing.

Creating the Page

Create a new page in CARL the same way you'd create any page. Set the slug and directory to something clean and descriptive: the product name works well as a slug. Choose the template that fits your sales page layout. Fill in the title, H1, meta description, and Open Graph fields with copy that reflects what you're selling and who it's for.

The content field is where you write the sales copy: what the product is, what's in it, who it's for, what problem it solves. Write this as you would any page on your site. The buy button gets added separately through the product renderer shortcode, so you don't need to manually build any payment markup.

Adding the Buy Button

CARL's Downloads module includes a product renderer that automatically renders the PayPal buy button and any associated product details. In the content field, place the renderer shortcode where you want the buy button to appear, typically after the main sales copy and before any closing content. When CARL generates the page, it replaces the shortcode with the fully rendered buy button tied to your product record.

The button uses the PayPal credentials you configured in CARL's PayPal settings. When a visitor clicks it, PayPal's native checkout opens. When the payment completes, the webhook fires, the purchase is confirmed, and the buyer receives their download link by email. You don't need to add any payment logic to the page itself.

Generating and Reviewing the Page

Once the content is written and the renderer shortcode is in place, use CARL's preview to check the page before generating it. Confirm the buy button renders correctly, the layout looks right, and the sales copy reads the way you intended. When you're satisfied, click Generate. The page goes to disk at the URL you specified and is immediately accessible.

Visit the live URL and run a test purchase using your PayPal Sandbox credentials to confirm the full flow works: button click, PayPal checkout, payment confirmation, download email, working download link. Once that passes, the page is ready for real buyers. For a complete overview of how all the pieces fit together, see How selling digital downloads works in CARL.

How Selling Digital Downloads Works in CARL

Selling a digital product from your CARL site doesn't require a third-party storefront, a monthly subscription to a delivery platform, or a percentage cut going to a middleman. The Downloads Module handles the entire process: product catalog, PayPal checkout, secure file delivery, and purchase history, all running directly on your server.

This page walks through how the whole system fits together, from the moment a buyer lands on your product page to the moment they download their file.

The Product Page

Each product you sell gets its own page on your CARL site, built using the download-product template. The page pulls the product details from your database in real time: the name, price, currency, description, file type, file size, download limit, and the duration the download link remains valid after purchase.

The product renderer also automatically renders the PayPal buy button using your PayPal Client ID from Settings. The buyer sees your product, your price, and a clean checkout button. Everything happens on your domain. There's no redirect to a storefront you don't control.

The Payment

When the buyer clicks the PayPal button, PayPal's native checkout opens. The buyer pays using their PayPal balance, a linked card, or a bank account. CARL doesn't handle payment card data at any point. PayPal processes the transaction entirely on its end.

The price and currency displayed on the page are exactly what gets charged. The product's currency setting controls this, with a fallback to the global PayPal currency you set in Settings. There are no surprises at checkout.

The Webhook

When PayPal confirms the payment, it fires a PAYMENT.CAPTURE.COMPLETED event to a webhook listener running at /admin/modules/downloads/webhook.php on your server. This is the trigger that sets everything in motion on CARL's side.

The webhook handler verifies the event, extracts the product ID embedded in the PayPal order, and runs an idempotency check to ensure the same order isn't processed twice. If everything checks out, CARL moves immediately to delivery.

The Download Token

CARL generates a secure download token: a 64-character random hexadecimal string produced by PHP's random_bytes() function. This token is tied to the specific product, stamped with an expiry time, and given a download counter starting at zero.

The token is stored in the download_tokens table alongside the buyer's details and the PayPal order ID. It cannot be guessed. It cannot be reused beyond the download limit you set. Once it expires, it stops working entirely.

The Confirmation Email

As soon as the token is created, CARL sends the buyer a confirmation email containing their download link. The link follows this format:

https://yourdomain.com/admin/modules/downloads/deliver.php?token=XXXX

The email also tells the buyer how many times the link can be used and when it expires. Delivery is immediate. By the time the buyer closes the PayPal confirmation screen, the email is already on its way.

The File Delivery

When the buyer clicks their download link, CARL's delivery script validates the token, checks the expiry timestamp, and checks the download count against the limit. If everything is valid, CARL streams the file directly to the browser.

The file itself is stored above public_html, in a folder called carl-downloads that sits entirely outside your web root. It cannot be accessed by a direct URL. The real file path is never exposed to the buyer. The only thing they see is the token URL, and the only way to access it is with a valid, unexpired token.

Each successful download increments the counter. When the counter reaches the limit, the link stops working.

The Purchase Record

Every completed sale is logged in the download_purchases table and visible in the Purchase History tab inside your Downloads admin. You can see the buyer's name and email, the product they bought, the amount paid, the PayPal order ID, how many times they've used their link, and whether the link is still active.

The stats summary at the top of the Downloads admin keeps a running total of sales, revenue, downloads delivered, and active products. It's a clear, honest record of what's moving and what's been delivered.

What You Need to Get Started

Three things: a PayPal Business account with your Client ID and Secret entered in Settings, at least one product created in the Downloads admin with a file uploaded, and a published product page using the download-product template with a slug that matches your product. That's the complete setup.

For the full step-by-step setup guide, see How to set up PayPal in CARL and How to create a product page for a digital download.

How CARL Delivers Files Securely

When someone buys a digital product through CARL, they don't get a link to a file sitting in a public folder on your server. They get a time-limited, single-use download token that points to a delivery script. The file itself is stored outside your public document root and is completely inaccessible to anyone who hasn't completed a verified purchase. That's the foundation of how CARL handles secure file delivery.

Why Public URLs Are a Problem

The simplest way to deliver a digital file is to upload it to your server and share the URL. It's also the worst way. A URL that points directly to a file can be shared, indexed by search engines, discovered by scanners, or stumbled on by anyone who guesses the path. Once the URL is out, the file is out. You have no way to revoke access, no way to know who downloaded it, and no way to tie a download to a specific purchase.

CARL's delivery system eliminates that problem entirely by keeping the file off the public web and routing every download through a controlled access layer.

Where the Files Are Stored

Files you add to CARL's Downloads module are stored in a protected directory outside public_html/. A visitor browsing your site has no path to that directory. There's no URL that resolves to it, no way to request files from it directly, and no index that lists its contents. The files exist on your server but are invisible to the public web.

This is a straightforward application of a principle that applies to any sensitive server-side resource: if the public doesn't need direct access to it, it shouldn't be in the public directory. CARL enforces this automatically when you add a product. You upload the file through the admin panel, and CARL handles where it goes.

How Delivery Actually Works

When a purchase is confirmed, CARL generates a unique download token and attaches it to the buyer's purchase record. The buyer receives a download link containing that token. When they click it, the link hits CARL's delivery script, which checks the token against the database: is it valid, has it been used, has it expired? If the check passes, the script reads the file from its protected location and streams it to the buyer's browser. The file never moves to a public URL at any point in that process.

If someone tries to use an expired token, a used token, or a token that doesn't exist, the delivery script returns an error. The file doesn't move. There's nothing to intercept, share, or reuse.

What This Means for Your Products

Secure delivery protects the value of what you're selling. A PDF guide, a software download, a template pack: these have value because access to them is controlled. CARL's delivery system keeps that control in place after the sale, not just before it. Buyers get what they paid for through a process that works cleanly and reliably. Everyone else gets nothing.

For a full picture of how the purchase-to-download flow fits together, see How selling digital downloads works in CARL.

How to Remove the CARL Admin Panel and Keep Your Pages

One of the more unusual things you can do with CARL is delete the admin panel entirely, leaving a fully functional website behind. Every page you've published keeps loading. Google keeps crawling. Visitors keep reading. The site has no idea the admin is gone.

Why This Is Possible

When you publish a page in CARL, a finished PHP file is written to disk in your document root. That file contains everything: your content, meta tags, navigation, schema, and footer. It has no dependency on the admin panel, the database, or any part of CARL's application code. It's a standalone file.

The admin panel is a separate directory on your server. It handles content management, settings, and page generation. Once a page is published, the admin's job for that page is done. Removing the admin directory doesn't touch the published files at all.

What You're Actually Removing

The CARL admin panel lives in its own folder, typically named admin/ inside your document root. That folder contains the admin application, the database connection config, and all the management tools. Your published pages live outside that folder, directly in your document root or in subdirectories based on their URL structure.

Deleting the admin/ folder removes your ability to create or edit pages. It removes access to settings, subscribers, and every other management function. Your published pages are unaffected because they never referenced the admin folder in the first place.

When You'd Actually Do This

The most common reason is a client handoff. You build the site, publish every page, hand the files to the client, and remove the admin so there's no login page for bots to probe and no CMS overhead on the server. The client gets a fast, clean website with no platform attached.

It's also useful if you've finished a project and want to archive it. Strip the admin, zip the files, and you have a complete working website in a folder. Upload it to any cPanel host, point a domain at it, and it runs. No database is required because the published pages don't use one.

The Database Stays Behind

If you remove the admin and leave the database in place, nothing breaks. The published pages don't query it. You can also drop the database entirely if you want a completely clean server with no leftover tables. Either way, the live site is unaffected.

This is the logical conclusion of the separation between admin data and published pages. The database was always an admin tool. Remove the admin, and the database has no role left to play.

Getting Back In

If you removed the admin and need it back, you can upload it again. Re-upload the admin folder, restore the database from a backup, and you're back to full management. Your published pages were sitting on the server the whole time, unchanged.

That's worth sitting with for a moment. In WordPress, the CMS and the site are the same thing. Remove WordPress, remove the site. In CARL, the CMS and the site are separate from the moment you click Generate. The published files are yours, on your server, with no platform holding them together.

How to Build a CARL Theme

A CARL theme is a zip archive renamed with a .carltheme extension. It contains three-page template files, a set of site include files, and a theme.json manifest. Build those components, run the package script, and you have a distributable theme file anyone can install on their CARL site in one step.

The Package Structure

A valid .carltheme package must follow this directory structure inside the zip:

mytheme/
  theme.json
  tpl/
    blog.tpl
    full-width.tpl
    category.tpl
  includes/
    css_include.txt
    nav_include.txt
    footer_include.txt
    footer_scripts.txt
    site_header.txt
    header_scripts.txt
    hub_render.txt
    recent_posts.txt
    sidebar_include.txt
    special_cta_include.txt
  assets/              (optional — images, fonts)

The top-level folder name doesn't matter. CARL locates theme.json automatically wherever it appears inside the zip. The tpl/ folder deploys to admin/tpl/ on the server. The includes/ folder deploys to site_includes/. The optional assets/ folder deploys to a web-accessible path at /assets/themes/{slug}/.

The theme.json Manifest

Every theme package requires a theme.json file that tells the installer what to do with the package contents:

{
  "name":          "My Theme",
  "slug":          "my-theme",
  "version":       "1.0",
  "description":   "A short description shown on the install confirmation screen.",
  "author":        "Your Name",
  "requires_carl": "1.0",
  "templates": {
    "blog":        "tpl/blog.tpl",
    "full-width":  "tpl/full-width.tpl",
    "category":    "tpl/category.tpl"
  },
  "includes": [
    "css_include.txt",
    "nav_include.txt",
    "footer_include.txt",
    "footer_scripts.txt",
    "site_header.txt",
    "header_scripts.txt",
    "hub_render.txt",
    "recent_posts.txt",
    "sidebar_include.txt",
    "special_cta_include.txt"
  ]
}

The slug field must be lowercase letters, numbers, and hyphens only. It's used to construct the template slugs stored in the database (for example, my-theme-blog) and the assets path on the server. The three template role names — blog, full-width, and category — are fixed. CARL uses them to remap existing pages to the new theme's layouts during install.

Building the Template Files

Each template file is a complete HTML document with CARL tokens in place of dynamic content. The four tokens are {{TITLE}} for the page title, {{META}} for the meta tag block, {{HEAD_EXTRA}} for any additional head content, and {{BODY}} for the full page content. Never hardcode an H1 heading directly in a template file. CARL generates the H1 as part of {{BODY}} and writes it into the file at generation time.

Every template must include lang="en" on the html element for accessibility compliance. Your viewport meta tag and any preload directives belong in header_scripts.txt rather than hardcoded in the template, so they can be updated without rebuilding the template files. The feedback widget, if you want it on category pages, is included via admin/modules/feedback/display.php.

The Include Files

All ten include files are required in the package. css_include.txt contains your entire stylesheet as an inline style block — putting CSS here rather than as an external file eliminates asset path problems when deploying the theme and removes any render-blocking external CSS request. nav_include.txt contains your site navigation HTML. footer_include.txt contains your footer. hub_render.txt contains the PHP that queries and outputs the article card grid on category pages. recent_posts.txt contains the PHP that powers the sidebar related posts widget. The remaining files handle scripts, the site header, the sidebar wrapper, and the mid-article CTA slot.

CSS and PageSpeed

Two CSS rules are essential for a zero Cumulative Layout Shift score. Content images need aspect-ratio and object-fit: cover declared so the browser reserves their space before they download. The site header banner image needs the same treatment. Without these, images cause layout jumps as they load and PageSpeed will penalize the score. Do not add transition: margin-top to the body rule — it causes measurable CLS on desktop.

For the H1 selector, use a descendant selector (.article-main h1) rather than a direct child selector. The H1 sits inside a content column div inside the article element, so a direct child selector won't reach it.

Packaging the Theme

Once all files are ready, create a folder named after your theme slug, place theme.json at the root, and add your tpl/ and includes/ subfolders with the correct files in each. Zip the folder, then rename the resulting zip file with the .carltheme extension. On Windows, a PowerShell script that copies and renames files into the correct structure and zips them in one command makes rebuilding fast and consistent whenever you update any source file.

Testing Before Distribution

Test every theme on a local or staging CARL install before distributing it. Verify the blog, full-width, and category templates all render correctly. Check the hamburger menu opens and closes on mobile. Run PageSpeed Insights on all three templates and confirm CLS is 0. Verify theme.json parses correctly, all ten include files are present, all three template files are in tpl/, and the install completes without errors on a clean test site with pages remapping correctly after install.

The CARL Magazine Theme

The Magazine Theme gives your CARL site a newspaper-style appearance: bold article headlines with a coloured accent bar, a structured sidebar with related posts, and a full-width banner header across the top of every page. It's designed for content publishers, affiliate sites, and anyone running a high-volume article site where speed and readability come first.

No External Dependencies

Unlike CARL's default Bootstrap templates, the Magazine Theme uses no external CSS framework. Every style is written natively and delivered as a single inline stylesheet. There are no CDN requests, no render-blocking external CSS files, and no dependency on any third-party service. Everything the theme needs is contained in the theme package itself.

Page Layouts

The Magazine Theme includes three layouts covering every standard page type in CARL. The blog layout is the standard article view: a large headline, a featured image, the article body, and a related posts sidebar on the right. A mid-article call-to-action slot is included for internal linking or promotions.

The full-width layout removes the sidebar and stretches the content to the full column width, making it well suited for landing pages and long-form content. The category layout displays all published pages in a directory as a two-column card grid, with each card showing the title, description, thumbnail, and a continue reading link, populated automatically with no manual configuration required.

Navigation

The desktop navigation is a full horizontal bar with support for drop-down menus. On smaller screens, it collapses to a hamburger icon. Tapping it slides in a full-screen navigation panel from the left, with all links clearly listed. The mobile panel is built by cloning the desktop nav in JavaScript, so there's only one nav to maintain, and the mobile view always stays in sync with the desktop version.

Performance

The Magazine Theme is built to score well on Google PageSpeed. All images reserve their space before loading, which eliminates layout shift during page load. The site header banner is preloaded so it's in the browser cache before the page layout requests it. There are no render-blocking external resources. On standard shared cPanel hosting, the blog layout scores 92 for performance and 100 for best practices on mobile. The full-width layout scores 99 for performance. Cumulative Layout Shift is 0 on both.

Setting Up Your Header Image

The Magazine Theme displays a full-width banner image at the top of every page. Upload your header image to your site's /images/ folder via cPanel File Manager or FTP. The image displays at a 3:1 aspect ratio, so a width of 1200px or wider is recommended. The WebP format delivers the best performance, though JPEG and PNG are also supported. Once uploaded, open site_header.txt in Include Files in your CARL admin and update the image filename to match the file you uploaded. Save and regenerate to apply the change.

Customizing the Navigation

The Magazine Theme navigation is controlled by your nav_include.txt include file, the same as all other CARL templates. Edit it in the Include Files in your admin panel. Because the nav is a PHP include rather than baked into each generated page, changes take effect immediately across your entire site without needing to regenerate. For a full walkthrough of working with include files, see How to manage include files in CARL.

Installing the Magazine Theme

Install the Magazine Theme the same way as any CARL theme. Go to Themes in the admin sidebar, upload magazine.carltheme, review the confirmation screen, click Install Theme, then regenerate all pages. For the full step-by-step process, see How to install a CARL theme.

How to Roll Back a Theme in CARL

Every time you install a theme in CARL, your previous template files and include files are saved automatically to a timestamped backup folder on your server. If you install a new theme and want to go back, everything you need is already there. The rollback process takes a few minutes and requires access to your server via cPanel File Manager or FTP.

Where the Backup Is Stored

Theme backups are stored in a timestamped folder inside your site's include files directory on the server. The folder name includes the date and time of the install, so you can identify which backup corresponds to which theme. If you've installed multiple themes, you'll have a separate backup folder for each install. Access them via cPanel File Manager or an FTP client.

What the Backup Contains

The backup covers your template files from admin/tpl/ and all include files from site_includes/. This is everything the theme system touches during an install. It does not cover your page content, images, database records, or any other part of your site. If you need a full site rollback rather than just a theme rollback, use CARL's Backup tool instead.

How to Restore the Previous Theme

Open cPanel File Manager or connect via FTP and navigate to the backup folder. Copy the template files back to admin/tpl/ and copy the include files back to site_includes/, overwriting the current versions. Take care to copy all files from both folders, not just some, since a partial restore will leave your site with a mixed set of files from two different themes.

Regenerate to Complete the Rollback

Once the files are restored, go to Pages in your CARL admin panel and run a bulk regeneration. This rewrites every published page using the restored template files. After regeneration, your site returns to the previous theme. Visit your live site to confirm everything is displaying correctly before considering the rollback complete.

Preventing the Need for a Rollback

The most reliable way to avoid rollbacks is to test a new theme on a staging installation before deploying it to your live site. Install the theme on a test CARL install, regenerate, and check every page type — blog layout, full-width layout, and category pages — before touching your live site. If everything looks correct on the test install, you can install with confidence on the live site.

How to Install a CARL Theme

Installing a theme in CARL is a two-step process: upload the package, then confirm the installation. CARL handles everything else — backing up your current files, extracting the new theme, remapping your pages, and registering the new templates. The whole process takes under a minute. Regenerating your pages afterward pushes the new look to your live site.

Before You Start

Have your .carltheme file downloaded and ready before opening the Themes page. The installer requires a valid theme package to proceed. It's also worth running a full site backup through CARL's Backup tool before making any major changes, since theme backups cover only templates and include files, not your page content or database.

Step 1: Open Themes

In your CARL admin panel, click Themes in the left sidebar. This opens the theme manager where you can upload and install theme packages.

Step 2: Upload Your Theme File

Click the upload area or drag your .carltheme file onto it. CARL reads the package immediately and validates its contents. Nothing is installed at this step. If the package is valid, a confirmation panel appears showing the theme name, version, author, and a summary of what will be installed.

Step 3: Review and Confirm

Check the confirmation screen to verify the theme details match what you intended to install. When you're satisfied, click Install Theme. CARL backs up your current files, extracts the new templates and include files to their correct locations on your server, registers the new templates in the database, and remaps all your existing pages to the new theme's layouts.

Step 4: Regenerate Your Pages

After the install completes, go to Pages in the sidebar and click Regenerate All. This rewrites every published page on your site, applying the new theme. Until you regenerate, your live pages still display the previous theme. Regeneration time depends on how many pages your site has, but on most sites, it completes in a few seconds.

After Regenerating

Visit your live site and confirm the new theme is displaying correctly. Check your navigation links, footer content, and sidebar. If the theme uses a header banner image, you may need to upload your header image and update the reference in your site_header.txt include file — each theme may expect a different image filename or dimensions. Run a Site Health check after regenerating to confirm all pages are in good shape.

How CARL's Theme System Works

CARL's theme system lets you change the entire look and structure of your site in a single operation. Upload a .carltheme file, confirm the install, and CARL replaces your templates, stylesheets, navigation, footer, and all site-wide include files at once. Every page on your site automatically switches to the new theme. No manual reassignment, no page-by-page updates.

What a Theme Is

A CARL theme is a complete site skin packaged as a single .carltheme file. Under the hood, it's a zip archive containing everything your site needs to look and function as designed: page layout templates, all CSS, navigation structure, footer, sidebar widgets, hub card grid, and the full set of include files that wire the layout together.

One file delivers the entire package.

CARL runs one active theme at a time across your entire site. Installing a new theme replaces the current one everywhere. There's no way to run different themes on different sections, but you can use different page types within a theme — for example, a blog layout for articles and a full-width layout for landing pages — to get the variation you need.

What Gets Installed

When you install a theme, CARL writes new versions of your template files and all site include files to your server. This covers your page layouts, stylesheet, navigation, footer, sidebar, hub card grid renderer, and header and footer scripts. Everything that controls how your site looks and is structured gets replaced in one pass.

Your page content is never touched. All your titles, meta descriptions, body copy, images, and settings remain exactly as they are. Themes control how pages look, not what's in them.

Automatic Backup Before Every Install

Before overwriting anything, CARL saves a timestamped copy of your current template files and include files to a backup folder on your server. If you install a theme and want to revert, the files you need are still there. For the full rollback process, see How to roll back a theme in CARL.

Pages Remap Automatically

CARL tracks which template type each page uses: blog layout, full-width layout, or category layout. When a new theme is installed, CARL automatically updates every page's template assignment to the new theme's equivalent layout. A page that was using the old blog layout switches to the new theme's blog layout without you having to touch it. The remapping happens as part of the install process.

Regeneration Completes the Switch

Installing a theme updates your template and includes files on the server, but your published pages are static files that were already written to disk under the previous theme. They continue serving visitors unchanged until you regenerate. After installing, go to Pages and run a bulk regenerate to rewrite every published page using the new theme. That's when the change becomes visible to your site visitors.

How to Secure Your CARL Include Files

Include files that display content only are low risk. Include files that accept user input, handle file uploads, or make database calls that carry real attack surface. The rules for securing them are the same rules that apply to any PHP form on any server: validate everything that comes in, sanitize everything that goes out, and never trust user-supplied data.

Sanitize All Output

Any user-supplied value that gets displayed back on a page must be sanitized before output. Use PHP's htmlspecialchars() on any value you echo back to the browser. This prevents cross-site scripting (XSS) attacks, in which malicious JavaScript is injected through a form field and executed in a visitor's browser. It's a one-line fix that applies to every field: names, emails, addresses, notes, anything a user typed.

Validate All Input Server-Side

Client-side validation in JavaScript improves the user experience but provides zero security. Any attacker can bypass it by submitting a request directly to your processor. Validate every field in PHP on the server before doing anything with the data. Check that required fields are present, that email addresses match the expected format, that ZIP codes are numeric and the right length, and that date fields contain valid dates. Reject anything that doesn't pass.

File Upload Security

File uploads are the highest-risk element in most include files. Validate the MIME type of every uploaded file server-side, not just the extension. Check file size against a maximum before processing. Store uploaded files outside public_html if they don't need to be publicly accessible, or in a dedicated uploads directory with an .htaccess file that prevents PHP execution inside it. Never trust the filename supplied by the user: generate your own filename on the server when saving the file.

CSRF Protection on Forms

Any form that performs an action, such as submitting a lead, processing a request, or writing to a database, should include a CSRF token. Generate a random token when the form page loads, store it in the session, include it as a hidden field in the form, and verify it matches on submission before processing anything. This prevents cross-site request forgery attacks, in which a malicious third-party site tricks a visitor's browser into submitting your form without the visitor's knowledge. CARL's own admin forms use this pattern throughout.

Honeypot Fields for Spam

For public-facing forms that don't require a login, a honeypot field is a simple and effective spam deterrent. Add a hidden form field that legitimate visitors will never fill in. If the field contains any value upon submission, silently discard the request. Bots that fill in every field get rejected without any friction for real visitors. This is lighter than a CAPTCHA and effective against most automated spam submissions.

Performance: Keep Includes Lean

Include files that run on every page load should be as lightweight as possible. Avoid database queries in sidebar includes if you can cache the output instead. Avoid external API calls in any include that appears site-wide: a slow or unavailable API will slow down or break every page that includes it. Reserve heavy logic for page-specific includes where the impact is contained to a single page rather than your entire site.

How to Build a Custom Include File in CARL

Building a custom include file in CARL doesn't require programming experience. If you can write HTML, you can build an include file. If you need PHP logic in it, the same rules apply as any PHP file: write the code, test it, save it. The process from idea to deployment is straightforward.

Step 1: Decide What the Include Will Do

Be clear about what the file will contain before you create it. A promotional banner is a simple HTML block. A contact form is HTML with a PHP processor handling the submission. A sidebar widget displaying recent posts is a PHP snippet that queries the database. The complexity of the include is determined entirely by what you need it to do, not by any CARL requirement.

Step 2: Create the File

In the CARL admin panel, go to Include Files and create a new file. Give it a descriptive name that makes its purpose clear: promo_banner.txt, contact_widget.txt, booking_form.txt. The .txt extension is the convention CARL uses for include files, though the file can contain any valid HTML or PHP regardless of extension. Write your content in the editor and save.

Step 3: Place It on a Page

You have two ways to deploy a custom include file. The first is through a page's PHP Snippet field: add a standard PHP include call referencing the file, and it will appear at the bottom of that page's content area when generated. The second is through a template file: add the include call directly to the template, and every page that uses that template gets the include automatically. Use the PHP Snippet approach for page-specific includes and the template approach for includes that belong to a category of pages.

Step 4: Test Before Bulk Deploying

If you're adding the include to a template that affects many pages, test it on a single page first. Add the include call to one page's PHP Snippet field, generate that page, and check it in a browser. Confirm that the include renders correctly, that any PHP logic executes without errors, and that the layout looks right. Once you're satisfied, move the include call into the template and bulk-regenerate.

Updating the Include Later

One of the advantages of the include system is that updating is as simple as building. Open the file in Include Files, make your changes, save, and run a bulk regenerate. Every page that references the file gets the update. If the include is only on specific pages via their PHP Snippet fields, regenerate only those pages. Either way, you're editing one file regardless of how many pages it appears on.

How CARL's Site-Wide Include Files Work

CARL ships with a set of standard include files that every page template references by default. These files control the site-wide elements that appear on every page: your header, navigation, footer, sidebar content, search bar, signup form, and social links. Each one is a separate file in your site_includes/ folder, and each one is yours to edit.

The Standard Include Files

CARL's default templates expect seven include files by name. site_header.txt contains your site header HTML. nav_include.txt contains your navigation menu. footer_include.txt contains your footer. search_bar.txt contains the site search widget. carl_signup_form.txt contains your email signup form. recent_posts.txt contains the recent posts sidebar widget. social_link_list.txt contains your social media links. These filenames are hardcoded into the template files, so the names must match exactly.

How They Get Into Your Pages

Each template file contains a PHP include call for each of these files, wrapped in a file existence check. If the file exists, its contents are included at that position in the page. If the file doesn't exist, that position is simply empty. This means you can choose which elements appear on your site by controlling which include files you create and populate. A template that references carl_signup_form.txt won't show a signup form until that file exists and contains form code.

Editing Site-Wide Elements

To change your navigation, open nav_include.txt in the Include Files manager, make your edits, save, and run a bulk regenerate. Every page on your site gets the updated navigation in a single pass. The same process applies to your footer, your header, your signup form, or any other standard include. There is no theme customizer, no menu management screen, no widget drag-and-drop interface. You edit the file and regenerate.

Customizing Per-Template

Different templates can reference different include files. If you have a landing page template that shouldn't show the sidebar or signup form, simply omit the include calls for those elements from that template. A blog template might show the full sidebar with recent posts and social links. A sales page template might show nothing but the header and footer. Each template decides independently which includes it pulls in, giving you precise control over what appears on each type of page.

Header Scripts and CSS

Two additional include files sit outside the visible layout: header_scripts.txt and site_css.txt. These are injected into the section of every page. header_scripts.txt is where your Google Analytics tag, custom fonts, or any other third-party head code lives. site_css.txt is where you add custom CSS that applies across your entire site. Update either file and bulk regenerate to push the changes everywhere.

What You Can Build With CARL Include Files

Because include files can contain any valid PHP and HTML, they're not just for navigation and footers. They're a full application injection point. Anything that runs on PHP can be deployed to a CARL page via an include file, without a plugin, third-party service, or recurring subscription.

Lead Generation Forms

A multi-step quote form, a contact form, a callback request widget — all of these can be built as include files and placed on any page. The form submits to a PHP processor on your server, which handles validation, stores the lead, sends a notification email, and redirects back with a success or error status. The entire flow runs on your own hosting account with no external dependency.

Two real examples: a 4-step moving company quote form that walks visitors through their contact details, pickup address, destination, and photo uploads, with client-side step validation and a progress indicator. And a pest control service request form with a honeypot field for spam protection and a direct post to a leads processor on a subdomain.

Both are self-contained include files. No WPForms license. No Gravity Forms subscription. No form builder account.

Booking and Appointment Widgets

A service business that needs a booking form can build one as an include file: date picker, time slot selection, service type, contact fields, and a submission handler that writes to the database and sends a confirmation email. Place it on a service page, a landing page, or a dedicated booking page. Update the available time slots by editing one file.

Price Calculators and Estimators

A calculator that takes user inputs and returns a price estimate is a natural fit for an include file. The logic runs in JavaScript on the client side, or in PHP if the calculation requires server-side data. Either way, the whole thing lives in a single file that can be included on any page.

Promotional Banners and Announcements

A site-wide promotional banner — a sale, a deadline, a new product announcement — can be managed through a single include file. Add it to your template, set it live, and it appears on every page instantly. When the promotion ends, remove the content from the file and run a bulk regeneration. No plugin toggle. No widget management screen. One file edit.

The WordPress Comparison

WordPress users solve these problems with plugins: WPForms or Gravity Forms for lead capture, a booking plugin for appointments, a calculator plugin for estimators, and a notification bar plugin for banners. Each plugin is a subscription, a potential conflict, and a door into your site controlled by someone else. CARL users write PHP. The functionality is identical. The cost and the risk are not.

How CARL's Includes System Works

CARL's includes system lets you define a block of HTML or PHP once and have it appear on every page that needs it. Your site navigation, footer, sidebar, and signup form all work this way. The content lives in a single file. Every page that references it pulls from that file at the time of generation. Change the file, regenerate your pages, and the change is everywhere.

What an Include File Is

An include file is a plain text file stored in your site_includes/ folder inside public_html. It contains whatever you want it to contain: HTML, PHP, JavaScript, a form, a widget, a navigation menu. There's no special syntax and no CARL-specific format. It's just a file with content, and CARL pulls it into your pages using a standard PHP include call.

How Templates Use Include Files

Every CARL page template contains PHP include calls that reference specific files in site_includes/. When CARL generates a page, it builds the complete PHP file from the template, writing those include calls into the output. When a visitor loads the page, PHP executes the include calls, and the content from each file is inserted at the correct position. Your navigation appears at the top, your footer at the bottom, your sidebar in the right column, exactly where the template expects them.

The Power of a Single Source File

Because every page references the same file, there is only ever one version of your navigation, one version of your footer, one version of your signup form. You don't maintain copies. You don't risk them falling out of sync. You update the source file, and every page on your site reflects the change on the next load. A site with 500 pages gets a navigation update in the same amount of time as a site with 5.

Include Files vs. Page Content

Include files handle everything that surrounds your content: layout chrome, site-wide elements, and reusable blocks. Page content lives in the page record itself. This separation is deliberate. It keeps your content clean and portable, and it keeps your site infrastructure manageable. If you ever change your navigation structure, you only need to change one file. Your page content is untouched.

Beyond Headers and Footers

The system isn't limited to structural elements. Because include files can contain any valid PHP code, you can use them to deploy interactive applications, lead-generation forms, booking widgets, and multi-step quote systems directly into any page. The same mechanism that puts your footer on every page can put a fully functional quote form on a specific page. For a full look at what's possible, see What you can build with CARL include files.

How to Manage Include Files in CARL

Include files are text files stored in your site_includes/ folder that gets pulled into your published pages at the point defined by your template. Your site header, navigation, footer, sidebar, signup form, and search bar all work this way. Edit the file once, regenerate your pages, and every page on your site reflects the change.

Where Include Files Live

All include files are stored in the site_includes/ directory inside your public_html folder. CARL's default templates expect specific filenames: site_header.txt, nav_include.txt, footer_include.txt, search_bar.txt, carl_signup_form.txt, recent_posts.txt, and social_link_list.txt. These filenames are referenced directly in the template files, so the name has to match exactly.

Managing Include Files in the Admin Panel

In the CARL admin panel, go to Include Files. You'll see a list of all files currently in your site_includes/ directory. Click any file to open it in the editor. Make your changes and save. The updated file is written to disk immediately. Your published pages don't reflect the change until you regenerate them, since the included content is baked into the static file at generation time.

Pushing Changes to All Pages

After saving changes to an include file, run a bulk regenerate to push the update across your entire site. Every published page that uses a template referencing that include file will be rebuilt with the new content. For a site with hundreds of pages, this takes seconds. For the full walkthrough, see How to bulk regenerate pages in CARL.

Creating Custom Include Files

You're not limited to CARL's default include filenames. Create any file in site_includes/ with any name you choose and reference it in a template or a page's PHP Snippet field using a standard PHP include call. This is how you add custom sidebar widgets, promotional banners, or any reusable block of HTML or PHP to your pages without editing every page individually. For a full walkthrough of building custom include files, see How to build a custom include file in CARL.

Include Files Are Not Templates

Include files handle content blocks. Templates handle page structure. The distinction matters: changing a template affects the layout of every page using it, while changing an include file only affects the content of the block that file provides. Keep layout decisions in templates and content decisions in include files, and site-wide updates stay straightforward.

How CARL's Hub Renderer Works

CARL's hub renderer automatically generates a grid of article cards for any directory on your site. Point it at a directory, and it queries the database for all published pages in that directory and renders them as a Bootstrap card grid, complete with title, meta description, and a read more link. No manual list maintenance, no editing the hub page every time you publish a new article.

How It Works

The hub renderer is a PHP include that accepts a directory path as its input. When the hub page loads, the renderer queries the database for all published pages whose directory matches the one you specified, orders them by publish date, and renders a card for each. Add a new article to the directory, publish it, and it appears on the hub page automatically on the next load. Nothing else required.

What Each Card Contains

Each card displays the page title, the meta description, and a link to the full article. This is why well-written meta descriptions matter on every page: the meta description is what visitors read on the hub page when deciding which article to click. A blank or weak meta description produces a weak card. The Site Health checker flags pages with missing meta descriptions for exactly this reason.

Hub Pages in CARL

A hub page in CARL is just a regular page with the hub renderer included in its PHP Snippet field and a short introductory paragraph in the body. The renderer handles everything else. This is why hub pages should never contain manual lists of article links: the renderer already outputs those cards dynamically, and manual links would duplicate them and fall out of sync every time you add or remove an article.

Using the Hub Renderer for Any Directory

The hub renderer isn't limited to wiki clusters. You can use it on any page where you want an auto-generated index of content from a specific directory: a blog index, a use case listing, a product documentation section. Any directory with published pages in it can have a hub page built this way. The renderer reads from the database, so the output is always up to date without any manual maintenance.

How CARL's Site Search Works

CARL includes a built-in site search that lets visitors search your content without a third-party service, a search plugin, or an API subscription. The search functionality is part of CARL's core install. You add the search bar to your pages using an include file, and the search dashboard in the admin gives you visibility into what your visitors are looking for.

The Search Bar Widget

CARL's search bar lives in an include file called search_bar.txt. If you're using the Bootstrap Blog template, the search bar is already present in the sidebar by default. It's one of the standard include files that the Blog template loads automatically, so any page using that template has search built in without any additional setup required.

For pages using a different template, or for pages where you want the search bar in a different position, you add it through the PHP Snippet field. Open the page in the editor, go to the PHP Snippet field, open the Include Picker, select search_bar.txt, and click Insert. When you regenerate the page, the search bar is present at that position.

How Search Works on a Static Site

CARL pages are static PHP files, which means there's no dynamic page assembly happening at request time. The search system works within that constraint: when a visitor submits a search query, the request goes to CARL's search handler, which queries the database for matching page records and returns the results. The search results page is served dynamically, while the individual content pages themselves remain static files.

This is a clean division of responsibility. Your content pages are fast, secure, static files. Search is a separate, contained operation that only runs when a visitor actively requests it. The search function doesn't add any overhead to regular page loads.

The Search Dashboard

In the CARL admin panel, go to Tools, then Search. The search dashboard shows you what queries visitors have been entering on your site. This data is genuinely useful for content planning: recurring searches for topics you haven't covered yet are a direct signal of what your audience wants. If visitors keep searching for something and not finding it, that's an article to write.

Search and Your Content Structure

CARL's search indexes your published pages by their titles and content. Pages that are clearly titled, well-structured, and contain the specific language your audience uses will return better search results than pages with vague titles or thin content. The same principles that make a page rank well in Google also ensure it surfaces correctly in CARL's internal search.

Hub pages and index pages are generally less useful search results than individual articles. If you want to refine what appears in search results over time, the search dashboard gives you the data to make those decisions based on what visitors are actually looking for rather than what you assume they want.

Setting Up Search on a New Install

If you're using the Bootstrap Blog template for your articles, the search is already in place, and nothing further is needed. If you're using a custom template and want search available sitewide, add search_bar.txt to your template directly via Include Files so it appears on every page using that template without requiring individual PHP snippet insertions. For a full walkthrough of how include files work in CARL, see How to manage include files in CARL.

How CARL Optimizes Images

When you upload an image through the CARL admin panel, CARL processes it automatically before saving it to your server. Compression is applied, oversized images are resized to a sensible maximum width, and the file is converted to WebP format. By the time the image is available to use on a page, the heavy lifting is already done.

Why Image Optimization Matters for SEO

Page speed is a ranking factor. Large, unoptimized images are among the most common reasons pages load slowly, and slow pages rank lower and convert worse. CARL handles optimization at upload time, so you never have to think about it. You upload the photo from your phone or camera, and what ends up on your server is a compressed, correctly sized WebP file, a fraction of the original size.

WebP Conversion

WebP is the image format Google recommends for web use. It produces smaller file sizes than JPG or PNG at equivalent visual quality, which means faster page loads and lower bandwidth usage. CARL converts uploaded images to WebP automatically using PHP's GD library. The original file format doesn't matter: JPG, PNG, and GIF uploads are all converted to WebP on your server.

Resizing and Compression

CARL resizes images that exceed the configured maximum width, scaling them down proportionally. Images already within the limit are left at their original dimensions. Compression is applied during the WebP conversion process. The result is an image that looks correct on your pages without carrying the file weight of an unoptimized original.

What Happens to the Original

CARL works on the uploaded file during processing and saves the optimized WebP version to your images directory. You don't need to pre-optimize images before uploading. Upload what you have, and CARL handles the rest. The Image Manager in the admin panel displays your uploaded images and their file sizes, so you can see exactly what's on your server.

How CARL Handles Popup Management

CARL includes a built-in popup manager that lets you create and deploy popups on any page without a plugin or third-party service. Popups are configured in the admin panel and written into the generated page file, so they load instantly with no external script required.

Popup Trigger Types

CARL supports two trigger types: timed and exit-intent. A timed popup appears after the visitor has been on the page for a specified number of seconds. An exit-intent popup fires when the visitor's cursor moves toward the top of the browser window, indicating they're about to leave. You set the trigger type and timing when building the popup, with no code required.

Creating a Popup

In the CARL admin panel, go to Popup Manager. Create a new popup and fill in the content: headline, body text, and an optional button with a label and URL. Set the trigger type and, for timed popups, the delay in seconds. Give the popup a name for identification and save it. The popup is now available to assign to any page on your site.

Assigning Popups to Pages

When editing a page in CARL, the popup field lets you select any saved popup to attach to that page. When you generate the page, CARL writes the popup HTML and trigger logic directly into the file. The popup runs from code already present in the page, with no dependency on an external popup service loading at runtime.

Frequency Control

CARL sets a cookie when a visitor dismisses a popup so it doesn't reappear on every visit. The cookie has a configurable duration, so you control how long a visitor is suppressed before the popup shows again. This keeps the experience from becoming intrusive while still re-engaging visitors who return after the suppression window has expired.

Updating Popups Across Pages

Like the CTA Builder, a single popup record can be assigned to multiple pages. Update the popup content once, then run a bulk regenerate to push the change across every page that uses it. If you want to remove a popup from all pages at once, clear the popup assignment and regenerate. No page-by-page editing required.

How CARL's CTA Builder Works

CARL's CTA Builder lets you create styled calls to action and place them on any page without touching a template file. You build the CTA once in the admin panel, assign it to a page, and CARL writes it into the generated file at the correct position when you publish or regenerate.

What a CTA Is in CARL

A CTA in CARL is a configurable block: a headline, supporting text, a button label, and a button URL. You control the styling through the builder interface. The output is a self-contained HTML block injected into the page at the point defined by your template. You don't need to write any HTML or edit any files to produce it.

Creating a CTA

In the CARL admin panel, go to CTA Builder. Click to create a new CTA and fill in the fields: headline, body text, button label, and destination URL. Give the CTA a name so you can identify it when assigning it to pages. Save it, and it becomes available to use on any page on your site.

Assigning a CTA to a Page

When creating or editing a page, the CTA field lets you select any saved CTA to attach to that page. When you generate the page, CARL pulls the CTA content and writes it into the file. If you update the CTA record later and regenerate the page, the page reflects the updated version. One CTA can be assigned to multiple pages, so a single update propagates to every page where it's used.

Updating CTAs Across Multiple Pages

This is where the CTA Builder earns its place. If you're running a promotion and need to update the button text or destination URL across 50 pages, you change the CTA record once and run a bulk regenerate. Every page using that CTA is updated in a single pass. No manual editing, no risk of missing a page, no inconsistency across your site. For how to run a bulk regeneration, see How to bulk regenerate pages in CARL.

How CARL Integrates With Kit

CARL connects directly to Kit (formerly ConvertKit), so new subscribers are added to your Kit list the moment they sign up. When the integration is active, CARL stores the subscriber record locally and forwards it to Kit simultaneously. You get a copy on your own server, and the subscriber lands in Kit ready to receive your sequences.

How the Integration Works

When a visitor submits your signup form, CARL calls the Kit API in the background using your API key and the form ID you've configured. Kit processes the submission and adds the subscriber to the associated form, which triggers any automation or sequence attached to that form. From the subscriber's perspective, the experience is identical to submitting a native Kit form, just hosted on your domain.

Setting Up the Integration

In the CARL admin panel, go to Settings and open the Subscribers tab. Enter your Kit API key and your Kit form ID. Your API key is available in your Kit account under Settings, then Developer. Your form ID is the number in the URL when you open a form in the Kit dashboard. Save the settings, and the integration is active immediately for all new signups through CARL's native form.

Finding Your Kit Form ID

In your Kit account, go to Grow, then Landing Pages and Forms. Open the form you want to connect. Look at the URL in your browser. The form ID is the number at the end of the URL. It typically looks like a 7-digit number. Copy that number into the Kit Form ID field in CARL's Settings. CARL uses this ID to submit new subscribers to the correct form, triggering the appropriate automation in Kit.

What Gets Sent to Kit

CARL sends the subscriber's email address and first name to Kit on each new signup. Kit matches these to its standard subscriber fields. Tags, custom fields, and sequences are managed on the Kit side through your form's automation settings, not through CARL. If you want new subscribers to receive a specific sequence or be tagged on signup, configure that in Kit on the form itself.

Fallback Behavior

If the Kit API call fails for any reason, CARL still saves the subscriber record locally. The signup is never lost. Failed Kit submissions are logged so you can identify them and add them to Kit manually if needed. This means a temporary Kit outage or API issue won't result in lost subscribers on your end.

How to Embed a Signup Form in CARL

CARL offers two ways to add a signup form to your site: a native form that submits to CARL's built-in subscriber system, and an embed code option for pasting a form from an external platform like Kit. Both methods work on any published page.

Using CARL's Native Signup Form

CARL's native form is included via the include file system. The signup form is stored as an include file and can be added to any page template or injected into individual pages through the Head Injection field. When a visitor submits the native form, the data is stored directly in your CARL subscriber database. No external service is required.

The native form collects an email address and an optional name field. The form handles its own validation, duplicate checking, and confirmation message. You can customize the form's appearance by editing the include file or adding CSS to your site stylesheet.

Embedding a Form From Kit

If you're using Kit as your email platform, you can paste your Kit form embed code directly into any CARL page using the Head Injection field or the page body. Kit provides the embed code from your Forms section in the Kit dashboard. Copy the inline or hosted form embed snippet, paste it into the relevant field in the CARL page editor, and regenerate the page. The form renders and submits directly to Kit.

This approach is useful when you want Kit to handle confirmation emails, tags, and sequences from the moment of signup. The subscriber goes straight into Kit without any manual export or sync step required.

Adding a Form to Multiple Pages at Once

The most efficient way to add a signup form across your entire site is through an include file. Save your form code to a site, include it in your page template, and every page using that template will display the form. If you update the form later, update the include file and run a bulk regenerate to push the change to all existing pages at once. For information on how to manage include files, see "How to manage include files in CARL".

Sidebar and Inline Placement

CARL's default blog templates include a sidebar column that already pulls in a signup form include file. If you're using one of those templates, the form appears automatically on every page using that layout once the include file contains your form code. For pages using a single-column template or a custom layout, add the form include call directly to the template file, or paste the form code into the page body at the point where you want it to appear.

How CARL's Subscriber System Works

CARL includes a built-in email subscriber system that collects and manages your list directly on your server. Visitors sign up through a form on your site, their details are stored in your database, and you can export the list at any time. No third-party list service is required to start collecting subscribers.

How Signups Work

When a visitor submits your signup form, CARL records their email address, an optional name field, the page they signed up from, and a timestamp. Each new subscriber is added with confirmed status by default, which means they're immediately on your list and no email verification step is required. If you're sending to a platform that requires confirmed opt-in, you can use the Kit integration to handle that on the platform side.

Subscriber Records

Each subscriber record includes their email, name, sign-up date, source page, and current status: active, unsubscribed, or bounced. The status can be changed manually from the Subscribers dashboard in the admin panel. Active subscribers appear in your exports. Unsubscribed and bounced records are retained in the database but excluded from exports by default, so you have a complete history without contaminating your active list.

The Subscribers Dashboard

In the CARL admin panel, the Subscribers section shows your total subscriber count, a breakdown by status, and a list of recent signups. You can search by email or name, filter by status, and delete individual records. The dashboard also shows which pages are generating the most signups, so you can see at a glance which forms and content are working.

Exporting Your List

The export function downloads your active subscriber list as a CSV with one click. The file includes email, name, signup date, and source page for every active subscriber. Use this to import into your email-sending platform, back up your list, or cross-reference it against your sending platform's own list. Your subscribers are in your database on your server, not locked inside a platform you don't control.

Kit Integration

If you're using Kit as your email sending platform, CARL can push new subscribers directly to your Kit list at signup instead of storing them locally only. See How CARL integrates with Kit for the setup steps. Both systems can run in parallel: CARL stores the record locally and forwards it to Kit at the same time, so you always have a copy of your list on your own server regardless of what happens with your Kit account.

How CARL Restricts Pages to Members Only

When you generate a members-only page in CARL, the access control code is written directly into the page file. There's no middleware, no separate authentication layer, and no request routing through the admin panel. The protection is built directly into the file that lives on your server.

How the Guard Works

At the top of every protected page CARL generates, an access guard is injected before any content is rendered. The guard reads the member session cookie, validates the token against the database, confirms the account is active, and checks the member's access level against the level required for that page. All of this happens before a single line of page content is sent to the browser.

If the visitor has no valid session cookie, they're redirected to /members/login.php with the current URL attached as a redirect parameter. After logging in, they're returned to the page they were trying to reach. If they're logged in but their access level is too low, they're redirected to /members/upgrade.php instead.

Setting the Required Access Level

When creating or editing a page in CARL, the members' access setting lets you choose which membership level is required: free or premium. Free-level pages are accessible to any logged-in member regardless of their tier. Premium-level pages are restricted to members with premium access only. Pages with no access restriction are public and visible to everyone.

What Happens if the Database Is Unavailable

Because the guard makes a database call to validate the session, a protected page cannot be served if the database is down. The guard will fail to load the session and treat the visitor as unauthenticated, redirecting them to the login page. This is the correct behavior: it's better to redirect than to accidentally serve protected content. Your public pages, which have no guard code, are unaffected and continue to load from disk as normal.

Regenerating Protected Pages

If you change the access level setting on a page after it has already been published, you need to regenerate the page for the change to take effect on disk. The guard code embedded in the existing file still reflects the old setting until you regenerate. Use bulk regenerate when updating access levels across many pages at once.

How to Create a Members-Only Content Area in CARL

A members-only content area in CARL is a section of your site where some or all pages require a login to view. You can run free and premium tiers on the same site, with different pages accessible to each level. The setup is entirely managed through the page editor and your Members settings, with no code required.

Plan Your Access Structure First

Before creating any pages, decide which content is public, which is free-member-only, and which is premium-only. CARL supports three states for any page: public (accessible to all logged-in members), accessible to all logged-in members, or accessible to premium members only. A clear structure before you start saves you from having to change access levels and regenerate pages later.

Set Up the Member Pages

Your members' area needs a small set of supporting pages: a registration page, a login page, a member dashboard, and an upgrade page for logged-in visitors trying to access premium content. Create these first using the appropriate CARL member templates before you start restricting any content pages.

The login page must be at /members/login.php since that's where CARL's access guard redirects unauthenticated visitors. For the full setup walkthrough, see How to set up member registration in CARL.

Restrict Your Content Pages

With the supporting pages in place, open any content page you want to protect in the CARL page editor. Find the members' access setting and select the required level: free membership or premium. Save and generate the page. The access guard is written into the file at that point. Repeat for every page you want to restrict.

There's no requirement that all protected pages use the same access level. You can have a mix of public articles, free-member guides, and premium content on the same site. Each page has its own access level.

Directing Visitors to Register

Public pages that preview your members' content are your main conversion tool. Link to the registration page from those public pages at the natural point where a visitor would want more. A public introduction page that ends with a clear call to action linking to registration converts better than a wall that simply redirects visitors without explanation.

Managing the Content Area Over Time

As your members area grows, use the Members dashboard to monitor signups, approve pending registrations if you're running approval mode, and upgrade free members to premium when appropriate. If you restructure your access levels at any point, remember to regenerate the affected pages so the updated guard code is written to disk. The content itself doesn't change during a regeneration, only the access rules embedded in the file.

How to Set Up Member Registration in CARL

Before visitors can register as members on your CARL site, you need to create the registration and login pages and configure the registration mode in Settings. The setup takes a few minutes and doesn't require any code.

Configure Registration Settings

In the CARL admin panel, go to Settings and open the Members tab. The registration mode setting controls how new signups are handled. Set it to open if you want new accounts to become active immediately after registration. Set it to approval-required if you want to review and manually approve each registration before the account becomes active. You can change this setting at any time without affecting existing members.

Create Your Member Pages

CARL's membership system requires a set of pages on your site to handle the member-facing flows. At minimum, you need a registration page, a login page, and a members' dashboard page. In the CARL admin, create these pages using the members-specific templates. The templates include the forms and logic for each step — registration, login, logout, and session handling — so there's no code to write.

The login page should be published at /members/login.php. CARL's access guard redirects unauthenticated visitors to that exact path when they attempt to reach a protected page. If you publish the login page at a different URL, update the redirect path accordingly.

Open Registration

With open registration enabled, a visitor fills out the registration form with their email, username, and password. CARL validates the input, checks for duplicate emails and usernames, creates the account with active status, sets the session cookie, and logs them in immediately. The whole process is a single form submission with no email verification step required.

Approval-Required Registration

With approval mode enabled, the registration process is the same from the visitor's side, but the account is created with pending status instead of active. The visitor sees a confirmation message telling them their account is awaiting approval. In your admin panel, go to Members and filter by the pending status to see registrations awaiting review. Click approve to activate the account, or delete it if you don't want to grant access.

Managing Members After Setup

Once registration is live, new members appear in the Members dashboard as they sign up. You can change any member's access level from free to premium at any time, suspend accounts without deleting them, and reinstate suspended accounts. If a member's email matches an existing subscriber in your email list, CARL links the two records automatically so you can see the connection between your members and your email audience.

How CARL's Members Area Works

CARL includes a built-in membership system that lets you restrict pages to registered members. There's no plugin, no third-party service, and no separate membership platform to manage. Registration, login, session handling, and access control all run directly on your server as part of CARL.

Access Levels

CARL offers two membership levels: free and premium. Free membership is open to anyone who registers. Premium membership is for paid or manually upgraded accounts. When you restrict a page, you choose which level is required to view it. A premium page is inaccessible to free members. A free-tier member's page is inaccessible to visitors who aren't logged in.

How Sessions Work

When a member logs in, CARL creates a session token and sets a secure, HTTP-only cookie in the browser with a 30-day expiry. The token is hashed before it's stored in the database, so the raw session value is never retained on the server. On each request to a protected page, CARL checks the cookie, validates the session against the database, confirms the member's account is active, and verifies their access level before allowing the page to load.

If the session has expired or the cookie is missing, the visitor is redirected to the login page, with the original URL included as a redirect parameter, so they land back on the correct page after logging in. If they're logged in but their access level is insufficient, they're redirected to an upgrade page instead.

Registration Modes

Registration can be set to open or approval-required in your Members settings. With open registration, new accounts become active immediately after signup. Once approval is required, new accounts remain pending until you approve them from the Members dashboard in the admin panel. The approval mode is useful when you want to control who gets access rather than letting anyone register freely.

Password Requirements

CARL enforces a minimum password standard on registration: at least 8 characters, one uppercase letter, and one number. Passwords are stored as bcrypt hashes. The plain-text password is never written to the database or any log file.

The Members Dashboard

In the CARL admin panel, the Members section shows a summary of total members broken down by status (active, pending, suspended) and access level. From there, you can approve pending registrations, suspend accounts, change a member's access level, and delete members. Each member record shows their email, username, registration date, last login, and current status.

How to Read Your Link Reports in CARL

CARL's link reports show you exactly what's happening with every tracked link on your site: how many clicks each link received, where those clicks came from, which countries they originated in, and how performance breaks down across your link groups. Everything is filterable by date range, so you can isolate any period you need.

Accessing the Reports

In the CARL admin panel, go to Link Tracker and click the Reports button in the top bar. The reports page opens with a default date range applied. You can adjust the from and to dates to cover any period, filter by a specific link or link group, and choose whether to include bot clicks in the totals. Bot clicks are excluded by default because they inflate the numbers without reflecting real visitor interest.

The Summary Panel

At the top of the reports page, a summary shows total clicks, human clicks, bot clicks, and unique IPs for the selected period and filters. Human clicks are the number you should focus on. Unique IPs give you a rough sense of how many distinct visitors clicked, since the same IP clicking multiple times counts once in that figure.

Clicks Over Time

Below the summary, a chart plots daily click totals across your selected date range. Gaps in the chart are genuine zero-click days, not missing data. Use this view to spot spikes after a new article goes live, a social post gets traction, or a campaign starts sending traffic. Flat lines between spikes tell you which links are passive earners versus which ones need fresh promotion.

Per-Link Breakdown

The per-link table ranks every link by human clicks for the selected period. Each row shows the link label, short code, redirect type, group, total clicks, human clicks, unique IPs, and the timestamp of the last click. Links with zero clicks during the period still appear in the table, making it easy to identify links that have gone cold and may need attention.

Referrers and Countries

The referrers breakdown shows the top sources sending clicks to your tracked links, so you can see whether traffic is coming from organic search, direct visits, social referrals, or specific pages on your own site. The countries breakdown shows where your clickers are located by country code. Both tables are limited to the top 20 results for the selected period.

Exporting the Data

The export function on the reports page downloads the full click log for the selected filters in CSV format. Each row contains the click timestamp, link label, short code, redirect type, group name, referrer, country code, user agent, and a bot flag. Use the export when you want to analyze the raw data in a spreadsheet or cross-reference click activity against your affiliate network's own reporting.

How to Cloak Affiliate Links in CARL

Link cloaking keeps your domain in the visitor's browser address bar when they click an affiliate link. Instead of the visitor seeing the affiliate network's URL, they stay on your domain throughout the visit. CARL offers two cloaking methods: iframe cloaking and JavaScript cloaking.

Why Cloak Affiliate Links

Cloaked links look cleaner and more trustworthy to visitors. A URL like yoursite.com/go.php?code=abc123 reads better than a raw affiliate URL with tracking IDs appended. It also protects your affiliate relationships: competitors can't identify which programs you're promoting just by hovering over your links. And because all your links run through your own domain, you keep full control over where they point at any time.

Iframe Cloaking

Iframe cloaking loads the destination page inside a full-screen, borderless iframe. Your domain stays in the address bar for the entire visit. From the visitor's perspective, they've arrived at the destination. From the browser's perspective, they're still on your site.

The iframe method is the default cloaking option in CARL and works well for most affiliate destinations. The one situation where it won't work is when the destination site sends an X-Frame-Options: DENY or X-Frame-Options: SAMEORIGIN header, which instructs browsers to refuse to load the page inside a frame. If you notice a cloaked link displaying a blank page, that's likely the cause. Switch that link to JavaScript cloaking instead.

JavaScript Cloaking

JavaScript cloaking serves a minimal, noindexed page that immediately bounces the visitor to the destination via a client-side redirect. The transition is nearly instant. Search engines see a noindex, nofollow page and don't follow the link, which keeps the affiliate URL out of Google's index. Visitors with JavaScript disabled see a plain fallback link instead.

JavaScript cloaking is the right choice for destinations that block iframes, or for any situation where you want the redirect to be clean and direct rather than frame-based.

301 and 302 Redirects

If you don't need cloaking, CARL also supports standard 301 and 302 redirects. A 301 tells search engines the destination is permanent and passes link equity. A 302 signals a temporary redirect and doesn't pass equity. Neither keeps your domain in the address bar. Use these when you want a clean, short URL that simply redirects rather than a cloaked link.

Setting the Redirect Type

When creating or editing a link in the Link Tracker, select the redirect type from the dropdown. You can change the type on any existing link at any time without affecting its short code or click history. If you're unsure which method to use, start with iframe cloaking and switch to JavaScript cloaking if the destination doesn't load correctly.

How CARL's Feedback System Works

CARL's feedback system adds a reaction widget to your published pages. Visitors can respond to your content with one of 5 reactions: upvote, funny, love, angry, or sad. The counts are visible on the page in real time, and the results are collected in your admin panel so you can see how your content is landing.

How the Widget Works

The feedback widget is included on pages via CARL's include file system. When a visitor clicks a reaction, the vote is submitted to the server and the count updates on the page immediately without a reload. If a visitor clicks the same reaction again, the vote is removed. If they click a different reaction, their vote changes to the new one. Each visitor can hold one active reaction per page at any time.

The system records which reaction each visitor left on each page, so when they return, their previous reaction is highlighted. The widget shows them where they stand without requiring an account or login.

Spam Protection

Votes are rate-limited per IP address in an hourly window. If the same IP submits an unusually high number of reactions within an hour, further votes from that address are blocked until the window resets. This keeps the counts meaningful without requiring captchas or friction for genuine visitors.

The Feedback Dashboard

In the CARL admin panel, go to Tools and then Feedback. The dashboard shows a summary of total votes across your site broken down by reaction type, a chart of vote activity over the last 30 days, and a ranked list of your most-reacted pages. Each page in the list shows its individual reaction breakdown, so you can see not just which pages got the most engagement but what kind of engagement they received.

From the dashboard, you can also reset votes for any individual page and export the full vote dataset. The export is useful if you want to analyze reaction data outside the admin panel or keep a record before clearing old data.

Adding the Widget to Your Pages

The feedback widget is automatically included in CARL's default templates. If you've built a custom template and want the widget on those pages, add the feedback include call to your template file. Any page using a template that includes the widget will display reactions. Pages on templates without it won't, which gives you control over where feedback appears without needing to configure it page by page.

How CARL's Built-In Analytics Work

CARL includes a built-in analytics system that tracks visitor activity directly on your server. No third-party service required, no data leaving your hosting account, no cookie consent banner forced on you by a tracking platform you don't control. The data is yours, and it stays on your server.

How Tracking Works

When a visitor loads a CARL page, a lightweight JavaScript beacon fires in the background and sends pageview data to a tracking endpoint on your server. The beacon captures the page URL, page title, referrer, and any UTM parameters present in the URL. A second beacon fires when the visitor leaves the page to record time on page. Both happen silently without affecting page load performance.

Bots are filtered automatically. CARL parses the visitor's user agent on every request and discards any hits identified as crawlers, spiders, or monitoring bots. Your view counts reflect real human visitors, not Google's crawl activity inflating your numbers.

What Gets Recorded

Each pageview record includes the URL, page title, referrer URL, referrer domain, and referrer type (organic search, direct, social, referral, or email). UTM parameters are captured and stored individually when present, so campaign traffic is clearly broken out. Device type, browser, operating system, and approximate geographic location are recorded for each visit.

Sessions are tracked using a short-lived cookie with a 30-minute inactivity window. A separate visitor cookie with a 30-day window identifies returning visitors. IP addresses are hashed before storage and never saved in plain text, so the system gives you meaningful audience data without retaining personally identifiable information.

The Analytics Dashboard

In the CARL admin panel, the Analytics dashboard shows an overview of pageviews, unique visitors, sessions, new visitor count, average time on page, and bounce rate for the selected period. Period filters cover the last 1, 7, 30, 90, or 365 days, with a custom date range option for anything in between. A trend indicator compares the current period against the previous equivalent period so you can see at a glance whether traffic is moving up or down.

Beneath the overview cards, the dashboard breaks down traffic by top pages, referrer sources, countries, devices, and browsers. Each breakdown lets you see where your traffic is coming from and which content is performing. The data updates in real time as new visits come in.

What It Doesn't Do

CARL's built-in analytics covers traffic patterns and content performance. It doesn't replace a full analytics platform if you need conversion funnels, goal tracking, or event-level reporting. For those use cases, adding GA4 through your header_scripts.txt include file runs both systems in parallel without any conflict. See How CARL integrates with Google Analytics for the setup steps.

How CARL Integrates With Google Analytics

CARL doesn't have a dedicated Google Analytics settings field. It doesn't need one. Because every page CARL generates includes your site-wide header scripts automatically, adding GA4 to your entire site takes about 30 seconds: paste your tracking snippet into one include file, and every page you've published picks it up.

How It Works

Every CARL page template includes a file called header_scripts.txt from your site_includes folder. Anything in that file gets injected into the section of every published page on your site. This is the same mechanism used for custom fonts, custom CSS links, and any other site-wide head code. Google Analytics is just one more thing that belongs there.

Adding Your GA4 Tag

In your Google Analytics account, go to Admin, then Data Streams, select your web stream, and copy the Google tag snippet. In the CARL admin panel, go to Includes and open header_scripts.txt. Paste the snippet in and save. That's the entire process.

Because CARL pages are static PHP files, the tag is already embedded when a visitor loads each page. There's no CMS runtime assembling the head section on request. The tag is written into every generated file at publish time, so it fires reliably on every page load without relying on any JavaScript framework or plugin being active.

Regenerating After Adding the Tag

Updating header_scripts.txt doesn't automatically update pages that are already published on disk. To push the new tag to all existing pages, run a bulk regenerate after saving the include file. New pages published after that point will automatically include the tag, since they're generated fresh from the current include files.

Verifying It's Working

After regenerating, open any published page and view its source. Search for your GA measurement ID (it looks like G-XXXXXXXXXX) and confirm it appears in the head section. In Google Analytics, the Realtime report should show activity within a minute of you visiting the page. If you don't see the tag in the source, check that header_scripts.txt was saved correctly and that the bulk regenerate completed without errors.

How to Change Your CARL Admin Password

CARL gives you two ways to update your admin password: through the Settings panel when you're logged in, and through the password recovery flow when you're not. Both methods update the same bcrypt-hashed password record in the database.

Changing Your Password While Logged In

In the CARL admin panel, go to Settings and find the password change section. Enter your new password, confirm it, and save. CARL hashes the new password using bcrypt and updates the admin account record immediately. Your current session stays active after the change, so you won't be logged out. The new password takes effect on the next login.

Resetting Your Password When Locked Out

If you can't log in, CARL's password recovery flow uses a recovery key instead of email. The recovery key is a value you set in Settings under General while you still have access. If you haven't set one yet, do it now before you need it.

To reset your password, go to admin/forgot-password.php on your site. The process runs in two steps. First, enter your recovery key. CARL verifies it against the stored value using a timing-safe comparison, so there's no way to probe for valid keys through response timing. If the key matches, you're moved to the second step. Enter your new password, confirm it, and submit. CARL updates the password and redirects you to the login page.

Password Requirements

Passwords must be at least 8 characters. There are no complexity requirements beyond that, but a longer passphrase is more secure than a short one with mixed characters. CARL stores passwords as bcrypt hashes. The plain-text password is never stored anywhere on the server.

If You've Lost Your Recovery Key

If you're locked out and have no recovery key set, you'll need to update the password directly in the database via phpMyAdmin. Generate a bcrypt hash of your new password using an online bcrypt tool or a quick PHP script, then update the password column in the users table with the hash. Log in with the new password, then immediately set a recovery key in Settings so you're not in this position again.

How CARL Handles Admin Authentication

CARL's admin panel is protected by a straightforward session-based login system. Username and password are verified against a single admin account stored in the database, and access is blocked at the PHP level on every admin page until a valid session exists.

The Login Process

When you submit your credentials at admin/login.php, CARL queries the database for a matching username and verifies the submitted password against the stored bcrypt hash using PHP's password_verify(). If verification passes, PHP regenerates the session ID before writing the authenticated session flag. This prevents session fixation attacks, where an attacker who obtained a pre-login session ID could try to use it after authentication.

On every successful login, CARL also silently refreshes your license token against the licensing server. If the license has been revoked (trial expired), the session is destroyed immediately and login is blocked. If the licensing server is unreachable, the grace period stored in the local auth file covers continued access so a temporary network issue doesn't lock you out of your own site.

Session Protection on Every Admin Page

Every admin page calls requireLogin() at the top of the file. If no valid authenticated session exists, the visitor is redirected to the login page immediately, before any admin content is rendered or any admin action is executed. There is no admin page that can be accessed without a valid session, and there is no way to bypass this check by manipulating the URL.

CSRF Protection

Every form in the CARL admin includes a CSRF token, a 64-character random hex string generated by PHP's random_bytes() and stored in the session. When a form is submitted, CARL verifies the submitted token against the session token using hash_equals(), which prevents timing attacks. Any POST request that arrives without a valid matching token is rejected with a 403 before any action is taken. AJAX requests can pass the token via the X-CSRF-Token header instead of a form field.

The Single Admin Account

CARL operates with one admin account. There's no user roles system, no multi-admin setup, and no permission levels to manage. The admin account username and password are set during installation and can be changed at any time from inside the admin panel. For the password change process, see How to change your CARL admin password.

No Public Login Page Exposure

Unlike WordPress, CARL has no well-known login URL that automated scanners can target. The admin directory lives at /admin/ on your server, which you can rename or restrict via .htaccess if you want an additional layer of obscurity. The login page has no username enumeration vulnerability: the same error message is returned whether the username doesn't exist or the password is wrong, so there's no way to confirm valid usernames through trial submissions.

What CARL's Database Actually Contains

If you've used WordPress, you're used to a CMS where the database is involved in everything. Every page load, every menu render, every widget and all of it hits the database in real time. CARL's database plays a completely different role. It's an admin tool, not a delivery mechanism. Understanding that distinction changes how you think about the whole system.

The Database Is for the Admin Panel Only

CARL's database is queried in one context: when you're logged into the admin panel. When you create a page, edit a page, change a setting, or manage a product, that data lives in the database. The admin panel reads from it and writes to it constantly.

When a visitor lands on one of your published pages, the database is not involved at all. The page was already built and written to disk when you published it. The visitor gets a pre-built file. No database connection, no query, no result set to render. The database sits completely idle during every live page request.

What's Actually Stored in the Database

CARL's database contains your page records (titles, slugs, content, meta fields, template assignments, status), your site settings, your module data (subscribers, members, products, purchases, links, popups, CTAs), and your admin user account. It's the working data that powers the admin panel.

None of that is exposed to the public. The database credentials live in admin/config.php, which sits inside the admin directory. A visitor browsing your site has no path to the database and no reason to look for one. The published pages contain no database calls.

MariaDB 11.4 on Standard Shared Hosting

CARL runs on MariaDB 11.4, the default database engine for most modern cPanel shared hosting accounts. You don't need a managed database service, a separate database server, or any special configuration. If your host provides cPanel with MySQL or MariaDB support, the database side of CARL is already covered.

The database is created during installation through the setup wizard, and all tables are managed by CARL's migration system. You never need to write SQL by hand or manage the schema manually. When a new version of CARL introduces new tables or columns, the migration runner handles the update automatically.

The Tables and What They Do

CARL's database schema is straightforward. The pages table holds your content and page metadata. The settings table holds every key-value pair from the Settings panel. The users table holds admin accounts. Module tables handle their own data: subscribers for email signups, members and member_sessions for the members' area, downloads_products and download_tokens and download_purchases for the Downloads module, links and link_groups for the affiliate tracker, popups and ctas for the content tools.

Every table has a single, clear job. There's no tangled dependency chain, no options table storing serialized PHP objects, no post meta sprawl. If you open the database in phpMyAdmin, you can read exactly what's in it without needing a decoder ring.

What Happens If the Database Goes Down

This is where the architecture pays off in a way that surprises most people coming from WordPress. If your database becomes unavailable for any reason (a hosting issue, a maintenance window, anything) your published pages keep working. Visitors keep reading your content. Google keeps crawling your site.

The only thing that stops working is the admin panel, because that's the only part of CARL that actually needs the database. The public-facing site is completely unaffected. That's a resilience level that a database-driven CMS simply cannot match, regardless of how much caching you throw at it.

Backups Are Simple

Because the database contains only admin and module data, not the live site itself, backing it up is a contained, straightforward task. CARL's built-in backup system handles this for you, but a manual export via phpMyAdmin is also possible. The published pages are already on disk in public_html and can be backed up independently via cPanel's file backup tools.

You end up with two clean backup targets: the database for your admin data and the file system for your published pages. No overlap, no confusion about what's in which backup, and no single point of failure that takes everything down at once.

How CARL's Scheduler Works

CARL's scheduler lets you set any page to go live at a specific date and time. Set the schedule, save the page, and CARL handles the rest. The page file is generated and written to disk automatically when the scheduled time arrives, with no manual action required on your part.

How Scheduling Is Triggered

CARL checks for due scheduled pages on every admin panel page load. When you open any page in the admin, CARL silently queries the database for pages whose scheduled time is at or before the current UTC time and publishes any it finds. This means scheduling works reliably on any shared hosting account without requiring a cron job, though a cron job can be added for more precise timing on high-volume sites.

For installations where consistent timing matters regardless of admin activity, CARL includes a dedicated cron endpoint at admin/modules/scheduler/run.php. This can be called via cPanel's Cron Jobs tool on a schedule you define, or triggered via HTTP using a scheduler key set in Settings. Either method works. The admin-trigger approach is sufficient for most sites.

Timezone Handling

CARL converts the date and time you enter from your configured admin timezone to UTC for storage. This means the page publishes at the correct moment regardless of where your server is located. Your admin timezone is set in Settings under General. For a walkthrough of setting a schedule on a specific page, see How to schedule a page for future publishing.

What Happens at Publish Time

When the scheduler finds a page that's due, it runs the same generation process as a manual publish. CARL builds the complete PHP file from the page record, writes it to disk at the correct path, and updates the page status to published. The scheduled time field is cleared from the database record. After each successful publish, CARL pings Google with your sitemap URL so the new page is picked up for indexing as quickly as possible.

If a page fails to generate, the error is logged and the page remains in scheduled status rather than being silently dropped. On the next scheduler run, CARL will attempt it again. Any generation errors are written to your server's PHP error log for diagnosis.

Preventing Overlapping Runs

CARL uses a database lock to prevent two scheduler runs from executing simultaneously. If a cron job and an admin-triggered check happen to fire at the same moment, the second run detects the lock and exits immediately. The lock is released as soon as the first run completes, so there's no risk of it blocking future runs if the process finishes normally.

How to Restore a CARL Backup

Restoring a CARL backup overwrites your current site files and database with the contents of the selected backup file. The entire process runs from inside the admin panel. You don't need shell access, FTP, or phpMyAdmin to complete a restore.

Before You Restore

A restore is irreversible. Whatever is on your server right now, including any pages published, settings changed, or purchases recorded since the backup was taken, will be replaced. If there's any chance you need that data, create a fresh backup first before triggering the restore.

The Backup panel lets you create a new backup and restore an older one in the same session.

How to Trigger a Restore

In the CARL admin panel, go to Backup. The Backup History panel lists every available backup with its filename, size, and creation timestamp. Find the backup you want to restore and click the Restore button next to it. A confirmation modal appears showing the exact filename and creation date, along with a warning that the action cannot be undone. Click Restore Now to proceed.

The restore button disables itself once clicked and shows a progress state. Do not close the tab while the restore is running. On a large site with many files, the process may take a minute or two to complete.

What Happens During a Restore

CARL opens the backup ZIP and extracts it to a temporary directory on the server. If the backup contains a database export, CARL imports it using a direct PDO connection, running each SQL statement in sequence with foreign key checks temporarily disabled.

If the backup contains secrets.php, it is restored to its correct location above public_html and its file permissions are set to 0600. If the backup contains site files, they are copied back into public_html, recreating the original directory structure.

Once the restore is complete, the temporary directory is deleted. The confirmation message on the Backup page tells you exactly which components were restored: database, site files, and secrets.php.

If any SQL statements produced warnings during the import, those are shown as well so you can assess whether anything needs attention.

After the Restore

Your site should be fully operational immediately after the restore completes. Published pages are static PHP files that were written back to disk as part of the file restore, so visitors see the restored content without any additional steps. The admin panel reconnects to the restored database automatically on the next page load.

If the backup was taken some time ago, run a Site Health check after restoring to confirm the state of your pages and catch any issues introduced by the rollback. Any pages published after the backup date will be gone, so check your page list and republish anything that's missing.

Restoring to a Different Server

CARL backups are self-contained. If you're migrating to a new host rather than recovering from an incident, download the backup ZIP from the Backup panel to your local machine, complete the fresh CARL installation on the new server, then use the Backup panel on the new install to restore from the downloaded file. The database credentials in secrets.php will need updating to match the new server's database settings after the restore.

How CARL's Backup System Works

CARL's backup system creates a single ZIP file containing your site files, your database, and your secrets.php configuration. Everything your site needs to run is in one file, stored in a location that no browser can reach.

Where Backups Are Stored

Backups go above your web root, in a folder called carl-backups sitting one level above public_html. On a standard cPanel account, that means the folder is at /home/yourusername/carl-backups/. A visitor browsing your site has no URL they could use to access it. Downloads are served exclusively through the admin panel, with login required.

This is a deliberate architectural decision. Storing backups inside public_html would make them publicly accessible by URL, which is a serious security risk on any site that handles member data, purchase records, or private configuration. CARL keeps them out of the web root by default, with no configuration required on your part.

What Gets Included

When you create a backup, you can choose to include site files, the database, or both. secrets.php is always included regardless of what you select, because the site cannot connect to the database without it. A backup that contains the database but not secrets.php would be unusable during a restore.

The site files option packages everything in public_html into the ZIP under a public_html/ path prefix, excluding the backup directory itself. The database option exports every table and all data using CARL's pure-PHP export function. There's no dependency on mysqldump, which means it works on every shared hosting account regardless of whether shell access is available.

The Backup File

Each backup is named carl-backup-YYYYMMDD-HHmmss.zip, with the timestamp embedded in the filename so you always know exactly when it was created. The backup screen shows the estimated size of your site files and database before you run the backup, alongside the available free disk space. If space is tight, a warning appears before you proceed.

Large sites may take a minute or two to package. CARL extends PHP's execution time limit for the duration of the backup and keeps the process running even if the browser tab goes idle. You don't need to keep the tab in focus, but you should leave it open until the confirmation message appears.

Managing Your Backup History

The Backup History panel lists every existing backup with its filename, size, and creation timestamp in UTC. From there you can download any backup directly to your computer, trigger a restore, or delete backups you no longer need. Backups flagged as over 30 days old are highlighted so you can decide whether to keep or remove them.

Deleting old backups regularly is good practice. Each full-site backup includes your entire public_html directory, so on a large site they accumulate disk usage quickly. Keep at least 2 recent backups on the server at any time and download a copy to your local machine or cloud storage for offsite redundancy.

Running a Backup

In the CARL admin panel, navigate to Backup. Select whether to include site files, the database, or both, then click Create Backup Now. The button disables itself during the process to prevent double submissions. When the backup completes, the new file appears immediately in the Backup History panel with its size confirmed. For how to use a backup to restore your site, see How to restore a CARL backup.

How to Set Up CARL's Site Search

CARL's site search is ready to use the moment you install it. The search bar widget is already included in the Bootstrap Blog sidebar template, so if you're using that template for your articles, search is already working on those pages. For any other template or page type, adding search takes about two minutes.

Search on the Bootstrap Blog Template

The Bootstrap Blog template loads search_bar.txt automatically as part of its sidebar. Every page using this template has a working search bar in the sidebar, with no additional setup. If you've published articles using the Bootstrap Blog template and visit one of those pages, the search bar is already there. Type a query, and it works.

Adding Search to a Specific Page

For pages using a different template, or for pages where you want to search in a non-sidebar position, add it through the PHP Snippet field. Open the page in the CARL editor and scroll to the PHP Snippet field. Click the Include Picker, find search_bar.txt in the list, and click Insert. CARL adds the include line to the snippet field. Click Save Draft, then Save and Generate File. The search bar is now on that page at the position where the snippet renders.

The PHP Snippet renders at the {{SNIPPET}} token position in your template. If you want the search appearing in a specific part of the layout, check where that token is placed in the template file and adjust accordingly.

Adding Search to a Custom Template

If you've built a custom template and want search available on every page using it, add the include directly to the template file rather than adding it to each page individually. Open the template file via Include Files in the admin, add the following line at the position where you want the search bar to appear:

Save the template and run bulk regeneration. Every page using that template will have the search bar on the next regeneration pass.

Verifying Search Is Working

After adding the search bar and regenerating the page, visit the live URL and enter a search query. Results should appear immediately. If the search bar renders but returns no results for queries you'd expect to find content for, confirm those pages are published and have been generated. CARL's search indexes published pages: draft pages and scheduled pages don't appear in search results until they're live.

Monitoring Search Queries

Once the search is live on your site, go to Tools, then Search in the CARL admin to review the queries visitors are entering. Check this dashboard periodically: repeated searches for topics you haven't covered are some of the most reliable content signals you'll find. Your visitors are telling you exactly what they want to read. For a full overview of what the search dashboard shows and how the search system works under the hood, see How CARL's Site Search works.

How to Use CARL's AI Schema Generator

The AI Schema Generator is one of CARL's most powerful features. Click one button, and Claude reads your page content, writes an optimized meta description, generates a complete Article JSON-LD schema with Thing entities, produces Open Graph tags, Twitter Card tags, a keywords tag, and a canonical URL tag, then delivers the entire block directly into the Head Injection field. One click covers everything that belongs in your page's,

Setting Up Your Claude API Key

The AI Schema Generator runs on Claude, Anthropic's AI. To use it, you need to add a Claude API key to CARL's settings. Go to console.anthropic.com, create a free Anthropic account if you don't have one, navigate to API Keys, and click Create Key. Name it something recognizable like "CARL" and copy the key. In CARL, go to Settings, click the AI Settings tab, paste the key into the Claude API Key field, and click Save All Settings.

The API key starts with sk-ant-. You're billed directly by Anthropic for usage, not through CARL. The cost is a fraction of a cent per page. Most users spend under $1 per month on API costs, even running active content sites.

Before You Click Generate Schema

The Generate Schema button works best when your page is as complete as possible before you run it. Write your full page content first. Set your OG Image using the OG/TW button in the Quick Image Insert panel: Claude includes the image URL in the Open Graph and Twitter Card tags it generates. Fill in your OG Description, a one to two-sentence summary of the page for social sharing. Add any SameAs URLs in the SameAs field, one per line: your social profiles, relevant Wikipedia pages, or other authority sources that relate to the page topic. The more context Claude has, the better the output.

Running Generate Schema

Once your content is written and the OG fields are filled in, click the Generate Schema button. CARL sends your full page content, title, OG image URL, and SameAs URLs to Claude. Claude generates the complete head block, and CARL appends it automatically to the Head Injection field.

A green success message confirms the transfer. The whole process takes a few seconds.

After the schema lands in Head Injection, the Override Auto-Schema checkbox ticks itself automatically. Leave it ticked.

This suppresses CARL's built-in schema generation, so there's no conflict between the AI-generated block and any default schema CARL would otherwise output. This is the correct state, and you don't need to change it.

After Generate Schema Runs

Click Save Draft immediately after the schema is generated. The Head Injection content is part of the page record and needs to be saved before you publish or navigate away. If you close the editor without saving, the generated schema is lost, and you'll need to run it again.

Once saved, click Save and Generate File to publish the page. The complete head block, including the meta description, schema, Open Graph tags, Twitter Cards, keywords, and canonical tag, gets baked into the published PHP file. Every visitor and every crawler gets the full structured data package on every page request, served from a static file with no runtime cost.

Schema Presets for Different Page Types

The default Generate Schema instructions produce the Article schema, which is correct for most content pages. For pages that need a different schema type, CARL's Schema Preset system lets you create named sets of instructions for different content types.

An FAQ page preset that generates FAQPage schema, a video page preset that generates VideoObject schema, a product review preset that generates Review schema: you create these in Settings under AI Settings, then select the relevant preset from the dropdown in the page editor before clicking Generate Schema.

For pages that need schema types the AI generator doesn't cover, write the JSON-LD manually and paste it into the Head Injection field. The Head Injection field accepts any valid HTML or script content and writes it verbatim into the published file's section.

How to Configure Organization Settings in CARL

The Organization tab in CARL's Settings panel powers your site's Organization JSON-LD schema. This is the structured data Google uses to understand your brand: who you are, what you do, where you're based, and how your online presence connects together. Fill it in completely during initial setup. It takes five minutes, and the SEO benefit compounds across every page on your site.

What Organization Schema Does

When Google crawls your site, it reads the Organization schema and uses it to build a knowledge graph entry for your brand. This is what drives the branded search results panel that appears when someone searches for your business by name, the logo that sometimes appears in search results, and the data connections that establish your site as an authoritative source rather than an anonymous collection of pages. It's also what Google uses to verify that the author of your content is a real, identifiable entity.

The Organization Fields

Organization Name is your business or brand name exactly as you want it to appear in search results. Alternate Name is a shorter version or common abbreviation if one exists: "C.A.R.L." alongside "Content Automation Ranking Launchpad", for example. Description is one to two sentences describing what your site or business does. Write it clearly and factually: this is data for Google, not a tagline.

The Email field is your public contact email address. Logo URL is the full URL to your logo image, for example https://yoursite.com/images/logo.png. Upload your logo to CARL's Image Manager first, copy the URL, and paste it here. Google uses this URL to display your logo in branded search results, so make sure the image is at a stable, permanent URL that won't change.

Founder Information

The Founder Name field is your name or the name of the business founder. The Founder LinkedIn URL links the Organization schema to a verified professional profile, which strengthens the entity connection Google can establish between your brand and a real person. If you have a LinkedIn profile, add it. If you don't, you can leave the field blank, but a linked profile adds credibility to the schema.

Address Fields

Fill in your business address: street, city, postcode, and country. The country field takes a two-letter ISO code: US for the United States, GB for the United Kingdom, AU for Australia, NL for the Netherlands, and so on. If you operate as a solo online business without a formal street address, use the city and country where you're based. Google doesn't require a full street address for every business type, but having city and country in place is better than leaving the fields empty.

Saving and Propagating

Click Save All Settings when all fields are filled in. The Organization schema is written into every page CARL generates from this point forward. For pages already published before you completed the Organization settings, run bulk regenerate to push the updated schema across your entire site in one pass. Every page that goes through a regeneration will carry the complete Organization data in its head section.

What Hosting Does CARL Require

CARL is built for standard cPanel shared hosting. You don't need a VPS, a dedicated server, a managed cloud platform, or any specialist infrastructure. If your host provides cPanel with PHP 8.1 or higher and a MySQL or MariaDB database, CARL will run on it. Most shared hosting accounts available today meet these requirements without any special configuration.

The Core Requirements

CARL requires PHP 8.1 or higher. The installer checks your PHP version automatically during the pre-flight stage and will tell you if your server falls short. Most cPanel hosts running modern infrastructure default to PHP 8.1 or 8.2, and many offer 8.3. If your host is still running PHP 7.x, it's time to either upgrade the PHP version in cPanel's MultiPHP Manager or switch hosts.

CARL also requires six PHP extensions to be enabled: curl, mbstring, pdo, pdo_mysql, json, and zip. These are standard extensions that come enabled by default on virtually every cPanel shared hosting account. The installer checks for all of them and flags any that are missing. If one is missing, contact your hosting provider and ask them to enable it.

Database Requirements

CARL stores all your content, settings, and module data in a MySQL or MariaDB database. Any cPanel host with MySQL Databases in the control panel supports this. Create the database and user in cPanel before running the installer; the setup wizard creates all tables automatically. You don't need a managed database service or a separate database server.

MariaDB 11.4 is what CARL is developed and tested against, but MySQL 5.7 and above work without issues. The specific database engine your host provides is generally not something you need to research: if your cPanel account has MySQL Databases, it's compatible.

Server and Directory Requirements

Your document root directory needs to be writable with standard 755 permissions. This is the default on cPanel shared hosting and shouldn't require any manual configuration. The installer checks this during the pre-flight stage. If the directory isn't writable, the installer will tell you before attempting anything.

During installation, your server needs to be able to make outbound HTTPS connections to the CARL licensing server to verify your license and download the CARL package. Most shared hosting accounts allow this by default. If the installer fails at the download stage, contact your host and ask them to allow outbound HTTPS connections to external servers.

What You Don't Need

CARL doesn't require root server access, SSH, a command line, or any server administration beyond what's available in cPanel. You don't need to configure PHP-FPM, adjust server memory limits, install server-side software, or touch anything outside File Manager, MySQL Databases, and the Cron Jobs section of cPanel. Everything CARL needs is available through the standard cPanel interface.

You also don't need a fast or expensive hosting plan. Because CARL pages are static PHP files written to disk at publish time, the server does almost no work on each page request. A basic shared hosting account that would struggle to serve a WordPress site at any meaningful traffic volume handles a CARL site without breaking a sweat.

Recommended Hosts

Any reputable cPanel shared hosting provider works. The things worth checking when choosing a host are: PHP 8.1 or higher available in MultiPHP Manager, MySQL Databases in the control panel, outbound HTTPS allowed, and reasonably fast SSD storage. Beyond those basics, CARL isn't demanding. The host that serves your files quickly is the right host, and for static PHP files, the bar is not high.

How to Install CARL on cPanel Shared Hosting

Installing CARL takes three stages: create a database in cPanel, run the CARL installer, and complete the setup wizard. The installer handles almost everything automatically. Your job is to follow the steps in order and have your database credentials ready before you start.

What You Need Before You Start

You need a cPanel shared hosting account with PHP 8.1 or higher, access to MySQL Databases in cPanel, and your CARL purchase confirmation email. The confirmation email contains the installer file download and the email address and password you'll use to verify your license. Have those credentials ready before you begin.

Step 1: Create Your Database

In cPanel, go to MySQL Databases. Create a new database and give it a recognizable name, something like yoursite_carl. Then create a new database user with a strong password. Add that user to the database and grant all privileges. Write down the database name, username, and password immediately and store them somewhere safe. The setup wizard needs all three.

Step 2: Upload and Run the Installer

Download the installer file from your CARL purchase confirmation email. In cPanel File Manager, navigate to your domain's public_html/ folder and upload the installer file there. Then open a new browser tab and navigate to the installer URL shown in your purchase confirmation.

The installer opens with a pre-flight check. It verifies your server meets the requirements: PHP 8.1 or higher, the required PHP extensions (curl, mbstring, pdo, pdo_mysql, json, zip), and a writable directory. All green means you're good to proceed. If anything fails, contact your hosting provider and ask them to enable the missing requirement.

Enter the email address and password from your CARL purchase confirmation, then click Verify License and Install CARL. The installer contacts the CARL licensing server, verifies your license, downloads the full CARL package, runs a SHA-256 integrity check, and extracts everything into your document root. This usually takes 30 to 90 seconds. Don't click anything or close the browser while it runs.

When it finishes, a green success message appears. The installer self-deletes at this point as a security measure. Click Continue to CARL Setup.

Step 3: Complete the Setup Wizard

On the setup page, click Fresh Install. Fill in your database connection details: DB_HOST (leave as localhost unless your host specifies otherwise,) DB_NAME, DB_USER, and DB_PASS using exactly what you set up in cPanel.

The SITE_ROOT field is the most common source of installation errors. It must be the full absolute server path to your public_html folder, starting with /home/, with no trailing slash. Look at the address bar in cPanel File Manager while you're in your public_html folder: that path is your SITE_ROOT. It looks like /home/yourusername/public_html. Not a URL, not a relative path.

Choose your admin username and a strong password, then click Run Fresh Install. CARL creates all database tables and confirms success. Click Go to Login.

Your First Login

Go to https://yoursite.com/admin/ and log in with the credentials you just set. Bookmark this URL immediately. Once you're in, go to Settings and complete your initial configuration before publishing anything. For a full walkthrough of what to set up on first login, see How to configure CARL's general settings.

If Something Goes Wrong

License verification failures are almost always due to incorrect credentials: use the exact email and password from the purchase confirmation, not your hosting login. Database errors in the setup wizard are almost always a credentials mismatch or missing privileges: double-check the database name, username, and password against what you created in cPanel, and confirm the user has all privileges on that database. SITE_ROOT errors mean the path format is wrong: copy it directly from the cPanel File Manager address bar.

How to Add a Favicon in CARL

A favicon is the small icon that appears in browser tabs, bookmarks, and search results next to your page title. It's a minor detail that makes a site look finished and professional. Adding one in CARL takes about two minutes: you prepare the icon file, upload it to your server, and add the reference tag to your template. Every page CARL generates from that template will automatically include it.

Preparing Your Favicon File

The most widely supported favicon format is a 32x32 pixel PNG file named favicon.png, or an ICO file named favicon.ico. Modern browsers also support SVG favicons, which scale cleanly at any size. For maximum compatibility across browsers and devices, a 32x32 PNG is the simplest choice. If you also want a larger icon for iOS home screens and Android bookmarks, prepare a second file at 180x180 pixels for the Apple Touch Icon.

Keep the design simple. A favicon is tiny. A detailed logo that looks sharp at full size becomes an unreadable smudge at 32 pixels. Use a simplified version of your logo, a single letter, or a distinctive symbol that reads clearly at small sizes.

Uploading the File

Upload your favicon file to the root of your domain's public_html/ directory. Placing it at the root means browsers can find it automatically even without an explicit link tag, but adding the link tag in your template is still best practice. Upload via cPanel's File Manager or any FTP client. The file should be accessible at yourdomain.com/favicon.png once uploaded.

Adding the Tag to Your Template

Open your site's template file and add the favicon link tag inside the section. For a PNG favicon, the tag looks like this:

If you're also adding an Apple Touch Icon for mobile home screens, add a second tag:

Save the template. The tags are now part of the template structure that CARL uses when generating pages. Every page using that template will include the favicon reference in its from the next regenerate onward.

Pushing the Change to Published Pages

Adding the tag to the template doesn't update pages that are already on disk. Those files were generated before the template change and don't yet contain the favicon tag. Run bulk regenerate to push the updated template across every published page in one pass. After the regeneration completes, every page on your site will have the favicon tag in its head section.

Checking It Works

Open any published page in a browser and look at the tab. Your favicon should appear next to the page title. If it doesn't show immediately, do a hard refresh: browsers cache favicons aggressively and sometimes hold onto an old version or a blank state for longer than you'd expect. In Chrome, you can force a favicon refresh by opening DevTools, going to the Application tab, finding the favicon in the cache, and clearing it. A full browser cache clear also works.

Once the favicon is showing correctly in one browser, check it in another to confirm it's not a caching issue. If it's missing in all browsers after a hard refresh, double-check that the file is at the correct path on your server and that the link tag in the template points to the right filename and extension.

How to Fix a Canonical Mismatch in CARL

A canonical mismatch means the canonical tag in your published PHP file points to a different URL than the page actually lives at. It usually happens when a page's slug or directory is changed after the page has already been published, leaving the old URL declared as authoritative in the file while the page is now accessible at a new one. CARL's Site Health checker surfaces these automatically. The fix is straightforward.

Why Canonical Mismatches Happen

The most common cause is a slug change. You publish a page, later decide the slug should be different, update it in the editor, and regenerate. The new file is at the new URL, but if the Head Injection field still contains the canonical tag from the previous Generate Schema run, that tag still points to the old URL. The file is in the right place, but it's declaring the wrong address as its canonical.

The same thing happens with directory changes. Move a page from blog/ to articles/, regenerate, and the canonical in the Head Injection field still references the old path unless you update it before regenerating.

Finding the Mismatch

Run a Site Health audit from the CARL admin panel. Any page with a canonical mismatch appears in the results with the issue flagged. The audit compares the canonical URL specified in the Head Injection field with the page's actual URL, determined by its current slug and directory settings. If they don't match, the page is flagged.

You can also spot a mismatch manually by viewing the source of a published page and checking the canonical tag in the section. If the URL in the href attribute doesn't match the page's actual URL, you have a mismatch.

Fixing the Mismatch

Open the flagged page in the CARL editor. Go to the Head Injection field and find the canonical tag. It looks like this:

Update the URL to match the page's current slug and directory:

Save the page and click Generate. The updated canonical tag is written into the new PHP file at the correct URL. The mismatch is resolved.

Using Generate Schema to Fix It Cleanly

If you'd rather not edit the Head Injection field manually, the cleanest approach is to clear the Head Injection field entirely and run Generate Schema again. Claude will produce a fresh head block with the canonical tag pointing to the current URL, derived from the page's current slug and directory settings. Check the generated output to confirm the canonical is correct before saving and regenerating.

This approach also refreshes the rest of the head block: the meta description, schema, Open Graph tags, and Twitter Card tags all get rewritten based on the current content. If the page has been significantly updated since the last Generate Schema run, this is the better option.

After the Fix

Once the page is regenerated with the correct canonical, run Site Health again to confirm the mismatch is cleared. If you changed the slug or directory as part of the same update, remember that the old file is still on disk at the old path. Delete it via cPanel's File Manager to avoid having a second copy of the content at an unintended URL. A stale file at an old URL with a canonical pointing to the new URL is better than a stale file with no canonical at all, but removing it entirely is the cleanest outcome.

How CARL's Site Health Checker Works

Site Health is CARL's built-in SEO audit tool. It scans every published page on your site, checks each one against a set of SEO and content quality criteria, and surfaces anything that needs attention.

Missing meta descriptions, canonical mismatches, pages without schema, titles that are too long or too short: Site Health finds them and lists them so you can fix them without having to open every page individually.

What Site Health Checks

Site Health runs through a checklist on every published page. It checks for the presence and length of the page title, the meta description, and the H1. It verifies that a canonical tag is present and that the canonical URL matches the page's actual URL. It checks whether the Head Injection field contains content and flags pages where Generate Schema hasn't been run. It also checks for pages that have been edited in the database but not regenerated, meaning the disk file is out of sync with the current record.

The checks cover the most common SEO issues that accumulate on a site over time: pages published before the Generate Schema workflow was established, pages where the slug was changed without updating the canonical URL, and pages where the meta description was left blank because the content felt self-explanatory at the time. Site Health finds all of them in one pass.

How to Run a Site Health Check

In the CARL admin panel, navigate to Site Health. Click the audit button, and CARL works through every published page record, running each check in sequence. The results appear as a list of pages with issues, grouped by issue type. A page can appear in multiple groups if it has more than one problem. Pages that pass all checks don't appear in the results, so the list shows only what needs attention.

On a large site, the audit takes a few seconds longer than on a small one, but it runs entirely on the server. You don't need to keep the tab active while it processes. The results stay available in the admin until you run the next audit.

Acting on the Results

Each flagged page in the results links directly to that page's editor. Click through, fix the issue, run Generate Schema if the page needs a head block, and regenerate. For pages flagged as out of sync between the database and the file on disk, the fix is a regeneration with no other changes needed. For pages with missing or oversized titles and descriptions, you'll need to edit the content or the Head Injection field before regenerating.

For issues that affect a large number of pages at once, such as a batch of pages published without running Generate Schema, the most efficient approach is to open each one, run Generate Schema, save, then use bulk regenerate to push all the updates to disk in a single pass rather than regenerating each page individually.

Running Site Health Regularly

Site Health is most useful as a regular check rather than a one-time fix. Run it after any batch of new pages to confirm everything was published correctly. Run it after a template change and bulk regenerate to verify no pages were missed. Run it periodically on a mature site to catch any drift that's accumulated since the last audit.

The issues Site Health finds aren't catastrophic individually, but they compound. A site where half the pages are missing schema, a quarter have canonical mismatches, and a handful have titles Google is rewriting because they're too long is a site leaving ranking signals on the table. Site Health keeps the baseline clean so those signals go where they should.

How CARL Handles RSS Feeds

An RSS feed is a machine-readable file that lists your most recently published content. Feed readers, news aggregators, podcast apps, and other services subscribe to it and pull updates automatically when new content appears. For SEO purposes, RSS feeds also give Google a fast signal that new content exists on your site. CARL generates and maintains your RSS feed automatically, no plugin required.

How CARL Builds the Feed

CARL generates your RSS feed from your published page records and serves it at the standard location: yourdomain.com/rss.xml. The feed updates each time you publish or regenerate pages, pulling the most recently published content into the file. You don't trigger the feed update manually. It happens as part of the normal publishing process.

The feed follows the RSS 2.0 specification, which is the format feed readers and aggregators expect. Each entry includes the page title, URL, publication date, and description. The description field pulls from the page's meta description, which is another reason the Generate Schema step matters: a well-written meta description serves double duty as the feed excerpt that subscribers and aggregators see.

RSS and Google Indexing

Google crawls RSS feeds as part of its discovery process. A new page that appears in your RSS feed can be picked up and queued for indexing faster than a page Google finds only by following internal links. Combined with a submitted XML sitemap, the RSS feed gives Google two separate signals that new content has been published. On an actively updated site, that combination keeps crawl frequency high.

CARL pages already have a structural advantage here. The static PHP files load fast, the structured data is in place, and there's nothing for Google's crawler to trip over during execution. The RSS feed simply ensures new content gets noticed sooner rather than waiting for Google to find it through internal links alone.

Feed Readers and Content Syndication

Readers who subscribe to your RSS feed receive updates whenever you publish, without you having to notify them directly. For a content-heavy site like a wiki or a blog, this is a low-effort way to build a returning audience. Someone who subscribes via RSS is actively choosing to follow your output, which makes them a more engaged reader than someone who finds a page through search once and never returns.

Some content aggregators and curation platforms also automatically pull from RSS feeds. If your content is relevant to a niche community that uses feed aggregators, being present in those feeds extends your reach without any additional distribution effort on your part.

Submitting Your Feed

Google Search Console doesn't require a separate RSS feed submission, unlike sitemaps. Google discovers and crawls RSS feeds on its own once it's familiar with your domain. If you want to make the feed easy to find for human subscribers, add a visible RSS link in your site's navigation or footer. The URL is always yourdomain.com/rss.xml. So it's consistent across every CARL install.

How CARL Generates XML Sitemaps

An XML sitemap is a file that lists every page on your site you want search engines to crawl and index. It's not a ranking factor, but it's a reliable way to ensure Google knows your pages exist, particularly for newer sites that don't yet have the inbound links that would naturally lead crawlers to every page.

CARL generates your sitemap automatically, keeps it up to date as you publish, and serves it as a static file without any plugins.

How CARL Builds the Sitemap

Every time you generate a page in CARL, the sitemap is updated to include it. CARL pulls the published page records from the database, builds a valid XML sitemap file, and writes it to your server. The sitemap is available at the standard location crawlers expect: yourdomain.com/sitemap.xml. You don't need to trigger a separate sitemap generation step or install an SEO plugin to get a working sitemap.

Pages with a status of draft or scheduled are not included in the sitemap. Only published pages make it into the file. If you unpublish a page or delete its generated file, the next sitemap update removes it from the list.

What the Sitemap Contains

CARL's sitemap follows the standard XML sitemap protocol. Each entry includes the page's full URL of the published PHP file, and the date reflecting when the page was last generated. The value is useful to Google: it signals that a page has been updated recently, which can prompt a recrawl sooner than a page that shows an old modification date.

Priority and changefreq values are optional in the sitemap protocol and have minimal influence on how Google actually crawls your site. CARL keeps the sitemap clean and doesn't pad it with values that Google largely ignores.

Submitting Your Sitemap to Google

Once your site is live, submit the sitemap URL to Google Search Console. Go to the Sitemaps section, enter sitemap.xml, and submit. Google will crawl it, report how many URLs it found, and begin indexing your pages. On a new site with no existing backlinks, this is the fastest way to get your pages into Google's index.

CARL pages index quickly regardless: the static PHP files load fast, the structured data is in place from the Generate Schema step, and there's no dynamic execution for Google's crawler to trip over. Submitting the sitemap simply ensures Google has a complete list of pages to work from rather than discovering them only through internal links.

The Sitemap and Bulk Regenerate

When you run bulk regenerate, the sitemap is rebuilt as part of the process. Every published page gets a fresh date reflecting the regeneration time. If you've made sitewide template changes and bulk-regenerated to push them across all pages, the sitemap update occurs in the same pass. There's no separate sitemap refresh step required.

Multiple Sites, Multiple Sitemaps

Each CARL install generates its own sitemap for its own domain. If you're running multiple domains on the same server, each install maintains a separate sitemap.xml at its own domain root. There's no crossover between installs and no configuration required to keep them separate. The sitemap for each site reflects only the published pages in that site's database, as described in "How CARL handles multiple domains on one server."

How CARL Handles Open Graph Tags

When someone shares one of your pages on Facebook, LinkedIn, or any other platform that reads Open Graph data, those platforms don't use your page title and meta description. They use the Open Graph tags: a separate set of meta tags in the page's that specify exactly what title, description, and image should appear in the shared preview. CARL handles these via the AI Schema Generator, with manual fields available when you need direct control.

What the Generate Schema Button Produces

When you click Generate Schema, Claude writes a complete set of Open Graph tags as part of the head block it delivers to the Head Injection field. The block includes og:type, og:title, og:description, og:url, og:image, and og:site_name.

These are written based on your page content and title, formatted correctly, and appended to Head Injection automatically alongside the schema, Twitter Card tags, meta description, and canonical. One click covers the full set.

The og:image tag uses the featured image you've assigned to the page in CARL. If a featured image is present, Claude includes its URL in the Open Graph block. Social platforms pull that image when the page is shared, giving your links a visual presence in feeds rather than appearing as text-only previews.

Twitter Card Tags

Generate Schema also produces Twitter Card meta tags in the same pass. The Twitter Card block includes twitter:card set to summary_large_image, along with twitter:title, twitter:description, and twitter:image. These control how your pages appear when shared on X, using the large image format that gives shared links significantly more visual weight in the timeline than a plain text link.

Open Graph and Twitter Cards serve the same purpose on different platforms. Generate Schema handles both in one operation, so there's nothing to configure separately for social sharing once the head block is in place.

The Manual Override Fields

CARL's page editor includes manual fields for the Open Graph title, description, and image. These exist for cases where the AI-generated Open Graph copy isn't quite right for a specific page: a page where the social sharing framing should differ noticeably from the search framing, or a page where you want to test specific social copy. If you fill in the manual fields, those values override the generated ones when you regenerate.

For most pages, the manual fields stay empty. Generate Schema writes better-optimized Open Graph copy faster than filling in fields by hand, and the result is consistent with the rest of the head block it produces.

Open Graph Images

The image that appears in social shares is one of the highest-impact elements of a shared link. A relevant, well-composed image stops the scroll. A missing or generic image doesn't. CARL's Open Graph image tag points to the page's featured image, so the image you choose in the page editor is the one that appears when the page is shared.

Social platforms cache Open Graph data aggressively. If you update the featured image on a published page and regenerate, the new image tag will be in the file immediately, but platforms that have already cached the old data may continue showing the old image for a period. Facebook's Sharing Debugger and LinkedIn's Post Inspector both let you force a cache refresh if you need the update to appear immediately.

Baked In at Generation Time

Like every other element of CARL's SEO output, the Open Graph tags are written into the static PHP file at generation time. There's no dynamic tag assembly happening on each page request. When a social platform crawls your page to generate a preview, it reads the tags directly from the file. The tags are always present, always correctly formed, and served instantly from the static file without any PHP execution required to produce them.

How CARL Generates JSON-LD Schema Markup

JSON-LD schema markup is structured data that tells search engines exactly what your page is about: who wrote it, when it was published, what entities it covers, how it relates to other things on the web.

Google uses it to build knowledge graph connections, power rich results, and understand content with more precision than it can from HTML alone. CARL generates it automatically through its AI Schema Generator, powered by Claude.

How the AI Schema Generator Works

Once you've written your page content, click the Generate Schema button in the page editor. CARL sends your content to Claude along with a set of instructions that specify exactly what to produce: an Article schema, Thing entities for knowledge graph enhancement, Twitter Card tags, Open Graph tags, a canonical tag, an optimized meta description, and a keywords tag, all delivered in a consistent order.

Claude reads the content, generates the complete head block, and CARL appends the result directly to the Head Injection field. You don't paste anything manually. The transfer is automatic.

When you click Generate to publish the page, the entire head block gets baked into the section of the generated PHP file. From that point, every visitor and every crawler gets the full structured data package on every page request, served from a static file with no runtime overhead.

What the Schema Block Contains

The Article schema Claude produces includes the page headline, description, author details and a URL pointing to /about.php, publisher information, datePublished and dateModified formatted with the correct timezone, isAccessibleForFree: true, and a mainEntityOfPage reference. It also includes Thing entities under the about property, each describing a key concept the page covers.

These Thing entities enable CARL pages to build knowledge graph connections beyond the basic Article type.

Where relevant, Claude adds sameAs links connecting entities to their corresponding entries on Wikipedia, Wikidata, or other authoritative sources. This considerably strengthens the knowledge graph signal.

A page about a named psychological effect, a historical business story, or a well-documented technical concept benefits significantly from sameAs links that anchor those entities to established knowledge graph nodes.

Why JSON-LD Over Other Schema Formats

Google supports three schema formats: JSON-LD, Microdata, and RDFa. JSON-LD is the one Google recommends, and for good reason. It sits in the as a self-contained script block, completely separate from the page's HTML markup.

You can read, edit, and validate it without touching the content. Microdata and RDFa require you to weave schema attributes into the HTML itself, which makes the markup harder to read and schema changes harder to make cleanly. CARL uses JSON-LD exclusively.

Manual Schema for Specific Cases

The AI Schema Generator handles the Article schema for standard content pages. For pages that need a different schema type, such as a LocalBusiness schema for a location page, an FAQ schema for a questions page, or a Product schema for a sales page, you write the JSON-LD manually and paste it into the Head Injection field alongside or instead of the AI-generated block. The Head Injection field accepts any valid HTML or script content and writes it verbatim into the page's .

This is the only case where manual schema entry makes sense: when the page type genuinely calls for a schema type that the Article generator doesn't cover. For everything else, Generate Schema produces better-structured, more consistent markup faster than writing it by hand.

Validating Your Schema

After generating a page, you can validate its schema using Google's Rich Results Test at search.google.com/test/rich-results. Paste the page URL, run the test, and Google shows you exactly what structured data it found and whether it's valid. CARL's Site Health checker also flags pages with missing head injection content, catching pages published before Generate Schema was run or pages where the Head Injection field was accidentally cleared before regeneration.

How to Set Up PayPal in CARL

CARL's Downloads module uses PayPal to process payments. Setting it up requires a PayPal Business account, API credentials from the PayPal developer dashboard, and a few minutes in CARL's settings panel. Once it's connected, the entire purchase-to-delivery flow runs automatically without any third-party storefront involved.

What You Need Before You Start

You need a PayPal Business account. A personal PayPal account won't give you access to the API credentials CARL requires. If you don't have a Business account yet, upgrading from a personal account is straightforward inside PayPal's account settings and doesn't require a new email address or a new account.

You also need access to the PayPal Developer Dashboard at developer.paypal.com. This is where you create the app that generates your API credentials and where you register your webhook URL. Both steps happen here before you touch anything in CARL.

Creating Your PayPal App

In the PayPal Developer Dashboard, navigate to My Apps and Credentials. Create a new app under your Business account. Give it a name that identifies it as your CARL install, something like your domain name, so it's easy to find later. Once the app is created, PayPal provides a Client ID and a Secret Key.

These are the credentials you'll paste into CARL's settings panel.

PayPal provides both Sandbox and Live credentials. Sandbox credentials are for testing: payments go through a simulated environment, and no real money moves. Live credentials connect to real PayPal accounts and process real payments. Start with Sandbox to verify the full purchase flow works correctly, then switch to Live credentials when you're ready to accept real payments.

Entering Your Credentials in CARL

In CARL's admin panel, go to Settings and find the PayPal configuration section. Enter your Client ID and Secret Key from the PayPal Developer Dashboard. Select whether you're running in Sandbox or Live mode to match the credentials you've entered. Save the settings.

CARL stores these credentials in the database and uses them to verify incoming webhook notifications against PayPal's API. Keep them private. They're not exposed in any generated page file, but you should treat them with the same care as any other API key.

Registering the Webhook URL

Back in the PayPal Developer Dashboard, find the Webhooks section for your app. Add a new webhook and enter the endpoint URL from CARL's settings panel. This is the URL PayPal will post payment notifications to when a purchase is completed.

Select the payment completion event types you want PayPal to notify you about. For CARL's Downloads module, you need, at minimum, the completed payment event so CARL knows when a purchase has been confirmed. Save the webhook in PayPal's dashboard. From this point, completed payments will automatically trigger a notification to your CARL install.

Testing the Connection

With Sandbox credentials active, use PayPal's test buyer accounts to complete a test purchase on one of your product pages. Walk through the full flow: click the buy button, complete the PayPal checkout, confirm the purchase, check that the download email arrives, verify the download link works.

If every step completes correctly, the integration is working.

Once you've confirmed the Sandbox flow works end-to-end, switch CARL's settings to Live mode, update to your Live credentials, and update the webhook URL in the PayPal Developer Dashboard to point to your live endpoint. Then you're ready to take real payments. For a full picture of what happens after a payment is confirmed, see How the PayPal webhook works in CARL.

How the PayPal Webhook Works in CARL

When a buyer completes a purchase on PayPal, CARL needs to be notified immediately so it can generate a download token and send the buyer their download link. That notification comes through a PayPal webhook: an automated HTTP request that PayPal sends to your server the moment a payment is confirmed. Understanding how that process works helps you set it up correctly and troubleshoot it if something goes wrong.

What a Webhook Is

A webhook is a server-to-server notification. Instead of your site polling PayPal repeatedly to check whether a payment has come through, PayPal takes the initiative and posts a notification directly to a URL you specify. The moment a payment is confirmed on PayPal's end, their system sends a POST request to your webhook URL with the transaction details. Your server receives it, processes it, and acts on it.

The entire exchange takes seconds and requires no action from the buyer. They complete the payment, PayPal fires the webhook, CARL processes it, and the buyer receives their download email before they've had time to wonder what happens next.

What CARL Does When the Webhook Fires

When PayPal's webhook hits CARL's endpoint, CARL verifies the notification's authenticity by checking it against PayPal's verification API. A notification that fails verification is discarded. This prevents anyone from spoofing a payment confirmation to trigger a download without actually paying.

Once the notification is verified, CARL checks the payment details against the product record, confirms the purchase in the database, generates a unique download token, and sends the buyer an email with their download link. All of that happens automatically on the server side, with no manual step required from you.

The Webhook URL

Your CARL install has a dedicated webhook endpoint that PayPal posts to. You register this URL in your PayPal developer account when you set up PayPal in CARL. The URL follows a consistent pattern based on your domain and your CARL install location. CARL's settings panel shows you the exact URL to use.

The webhook URL needs to be publicly accessible. PayPal's servers are posting to it from outside your network, so it can't be behind a login, a firewall rule that blocks external requests, or a development environment that isn't reachable from the internet. A live cPanel hosting account on a public domain works without any additional configuration.

What Happens If the Webhook Fails

If PayPal's webhook notification doesn't reach your server, or if CARL returns an error response, PayPal will retry the notification several times over a period of hours before giving up. Most transient failures, brief server downtime, and temporary network issues resolve themselves before PayPal exhausts its retries.

If a buyer completes a payment but doesn't receive their download email, the first place to check is the webhook log in your PayPal developer dashboard. It shows every notification PayPal attempted to send, the response your server returned, and whether the delivery succeeded. Cross-reference that with the purchase records in CARL's admin to identify exactly where the process stopped.

Keeping the Webhook Secure

CARL verifies every incoming webhook notification against PayPal's API before acting on it. That verification step is non-optional and happens before any purchase record is created or any token is issued. Beyond that, your webhook URL should be treated like any other sensitive endpoint: don't share it publicly, keep your PayPal API credentials securely stored in CARL's settings, and ensure your admin directory is protected as described in How CARL handles admin authentication.

How CARL's Download Tokens Work

Every purchase made through CARL's Downloads module generates a unique download token. That token is the buyer's key to their file. It's tied to a specific purchase, valid for a limited time, and usable a limited number of times. Once it expires or is used up, it stops working. The file stays protected, and access stays controlled.

What a Token Actually Is

A download token is a randomly generated string stored in CARL's database alongside the purchase record to which it belongs. When a buyer clicks their download link, the URL contains that token as a parameter. CARL's delivery script reads the token, looks it up in the database, checks its validity, and either streams the file or returns an error. The token is the only thing standing between the request and the file.

Because the token is random and generated fresh for each purchase, there's no way to guess or construct a valid one. A buyer can't share their link with someone else and expect it to work indefinitely because the token has an expiry and a usage limit.

Expiry and Use Limits

When you set up a product in CARL's Downloads module, you configure how long the token remains valid and how many times it can be used. A token might be valid for 48 hours and allow three downloads, giving the buyer enough flexibility to download on multiple devices without leaving access open indefinitely. Once the expiry time passes or the use count is reached, whichever comes first, the token stops working.

These limits are practical rather than restrictive. Most buyers download a file once or twice immediately after purchase. The limits exist to prevent a download link from circulating as permanent free access to your product, not to create friction for legitimate customers.

What Happens When a Token Is Checked

When the delivery script receives a download request, it runs through a short sequence of checks: does this token exist in the database, is it linked to a completed purchase, has it expired, has it exceeded its use limit? If every check passes, the script increments the use count, streams the file to the browser, and completes the download. If any check fails, the request stops there.

The file never moves to a public URL at any point in this process. It stays in its protected directory on the server and is streamed directly to the buyer by the delivery script. The token is consumed in the transaction; the file is not.

Tokens and the Purchase Record

Every token is attached to a purchase record in CARL's database. That record contains the buyer's details, the product they purchased, the PayPal payment confirmation, and the issued token. If a buyer contacts you with a download problem, you can look up their purchase record, check the token status, and issue a replacement if needed. The full history is there.

For a complete picture of how tokens fit into the purchase flow from start to finish, see How selling digital downloads works in CARL.

How CARL's Preview System Works

Because CARL pages are static PHP files written to disk at publish time, there's no live rendering happening in the background that you can peek at before committing. The preview system bridges that gap: it lets you see what a page will look like before the file is served from your public document root, so you can check layout, content, and formatting without putting an unfinished page in front of visitors or search engines.

How the Preview Is Generated

When you trigger a preview in the CARL editor, CARL runs the same generation process it uses for a full publish. It takes your current content, runs it through the assigned template, compiles the complete HTML output, and renders it in a preview context. The difference is where the output goes: instead of writing a file to your public directory, CARL renders it in a way that only you can see from inside the admin session.

What you see in the preview is a faithful representation of the published page. The template, the meta tags, the content formatting, the layout: all of it reflects exactly what would be generated if you clicked the publish button. There's no simplified preview mode that strips parts of the template to speed up rendering.

Checking Before You Publish

Preview is particularly useful when you're working with a new custom template for the first time. Building a template involves some iteration: you write the structure, check how the content fits within it, adjust spacing or markup, and check again. Being able to do that without generating live files each time keeps your public directory clean during the development process.

It's also useful for content-heavy pages where formatting matters: long articles, product pages, comparison tables. Seeing the page at full width in its actual template before publishing catches layout issues that aren't obvious in the editor's content field.

Preview Doesn't Write to Disk

This is the key distinction. A preview doesn't create a file. Nothing is written to public_html/, no URL becomes accessible, and Google can't crawl it. The preview exists only during your admin session. Once you close the preview or log out, there's nothing left on the server from that preview operation.

The only way to put a page on disk is to click Generate. Preview and Generate are separate actions with separate consequences. You can preview a page as many times as you like, without those previews affecting your live site.

After the Preview Looks Right

Once the preview confirms the page looks the way you want it, click Generate to write the file to disk and make the page live. If you've set a scheduled publish date, the file will be written automatically at that time instead. Either way, what gets published is exactly what you saw in the preview: the same content, the same template, the same output.

The preview system removes the guesswork from publishing. You write, you check, you generate. The page on disk matches what you approved in the preview, with no surprises when you visit the live URL.

How to Bulk-Regenerate Pages in CARL

Every page in CARL is a static PHP file written to disk at publish time. That's what makes them fast and secure, but it also means that when something changes sitewide, like a template update, a navigation change, or a footer edit, the existing files on disk don't update themselves. Bulk regenerate is how you push those changes across every page on your site in a single operation.

When You Need It

The most common trigger for a bulk regenerate is a change to a template. If you've updated your site's navigation, changed the footer, added a sitewide script, or modified the layout in any way, the pages already on disk still contain the old template. They won't reflect the update until they're regenerated. Bulk regenerate handles all of them at once rather than requiring you to open and regenerate each page individually.

Other situations that call for a bulk regenerate include updating your site's global settings that feed into page output, changing the default schema structure, or recovering from a situation where files on disk have become out of sync with the records in the database. Any time you need the entire site to reflect a change made in the admin, use bulk regenerate.

How It Works

Bulk regenerate runs through every published page record in your database and triggers the generation process for each one in sequence. CARL takes each page's content, runs it through its assigned template, and overwrites the existing PHP file on disk with a freshly generated version. Pages that haven't changed come out identical to before. Pages affected by the template or settings change come out updated.

The process runs server-side, so you don't need to keep the browser tab open for the entire duration on a small site. On a larger site with hundreds of pages, give it time to complete before navigating away from the admin panel.

What It Doesn't Do

Bulk regenerate updates existing pages. It doesn't clean up orphaned files left behind by slug or directory changes. If you renamed a page's slug before running bulk regenerate, the new file gets written at the new path but the old file at the old path remains on disk. File cleanup after structural changes is a manual step via cPanel's File Manager.

It also doesn't regenerate pages in draft or scheduled status. Only published pages are included in the bulk regenerate pass. Scheduled pages will be generated at their publish time as normal.

Making It Part of Your Workflow

Getting into the habit of running a bulk regenerate after any sitewide change removes the risk of pages falling out of sync with your current template or settings. It takes a few seconds on a small site and a few minutes on a large one. The cost is low; the alternative, discovering that half your pages are showing an outdated layout because you forgot to regenerate them, is considerably more frustrating.

For sites built around a content publishing schedule, a bulk regeneration after each batch of edits is a clean way to confirm that everything on disk matches everything in the admin. Think of it as a final consistency check before you consider a work session done.

How to Create a Page in CARL

Creating a page in CARL is a linear process: fill in the fields, click Generate, and a finished PHP file lands on your server. There's no draft mode to navigate, no publish/update confusion, and no plugin adding fields you didn't ask for. You fill in what matters, generate the file, and the page is live.

Open the Page Editor

From the CARL admin panel, go to Pages and click Add New Page. The page editor opens with a set of fields organized into two areas: the main content fields and the SEO/meta fields. Everything that ends up in the published PHP file gets set here.

The Core Fields

The Title field sets the page's https://carlriedel.com/wiki/architecture/what-happens-when-you-publish-a-page.php https://carlriedel.com/wiki/architecture/what-happens-when-you-publish-a-page.php Mon, 01 Jun 2026 12:29:18 +0000 Carl Riedel

What Happens When You Publish a Page in CARL