{"_id":"@apostrophecms/seo-stable","name":"@apostrophecms/seo-stable","dist-tags":{"latest":"1.4.3"},"versions":{"1.4.3":{"name":"@apostrophecms/seo-stable","version":"1.4.3","description":"SEO Tools for ApostropheCMS","main":"index.js","scripts":{"lint":"npm run eslint","eslint":"eslint .","pretest":"npm run lint","test":"nyc mocha test/unit-tests.js -t 5000 && nyc mocha test/functional-tests.js -t 30000"},"repository":{"type":"git","url":"git+https://github.com/apostrophecms/apostrophe.git","directory":"packages/seo"},"homepage":"https://github.com/apostrophecms/apostrophe/blob/main/packages/seo","author":{"name":"Apostrophe Technologies"},"license":"MIT","dependencies":{"lodash":"^4.18.1"},"devDependencies":{"@apostrophecms/blog":"workspace:^","@apostrophecms/seo":"workspace:*","apostrophe":"workspace:^","eslint":"^9.39.1","eslint-config-apostrophe":"workspace:^","mocha":"^11.7.5","nyc":"^17.1.0"},"gitHead":"b3e29f004f514041e1e389293ae67017c60d006e","_id":"@apostrophecms/seo-stable@1.4.3","bugs":{"url":"https://github.com/apostrophecms/apostrophe/issues"},"_nodeVersion":"24.10.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-+E05T/vC643m6GZgEPaDPEIHkMZP6PAppLGwZwcKaFexBpqWpLS4qNgEPsX485z9KkcCQYaYYzEi1X2vuwcBlA==","shasum":"f26e9ad2f27b204c05cb79e2b34eed14aa9fd89e","tarball":"https://registry.npmjs.org/@apostrophecms/seo-stable/-/seo-stable-1.4.3.tgz","fileCount":36,"unpackedSize":474377,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHhAh90R1SJSqIrycX2BND57eoSYq6EALoeozNVqSuBrAiEAsmZVlHEljDDg0nkCKWorkJcSUhqy1S0zdDVU3y5ObXY="}]},"_npmUser":{"name":"boutell","email":"tom@apostrophecms.com"},"directories":{},"maintainers":[{"name":"alexgilbert","email":"alex@apostrophecms.com"},{"name":"boutell","email":"tom@apostrophecms.com"},{"name":"romanek","email":"stuart+npm@apostrophecms.com"},{"name":"bodonkey","email":"robert.means1969+apostrophecms@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/seo-stable_1.4.3_1781112826122_0.28621244407554114"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-10T17:33:45.976Z","1.4.3":"2026-06-10T17:33:46.270Z","modified":"2026-06-10T17:33:46.535Z"},"maintainers":[{"name":"alexgilbert","email":"alex@apostrophecms.com"},{"name":"boutell","email":"tom@apostrophecms.com"},{"name":"romanek","email":"stuart+npm@apostrophecms.com"},{"name":"bodonkey","email":"robert.means1969+apostrophecms@gmail.com"}],"description":"SEO Tools for ApostropheCMS","homepage":"https://github.com/apostrophecms/apostrophe/blob/main/packages/seo","repository":{"type":"git","url":"git+https://github.com/apostrophecms/apostrophe.git","directory":"packages/seo"},"author":{"name":"Apostrophe Technologies"},"bugs":{"url":"https://github.com/apostrophecms/apostrophe/issues"},"license":"MIT","readme":"
\n \"ApostropheCMS\n\n

SEO Tools for ApostropheCMS

\n

\n \n \n \n \n \"\"\n \n \n \"\"\n \n

\n
\n\n**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.\n\n## Why ApostropheCMS SEO Tools?\n\n- **🎯 Complete SEO Control**: Essential meta fields for titles, descriptions, and canonical URLs\n- **📊 Analytics Ready**: Built-in Google Analytics, Tag Manager, and Site Verification integration\n- **🤖 Smart Automation**: Automatic robots.txt generation with granular control\n- **⚡ Performance Optimization**: Critical font preloading improves Core Web Vitals scores\n- **🔍 Search Engine Friendly**: Proper canonical linking prevents duplicate content issues\n- **📈 Marketing Team Ready**: Easy-to-use interface for non-technical content creators\n- **💰 E-commerce Ready**: Rich structured data for products, offers, and pricing\n- **🤖 AI-Ready**: Automatic llms.txt generation for AI policy transparency (proposed standard for forward-thinking SEO)\n\n\n## Compatibility\n\nThis 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.\n\n---\n\n## TL;DR: Quick Setup\n\n1. Install the module:\n\n ```bash\n npm install @apostrophecms/seo\n ```\n2. Set your base URL (`APOS_BASE_URL`).\n3. Enable Google Analytics or Tag Manager in `@apostrophecms/global`.\n4. Optionally install `@apostrophecms/sitemap` for XML sitemap generation.\n5. Configure `robots.txt` and `llms.txt` via global settings.\n6. Choose schema types per page in the SEO tab.\n7. Validate your structured data using [Google’s Rich Results Test](https://search.google.com/test/rich-results).\n\n---\n\n## Table of Contents\n\n- [Why ApostropheCMS SEO Tools?](#why-apostrophecms-seo-tools)\n- [TL;DR: Quick Setup](#tldr-quick-setup)\n- [Table of Contents](#table-of-contents)\n- [Installation](#installation)\n- [Before You Start](#before-you-start)\n - [✅ Works Immediately (No Setup Required)](#-works-immediately-no-setup-required)\n - [⚙️ Requires Content Structure Setup](#️-requires-content-structure-setup)\n- [Core Features](#core-features)\n - [Automatic SEO Fields](#automatic-seo-fields)\n - [Google Analytics \\& Tag Manager](#google-analytics--tag-manager)\n - [Automated Robots.txt](#automated-robotstxt)\n - [AI Crawler Control (llms.txt)](#ai-crawler-control-llmstxt)\n - [Sitemap Integration](#sitemap-integration)\n - [Performance Optimization](#performance-optimization)\n- [Essential Configuration](#essential-configuration)\n - [Setting the Base URL](#setting-the-base-url)\n - [Google Analytics Integration](#google-analytics-integration)\n - [Google Tag Manager Integration](#google-tag-manager-integration)\n - [Google Site Verification](#google-site-verification)\n - [Sitemap Installation](#sitemap-installation)\n- [Structured Data \\& Schema Types](#structured-data--schema-types)\n - [How It Works](#how-it-works)\n - [Choosing the Right Schema](#choosing-the-right-schema)\n - [Quick Schema Selection Guide](#quick-schema-selection-guide)\n - [Best Practices](#best-practices)\n- [AI \\& Search Strategy](#ai--search-strategy)\n - [Understanding Crawler Types](#understanding-crawler-types)\n - [Recommended Configuration for Most Sites](#recommended-configuration-for-most-sites)\n - [For Maximum AI Visibility](#for-maximum-ai-visibility)\n - [For Maximum Privacy/Protection](#for-maximum-privacyprotection)\n - [Understanding robots.txt vs llms.txt](#understanding-robotstxt-vs-llmstxt)\n - [Site Search Query Parameter](#site-search-query-parameter)\n- [Advanced Configuration](#advanced-configuration)\n - [Disabling SEO Fields](#disabling-seo-fields)\n - [Setting Default Schema Types](#setting-default-schema-types)\n - [Canonical Link Configuration](#canonical-link-configuration)\n - [Pagination Support](#pagination-support)\n - [Custom 404 Tracking](#custom-404-tracking)\n - [Paywalled Content](#paywalled-content)\n - [Custom Field Mappings](#custom-field-mappings)\n- [Implementation Guidelines for Developers](#implementation-guidelines-for-developers)\n - [Field Flexibility](#field-flexibility)\n - [Flexible Field Formats](#flexible-field-formats)\n - [Debug Mode](#debug-mode)\n - [Featured Images](#featured-images)\n - [Author Information](#author-information-1)\n - [URL Requirements](#url-requirements)\n - [Date Fields](#date-fields)\n - [Listing Pages (Item List)](#listing-pages-item-list)\n - [Summary: Key Document-Level Fields by Schema Type](#summary-key-document-level-fields-by-schema-type)\n - [Schema Types That Require No Developer Fields](#schema-types-that-require-no-developer-fields)\n - [Debugging Structured Data](#debugging-structured-data)\n- [Extending the SEO Module with Custom JSON-LD Schemas](#extending-the-seo-module-with-custom-json-ld-schemas)\n - [1. Register a Custom Schema on `@apostrophecms/seo`](#1-register-a-custom-schema-on-apostrophecmsseo)\n - [2. Add the Type to the Schema Dropdown (`@apostrophecms/seo-fields-doc-type`)](#2-add-the-type-to-the-schema-dropdown-apostrophecmsseo-fields-doc-type)\n - [3. Add Fields on `@apostrophecms/doc-type`](#3-add-fields-on-apostrophecmsdoc-type)\n- [Performance Optimization](#performance-optimization-1)\n - [Critical Font Preloading](#critical-font-preloading)\n- [1. Place Your Fonts in a Module’s `public/` Directory](#1-place-your-fonts-in-a-modules-public-directory)\n- [2. Configure the SEO Module to Preload Fonts](#2-configure-the-seo-module-to-preload-fonts)\n - [Mobile Optimization](#mobile-optimization)\n- [Field Reference](#field-reference)\n- [🚀 Ready for AI-Powered SEO?](#-ready-for-ai-powered-seo)\n - [✨ SEO Assistant Pro Features](#-seo-assistant-pro-features)\n- [🏢 Managing Multiple Sites?](#-managing-multiple-sites)\n - [✨ Assembly Multisite Features](#-assembly-multisite-features)\n- [Roadmap](#roadmap)\n\n## Installation\n\n```bash\nnpm install @apostrophecms/seo\n```\n\nConfigure the module in your `app.js` file:\n\n```javascript\nimport apostrophe from 'apostrophe';\n\napostrophe({\n root: import.meta,\n shortName: 'my-project',\n modules: {\n '@apostrophecms/seo': {}\n }\n});\n```\n\n**Important:** For proper SEO functionality, you must also configure your site's base URL. See the [Essential Configuration](#essential-configuration) section below.\n\n## Before You Start\n\nThis module provides SEO functionality at two levels:\n\n### ✅ Works Immediately (No Setup Required)\n\nThese features work out-of-the-box with any ApostropheCMS site:\n\n- **Essential meta tags**: Title, description, robots\n- **Analytics**: Google Analytics, Tag Manager, Site Verification\n- **Site control**: Automated robots.txt and llms.txt generation\n- **Basic structured data**: WebPage and CollectionPage schemas\n\n**You can start using these features right away** - just install the module and configure your global SEO settings.\n\n### ⚙️ Requires Content Structure Setup\n\nAdvanced structured data types need [fields with specific names](#summary-required-fields-by-schema-type) in your content types:\n\n- **Article, Review**: Work best with author information\n- **Product, HowTo**: Benefit from featured images for richer results\n- **Recipe**: **Requires** a featured image (Google requirement)\n- **VideoObject**: **Requires** thumbnail and upload date (Google requirement)\n- **JobPosting**: Complex schema with many required fields for Google for Jobs\n- **Event, LocalBusiness**: Need address/location fields\n- **FAQPage, QAPage**: Need question and answer content\n\n> [!IMPORTANT]\n> ### ⚠️ Important: Field Names Must Match Expected Names for Structured Data\n>\n> 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**.\n>\n> The module also supports **fallbacks and flexible formats** (e.g., string vs. relationship fields) for authors, images, descriptions, and dates.\n>\n> 👉 For the full list of supported field names, fallbacks, and recommended patterns, see **[Field Flexibility](#field-flexibility)**.\n>\n> You can also map existing field names to required field names using the [`seoFieldMappings`](#custom-field-mappings) option of the module.\n>\n> If you plan to rely heavily on structured data (especially for products, recipes, jobs, or video), it’s a good idea to:\n>\n> - Design your content types with these field names in mind, or\n> - Refactor existing types to match, before enabling those schema types in production.\n\n## Core Features\n\n### Automatic SEO Fields\n\n![The module adds an SEO tab to your editing modals](https://static.apostrophecms.com/apostrophecms/seo/images/seo-modal.png)\n\nThe module automatically adds an \"SEO\" tab to all page and piece editors containing:\n\n- **Title Tag**: Custom titles for search results (falls back to page title)\n- **Meta Description**: Compelling descriptions that appear in search results\n- **Robots Meta Tag**: Control search engine indexing and following behavior\n- **Canonical URLs**: Prevent duplicate content penalties\n- **Schema Type Selection**: Choose the appropriate structured data type for your content\n\n### Google Analytics & Tag Manager\n\nBuilt-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.\n\n**Supported integrations:**\n- Google Analytics (GA4) tracking\n- Google Tag Manager for advanced marketing campaigns\n- Google Site Verification for Search Console\n\nSee [Essential Configuration](#essential-configuration) below for setup instructions.\n\n### Automated Robots.txt\n\nThe 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:\n\n**Available Modes:**\n\n1. **Allow All (Search + AI)** - Default open access for all crawlers\n2. **Allow Search, Block AI Training** - Maintains search rankings while protecting content from AI training by AI agents that choose to respect this standard\n3. **Selective AI Crawlers** - Granular control over individual AI crawlers that support this standard\n4. **Block All** - Prevents all indexing\n5. **Custom** - Write your own robots.txt content\n\n> ⚠️ Make sure that if you block all indexing during development, make sure to change the policy when you launch your final site.\n\n**Selective Mode Crawlers:**\nFor fine-grained control, use Selective mode to choose specific AI crawlers. These crawlers currently indicate they honor robots.txt directives.\n- **GPTBot** (OpenAI ChatGPT training)\n- **ChatGPT-User** (OpenAI real-time browsing)\n- **Google-Extended** (Google AI training)\n- **ClaudeBot** (Anthropic AI training)\n- **Claude-User** (Anthropic real-time browsing)\n- **PerplexityBot** (Perplexity AI)\n- **CCBot** (Common Crawl datasets)\n- **Applebot-Extended** (Apple Intelligence)\n- **FacebookBot** (Meta AI)\n- **anthropic-ai** (Anthropic general)\n\nTraditional search engines (Googlebot, Bingbot) are always allowed unless using \"Block All\" mode.\n\n> ### ⚠️ Important Note About Robots.txt Enforcement\n> The `robots.txt` standard is a **voluntary convention**, not a security mechanism.\n> While the crawlers listed here currently **state that they honor `robots.txt`**, real-world behavior can differ:\n>\n> - Some crawlers only respect `robots.txt` in certain contexts (e.g., indexing vs. real-time browsing).\n> - User-agent policies may change over time.\n> - New crawlers may appear that do not publicly disclose their behavior.\n>\n> 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.\n\n\n**Technical Notes:**\n- 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\n- All modes preserve traditional search engine access (except \"Block All\")\n- See [AI & Search Strategy](#ai--search-strategy) for detailed configuration guidance\n\n**Related:** This module also provides automated [llms.txt generation](#ai-crawler-control-llmstxt) for policy communication.\n\n> **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.\n\n### AI Crawler Control (llms.txt)\n\nThe module automatically provides an `/llms.txt` route to communicate your AI usage policies. This is **complementary** to `robots.txt`:\n\n- **robots.txt**: Enforceable crawler access control (blocks/allows bots)\n- **llms.txt**: Informational policy declaration (informs AI systems about usage terms)\n\n> **⚠️ 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.\n\n**Configuration options:**\n\n1. **Allow AI Crawling (Default)**: Generates a comprehensive `llms.txt` file that permits responsible AI crawling with site structure information\n\n2. **Disallow AI Training**: States content should NOT be used for AI training datasets but permits real-time search and retrieval with attribution\n\n3. **Custom Content**: Write your own `llms.txt` policies from scratch\n\n4. **Disabled**: Returns 404 for `/llms.txt` requests\n\n**Best Practice:** Combine both tools strategically:\n- Use **robots.txt** (Allow Search, Block AI Training mode) to technically enforce access\n- Use **llms.txt** (Disallow AI Training mode) to clearly communicate your policies\n- This dual approach provides both technical enforcement and clear policy communication\n\n**What's included in the generated file:**\n- Site name and description\n- AI training policy (based on your selection)\n- Organization information\n- Links to main pages with descriptions\n- Available content types\n- Technical details about structured data\n- Sitemap reference (if @apostrophecms/sitemap is installed)\n\n### Sitemap Integration\n\nWorks 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.\n\n### Performance Optimization\n\n**Critical Font Preloading** - Automatically preload critical fonts to improve Core Web Vitals scores and SEO performance:\n- Reduces Cumulative Layout Shift (CLS) by preventing font-loading jank\n- Improves Largest Contentful Paint (LCP) with faster font rendering\n- Optimizes First Contentful Paint (FCP) by eliminating render-blocking requests\n\nConfigure once in your `app.js` and the module handles the rest. See [Performance Optimization](#performance-optimization) for details.\n\n## Essential Configuration\n\n### Setting the Base URL\n\n**This step is required** for proper canonical link generation and SEO performance. If using [ApostropheCMS hosting](https://apostrophecms.com/hosting), this is set automatically.\n\n**Via environment variable (recommended):**\n```bash\nexport APOS_BASE_URL=https://yoursite.com\n```\n\n**Via configuration file:**\n```javascript\n// data/local.js\nexport default {\n baseUrl: 'https://yoursite.com',\n modules: {\n // other module configuration\n }\n};\n```\n\n**For multisite projects using ApostropheCMS Assembly:**\nThe base URL is automatically configured through the `baseUrlDomains` option. [Learn more about Assembly multisite hosting](https://apostrophecms.com/assembly).\n\n### Google Analytics Integration\n\nEnable Google Analytics tracking:\n\n```javascript\nimport apostrophe from 'apostrophe';\n\napostrophe({\n root: import.meta,\n shortName: 'my-project',\n modules: {\n '@apostrophecms/seo': {},\n '@apostrophecms/global': {\n options: {\n seoGoogleAnalytics: true\n }\n }\n }\n});\n```\n\nThis adds a field in the global configuration for your Google Analytics Measurement ID (e.g., `G-XXXXXXXXXX`).\n\n### Google Tag Manager Integration\n\nFor advanced tracking and marketing campaigns:\n\n```javascript\nimport apostrophe from 'apostrophe';\n\napostrophe({\n root: import.meta,\n shortName: 'my-project',\n modules: {\n '@apostrophecms/seo': {},\n '@apostrophecms/global': {\n options: {\n seoGoogleTagManager: true\n }\n }\n }\n});\n```\n\nAdd your GTM container ID (e.g., `GTM-XXXXXXX`) in the global configuration.\n\n### Google Site Verification\n\nVerify site ownership for Google Search Console:\n\n```javascript\nimport apostrophe from 'apostrophe';\n\napostrophe({\n root: import.meta,\n shortName: 'my-project',\n modules: {\n '@apostrophecms/seo': {},\n '@apostrophecms/global': {\n options: {\n seoGoogleVerification: true\n }\n }\n }\n});\n```\n\nEnter your verification meta tag content from Google Search Console in the global settings.\n\n### Sitemap Installation\n\n> [!TIP]\n> Installations of the sitemap module is optional, but highly recommended for better search rankings\n\nInstall the companion sitemap module for XML sitemap generation:\n\n```bash\nnpm install @apostrophecms/sitemap\n```\n\n```javascript\nimport apostrophe from 'apostrophe';\n\napostrophe({\n root: import.meta,\n shortName: 'my-project',\n modules: {\n '@apostrophecms/seo': {},\n '@apostrophecms/sitemap': {}\n }\n});\n```\n\n## Structured Data & Schema Types\n\nThis module generates rich structured data (JSON-LD) that helps search engines understand your content. All structured data is output in a single `