SEO Tools for ApostropheCMS

Ensure your content gets found by search engines and AI systems with comprehensive SEO management for ApostropheCMS. Essential meta fields, Google Analytics integration, automated robots.txt and llms.txt generation — everything you need to boost your search rankings, control AI training usage, and drive organic traffic.

Why ApostropheCMS SEO Tools?

- 🎯 Complete SEO Control: Essential meta fields for titles, descriptions, and canonical URLs
- 📊 Analytics Ready: Built-in Google Analytics, Tag Manager, and Site Verification integration
- 🤖 Smart Automation: Automatic robots.txt generation with granular control
- ⚡ Performance Optimization: Critical font preloading improves Core Web Vitals scores
- 🔍 Search Engine Friendly: Proper canonical linking prevents duplicate content issues
- 📈 Marketing Team Ready: Easy-to-use interface for non-technical content creators
- 💰 E-commerce Ready: Rich structured data for products, offers, and pricing
- 🤖 AI-Ready: Automatic llms.txt generation for AI policy transparency (proposed standard for forward-thinking SEO)

Compatibility

This version requires the latest ApostropheCMS. When adding this module to an existing project, run npm update to ensure all ApostropheCMS modules are up-to-date.

---

TL;DR: Quick Setup

1. Install the module:

``bash
npm install @apostrophecms/seo
`
2. Set your base URL (APOS_BASE_URL).
3. Enable Google Analytics or Tag Manager in @apostrophecms/global.
4. Optionally install @apostrophecms/sitemap for XML sitemap generation.
5. Configure robots.txt and llms.txt via global settings.
6. Choose schema types per page in the SEO tab.
7. Validate your structured data using Google’s Rich Results Test.

---

Table of Contents

- Why ApostropheCMS SEO Tools?
- TL;DR: Quick Setup
- Table of Contents
- Installation
- Before You Start
- ✅ Works Immediately (No Setup Required)
- ⚙️ Requires Content Structure Setup
- Core Features
- Automatic SEO Fields
- Google Analytics \& Tag Manager
- Automated Robots.txt
- AI Crawler Control (llms.txt)
- Sitemap Integration
- Performance Optimization
- Essential Configuration
- Setting the Base URL
- Google Analytics Integration
- Google Tag Manager Integration
- Google Site Verification
- Sitemap Installation
- Structured Data \& Schema Types
- How It Works
- Choosing the Right Schema
- Quick Schema Selection Guide
- Best Practices
- AI \& Search Strategy
- Understanding Crawler Types
- Recommended Configuration for Most Sites
- For Maximum AI Visibility
- For Maximum Privacy/Protection
- Understanding robots.txt vs llms.txt
- Site Search Query Parameter
- Advanced Configuration
- Disabling SEO Fields
- Setting Default Schema Types
- Canonical Link Configuration
- Pagination Support
- Custom 404 Tracking
- Paywalled Content
- Custom Field Mappings
- Implementation Guidelines for Developers
- Field Flexibility
- Flexible Field Formats
- Debug Mode
- Featured Images
- Author Information
- URL Requirements
- Date Fields
- Listing Pages (Item List)
- Summary: Key Document-Level Fields by Schema Type
- Schema Types That Require No Developer Fields
- Debugging Structured Data
- Extending the SEO Module with Custom JSON-LD Schemas
- 1. Register a Custom Schema on @apostrophecms/seo
- 2. Add the Type to the Schema Dropdown (@apostrophecms/seo-fields-doc-type)
- 3. Add Fields on @apostrophecms/doc-type
- Performance Optimization
- Critical Font Preloading
- 1. Place Your Fonts in a Module’s public/ Directory
- 2. Configure the SEO Module to Preload Fonts
- Mobile Optimization
- Field Reference
- 🚀 Ready for AI-Powered SEO?
- ✨ SEO Assistant Pro Features
- 🏢 Managing Multiple Sites?
- ✨ Assembly Multisite Features
- Roadmap

Installation

`bash
npm install @apostrophecms/seo
`

Configure the module in your app.js file:

`javascript
import apostrophe from 'apostrophe';

apostrophe({
root: import.meta,
shortName: 'my-project',
modules: {
'@apostrophecms/seo': {}
}
});
`

Important: For proper SEO functionality, you must also configure your site's base URL. See the Essential Configuration section below.

Before You Start

This module provides SEO functionality at two levels:

$3

These features work out-of-the-box with any ApostropheCMS site:

- Essential meta tags: Title, description, robots
- Analytics: Google Analytics, Tag Manager, Site Verification
- Site control: Automated robots.txt and llms.txt generation
- Basic structured data: WebPage and CollectionPage schemas

You can start using these features right away - just install the module and configure your global SEO settings.

$3

Advanced structured data types need fields with specific names in your content types:

- Article, Review: Work best with author information
- Product, HowTo: Benefit from featured images for richer results
- Recipe: Requires a featured image (Google requirement)
- VideoObject: Requires thumbnail and upload date (Google requirement)
- JobPosting: Complex schema with many required fields for Google for Jobs
- Event, LocalBusiness: Need address/location fields
- FAQPage, QAPage: Need question and answer content

> [!IMPORTANT]
> ### ⚠️ Important: Field Names Must Match Expected Names for Structured Data
>
> Some structured data types require specific field names so that the SEO module can automatically find the right values in your documents. If your content types use different field names, and you don’t configure them accordingly, your JSON-LD may be missing required properties and fail validation in Google’s tools.
>
> The module also supports fallbacks and flexible formats (e.g., string vs. relationship fields) for authors, images, descriptions, and dates.
>
> 👉 For the full list of supported field names, fallbacks, and recommended patterns, see Field Flexibility.
>
> You can also map existing field names to required field names using the fieldMappings option of the module.
>
> If you plan to rely heavily on structured data (especially for products, recipes, jobs, or video), it’s a good idea to:
>
> - Design your content types with these field names in mind, or
> - Refactor existing types to match, before enabling those schema types in production.

Core Features

$3

!The module adds an SEO tab to your editing modals

The module automatically adds an "SEO" tab to all page and piece editors containing:

- Title Tag: Custom titles for search results (falls back to page title)
- Meta Description: Compelling descriptions that appear in search results
- Robots Meta Tag: Control search engine indexing and following behavior
- Canonical URLs: Prevent duplicate content penalties
- Schema Type Selection: Choose the appropriate structured data type for your content

$3

Built-in integration with Google Analytics, Google Tag Manager, and Google Site Verification. Simply enable the options you need and add your tracking IDs through the global configuration interface.

Supported integrations:
- Google Analytics (GA4) tracking
- Google Tag Manager for advanced marketing campaigns
- Google Site Verification for Search Console

See Essential Configuration below for setup instructions.

$3

The module automatically provides a /robots.txt route with strategic control over both traditional search engines and AI crawlers. Configure through global settings with five control modes:

Available Modes:

1. Allow All (Search + AI) - Default open access for all crawlers
2. Allow Search, Block AI Training - Maintains search rankings while protecting content from AI training by AI agents that choose to respect this standard
3. Selective AI Crawlers - Granular control over individual AI crawlers that support this standard
4. Block All - Prevents all indexing
5. Custom - Write your own robots.txt content

> ⚠️ Make sure that if you block all indexing during development, make sure to change the policy when you launch your final site.

Selective Mode Crawlers:
For fine-grained control, use Selective mode to choose specific AI crawlers. These crawlers currently indicate they honor robots.txt directives.
- GPTBot (OpenAI ChatGPT training)
- ChatGPT-User (OpenAI real-time browsing)
- Google-Extended (Google AI training)
- ClaudeBot (Anthropic AI training)
- Claude-User (Anthropic real-time browsing)
- PerplexityBot (Perplexity AI)
- CCBot (Common Crawl datasets)
- Applebot-Extended (Apple Intelligence)
- FacebookBot (Meta AI)
- anthropic-ai (Anthropic general)

Traditional search engines (Googlebot, Bingbot) are always allowed unless using "Block All" mode.

> ### ⚠️ Important Note About Robots.txt Enforcement
> The robots.txt standard is a voluntary convention, not a security mechanism.
> While the crawlers listed here currently state that they honor robots.txt, real-world behavior can differ:
>
> - Some crawlers only respect robots.txt in certain contexts (e.g., indexing vs. real-time browsing).
> - User-agent policies may change over time.
> - New crawlers may appear that do not publicly disclose their behavior.
>
> ApostropheCMS provides fine-grained controls for compliant crawlers, but it cannot guarantee enforcement against bots that ignore robots.txt or do not implement the standard. We recommend periodically reviewing crawler policies to ensure ongoing compliance.


Technical Notes:
- A physical robots.txt file in your public/ directory for a single-site project, or sites/public and dashboard/public directories for multisite will override these settings
- All modes preserve traditional search engine access (except "Block All")
- See AI & Search Strategy for detailed configuration guidance

Related: This module also provides automated llms.txt generation for policy communication.

> Note: A global Disallow: / in robots.txt may cause some AI crawlers to skip reading llms.txt, depending on their behavior, but the file remains publicly accessible.

$3

The module automatically provides an /llms.txt route to communicate your AI usage policies. This is complementary to robots.txt:

- robots.txt: Enforceable crawler access control (blocks/allows bots)
- llms.txt: Informational policy declaration (informs AI systems about usage terms)

> ⚠️ Important Note: llms.txt is a proposed standard that is not yet widely adopted. As of this writing, most LLMs and AI systems do not respect or read llms.txt files. This feature is included for forward-thinking SEO strategies and may gain broader adoption in the future. For enforceable crawler control, rely on robots.txt settings.

Configuration options:

1. Allow AI Crawling (Default): Generates a comprehensive llms.txt file that permits responsible AI crawling with site structure information

2. Disallow AI Training: States content should NOT be used for AI training datasets but permits real-time search and retrieval with attribution

3. Custom Content: Write your own llms.txt policies from scratch

4. Disabled: Returns 404 for /llms.txt requests

Best Practice: Combine both tools strategically:
- Use robots.txt (Allow Search, Block AI Training mode) to technically enforce access
- Use llms.txt (Disallow AI Training mode) to clearly communicate your policies
- This dual approach provides both technical enforcement and clear policy communication

What's included in the generated file:
- Site name and description
- AI training policy (based on your selection)
- Organization information
- Links to main pages with descriptions
- Available content types
- Technical details about structured data
- Sitemap reference (if @apostrophecms/sitemap is installed)

$3

Works seamlessly with @apostrophecms/sitemap to generate XML sitemaps that help search engines discover and index your content. The sitemap is automatically referenced in the /llms.txt file for AI crawlers.

$3

Critical Font Preloading - Automatically preload critical fonts to improve Core Web Vitals scores and SEO performance:
- Reduces Cumulative Layout Shift (CLS) by preventing font-loading jank
- Improves Largest Contentful Paint (LCP) with faster font rendering
- Optimizes First Contentful Paint (FCP) by eliminating render-blocking requests

Configure once in your app.js and the module handles the rest. See Performance Optimization for details.

Essential Configuration

$3

This step is required for proper canonical link generation and SEO performance. If using ApostropheCMS hosting, this is set automatically.

Via environment variable (recommended):
`bash
export APOS_BASE_URL=https://yoursite.com
`

Via configuration file:
`javascript
// data/local.js
export default {
baseUrl: 'https://yoursite.com',
modules: {
// other module configuration
}
};
`

For multisite projects using ApostropheCMS Assembly:
The base URL is automatically configured through the baseUrlDomains option. Learn more about Assembly multisite hosting.

$3

Enable Google Analytics tracking:

`javascript
import apostrophe from 'apostrophe';

apostrophe({
root: import.meta,
shortName: 'my-project',
modules: {
'@apostrophecms/seo': {},
'@apostrophecms/global': {
options: {
seoGoogleAnalytics: true
}
}
}
});
`

This adds a field in the global configuration for your Google Analytics Measurement ID (e.g., G-XXXXXXXXXX).

$3

For advanced tracking and marketing campaigns:

`javascript
import apostrophe from 'apostrophe';

apostrophe({
root: import.meta,
shortName: 'my-project',
modules: {
'@apostrophecms/seo': {},
'@apostrophecms/global': {
options: {
seoGoogleTagManager: true
}
}
}
});
`

Add your GTM container ID (e.g., GTM-XXXXXXX) in the global configuration.

$3

Verify site ownership for Google Search Console:

`javascript
import apostrophe from 'apostrophe';

apostrophe({
root: import.meta,
shortName: 'my-project',
modules: {
'@apostrophecms/seo': {},
'@apostrophecms/global': {
options: {
seoGoogleVerification: true
}
}
}
});
`

Enter your verification meta tag content from Google Search Console in the global settings.

$3

> [!TIP]
> Installations of the sitemap module is optional, but highly recommended for better search rankings

Install the companion sitemap module for XML sitemap generation:

`bash
npm install @apostrophecms/sitemap
`

`javascript
import apostrophe from 'apostrophe';

apostrophe({
root: import.meta,
shortName: 'my-project',
modules: {
'@apostrophecms/seo': {},
'@apostrophecms/sitemap': {}
}
});
`

Structured Data & Schema Types

This module generates rich structured data (JSON-LD) that helps search engines understand your content. All structured data is output in a single