SEO tools for Apostrophe 3
Add useful meta fields to all pages and pieces.
Roadmap
Feature | Status |
---|---|
SEO Meta fields for pages and pieces | |
SEO Page Scanner |
Installation
npm install @apostrophecms/seo
Use
1. Initialization
Configure @apostrophecms/seo
in app.js
.
require('apostrophe')({
shortName: 'MYPROJECT',
modules: {
'@apostrophecms/seo': {}
}
});
baseUrl
Setting the It is important to set the baseUrl
option on your ApostropheCMS application for various reasons. In the SEO module, it contributes to building the correct canonical
link tag URL, so in production search engines and web crawlers will register the correct link. The baseUrl
can be set multiple ways:
With the APOS_BASE_URL
environment variable
How you set the variable will depend on your hosting setup.
As part of an environment configuration in data/local.js
This method is if you are using stagecoach or a similar system for deployment.
module.exports = {
baseUrl: 'https://mysite.com',
modules: {
// other module env configuration
}
};
Via the multisite module if using Apostrophe Assembly
See the multisite documentation for details.
2. Module configuration
SEO fields for pages
SEO fields are enabled automatically for any page-type module. The following modules disable SEO field enhancements by default by setting the seoFields
option to false
:
@apostrophecms/global
@apostrophecms/user
@apostrophecms/image
@apostrophecms/image-tag
@apostrophecms/file
@apostrophecms/file-tag
module.exports = {
extend: '@apostrophecms/page-type'
options: {
label: 'Personnel',
seoFields: false
}
};
The @apostrophecms/seo
module adds a new tab labeled SEO
to the document editor. This tab contains fields for setting the title, description, robots tag, and canonical link meta data to the head section of the page.
SEO fields for pieces
SEO fields for pieces, including canonical links to other pieces or pages, are activated by adding an seoCanonicalTypes
option. This option takes an array that includes comma-separated piece-type module names and/or the apostrophecms/page
manager to include all page types. This option is added to the piece-type module but will output the relevant SEO information on the show.html
page of the associated piece-page-type module. For example, the option seoCanonicalTypes: [ '@apostrophecms/page' ]
would be added to the modules/article/index.js
piece-type configuration for output on show pages generated by the modules/article-page
module.
module.exports = {
extend: '@apostrophecms/piece-type'
options: {
label: 'Article',
// allow the editor to select a published page or a `topic` piece type show page
seoCanonicalTypes: [ '@apostrophecms/page', 'topic' ]
}
};
Note that you cannot link to specific page-types, only all pages through
@apostrophecms/page
, but you can link to specific piece-types.
After adding this option to a piece-type, a new SEO tab will be added. In addition to the fields for title, description, and robots tag meta fields, there will be a new field for selecting the type of page to use for the canonical link populated by the items entered into the seoCanonicalTypes
array. Selecting a type will bring up a new input to enter the desired page by browsing or typing the name.
Add Google Analytics (GA)
Setting seoGoogleAnalytics: true
in @apostrophecms/global
will add a Google Analytics tracking ID field to your Global configuration:
require('apostrophe')({
shortName: 'MYPROJECT',
modules: {
'@apostrophecms/seo': {},
'@apostrophecms/global': {
options: {
seoGoogleAnalytics: true
}
}
}
});
Add Google Tag Manager (GTM)
Setting seoGoogleTagManager: true
in @apostrophecms/global
will add a Google Tag Manager ID field to your Global configuration:
require('apostrophe')({
shortName: 'MYPROJECT',
modules: {
'@apostrophecms/seo': {},
'@apostrophecms/global': {
options: {
seoGoogleTagManager: true
}
}
}
});
Add Google Site Verification
Setting seoGoogleVerification: true
in @apostrophecms/global
will add a Google Site Verification ID field to your Global configuration:
require('apostrophe')({
shortName: 'MYPROJECT',
modules: {
'@apostrophecms/seo': {},
'@apostrophecms/global': {
options: {
seoGoogleVerification: true
}
}
}
});
Notes
Canonical URls
The canonical link field on a page or piece allows an editor to select another page that search engines should understand to be the primary version of that page or piece. As described on Moz.com:
A canonical tag (aka "rel canonical") is a way of telling search engines that a specific URL represents the primary copy of a page. Using the canonical tag prevents problems caused by identical or "duplicate" content appearing on multiple URLs. Practically speaking, the canonical tag tells search engines which version of a URL you want to appear in search results.
For pages, this link can be to any published page. For pieces, this can be either a published page or another piece-page-type show page.
Custom Google Analytics Event on 404
Optionally add the following include to your notFound.html
view. If the app has a Google Tracking ID value entered, this will send an event to Google Analytics tracking the 404 response, the URL on which it happened, and, if applicable, the page on which the bad URL was triggered (helping you identify where bad links are located).
{% block extraBody %}
{{ super() }}
{% include "@apostrophecms/seo:404.html" %}
{% endblock %}
If you already have an extraBody
block in the notFound.html
view file, you'll only need to add the {% include "@apostrophecms/seo:404.html" %}
statement somewhere in that.
{% block extraBody %}
{# ...Other templating... #}
{% include "@apostrophecms/seo:404.html" %}
{% endblock %}
Field Reference
The following are the fields that can be added to pieces, pages, and the global doc, as well as what module option enables them.
Name | Description | Module Effected | Module Option |
---|---|---|---|
seoTitle |
Title attribute, populates <meta name="title" /> tag |
@apostrophecms/doc-type |
Enabled by default |
seoDescription |
Description attribute, populates <meta name="description" /> tag |
@apostrophecms/doc-type |
Enabled by default |
seoRobots |
Robots attribute, populates <meta name="robots" /> tag |
@apostrophecms/doc-type |
Enabled by default |
_seoCanonical |
Canonical URL, populates <link rel="canonical" /> tag |
@apostrophecms/page-type |
Enabled by default |
seoGoogleTagManager |
Google Tag Manager Container ID | @apostrophecms/global |
seoGoogleTagManager: true |
seoGoogleTrackingId |
Google Analytics ID | @apostrophecms/global |
seoGoogleAnalytics: true |
seoGoogleVerificationId |
Google Verification ID, populates <meta name="google-site-verification" />
|
@apostrophecms/global |
seoGoogleVerification: true |