Metatag
Provides structured meta tags for Drupal content entities to improve SEO and social media sharing.
metatag
Install
composer require 'drupal/metatag:^2.2'
composer require 'drupal/metatag:^2.1'
Overview
The Metatag module allows site builders to automatically provide structured metadata (meta tags) about the site and individual pages. This metadata helps search engines understand page content, improves search rankings, and controls how content appears when shared on social networks like Facebook, Twitter, and LinkedIn.
The module uses a hierarchical defaults system where global meta tags can be overridden at the entity type level, bundle level, and finally per-entity level. Token support enables dynamic value insertion from entity fields and site information.
The module provides a plugin-based architecture with over 300 individual meta tags available through various submodules covering Open Graph Protocol, Twitter Cards, Dublin Core, favicons, mobile settings, and more. Custom meta tags can be added through the plugin system.
Features
- Hierarchical defaults system with global, entity type, bundle, and per-entity meta tag configuration
- Token-based dynamic value substitution for automatic meta tag population
- Field type for storing per-entity meta tag overrides with translation and revision support
- Support for over 300 meta tags through submodules covering Open Graph, Twitter Cards, Dublin Core, and more
- Plugin-based architecture for easily adding custom meta tags via contributed modules
- Views integration for adding meta tags to Views pages
- Migration support from Drupal 6 Nodewords and Drupal 7 Metatag modules
- JSON API / REST integration for exposing meta tags via web services
- Search API integration for indexing meta tag values
- Configuration for limiting which meta tag groups appear on entity forms
- Meta tag value trimming with configurable maximum lengths
- Report page showing all available meta tags and their providers
- Special meta tag configurations for front page, 403, and 404 error pages
- Widget settings for sidebar placement and scrollable containers
Use Cases
SEO optimization for content sites
Configure default meta tags with tokens like [node:title] and [node:summary] to automatically generate SEO-friendly meta descriptions. Set up per-content-type defaults for different description patterns.
Social media sharing optimization
Install metatag_open_graph and metatag_twitter_cards submodules to control how content appears when shared on Facebook, Twitter, LinkedIn, and Pinterest. Configure og:image and twitter:image tokens to use article featured images.
Multilingual site SEO
Use metatag_hreflang submodule to automatically generate hreflang tags for translated content, helping search engines serve the correct language version to users.
E-commerce product pages
Use metatag_open_graph_products to add product-specific meta tags for rich social sharing including price, availability, and product category information.
Site verification
Use metatag_verification submodule to add verification meta tags for Google Search Console, Bing Webmaster Tools, and other services without modifying theme templates.
Custom landing pages
Use metatag_routes submodule to configure meta tags for custom routes that aren't entity pages, such as Views pages or custom controllers.
Enterprise permission control
Install metatag_extended_perms to give different user roles access to different meta tags. Allow content editors to set descriptions while restricting robots tag access to administrators.
Tips
- Use tokens like [node:title] | [site:name] for automatic, consistent meta tag patterns across content
- Add separate fields for SEO title and description if you want simpler content editing, then reference those fields via tokens in global defaults
- Install only the submodules you actually need - fewer tags means faster forms and less complexity
- Use the meta tag groups feature in settings to hide irrelevant tags from content editors
- Configure trimming for description tags to stay within recommended character limits (155-160 for descriptions, 55-65 for titles)
- The Metatag field is only needed when per-entity customization is required; defaults handle most cases automatically
- Use the plugin report at /admin/reports/metatag-plugins to see all available tags and which module provides them
Technical Details
Admin Pages 6
/admin/config/search/metatag
Manage default meta tag configurations for the site. Displays a hierarchical list of all default configurations including Global, Front page, 403/404 error pages, and entity type/bundle specific overrides. Each configuration shows the defined meta tag values and allows editing, deleting, or reverting to defaults.
/admin/config/search/metatag/add
Create a new default meta tag configuration for a specific entity type or bundle. Select from available entity types and bundles that don't already have custom defaults configured.
/admin/config/search/metatag/{metatag_defaults}
Edit an existing default meta tag configuration. Modify meta tag values using direct text or tokens. Token browser available for viewing available replacement patterns.
/admin/config/search/metatag/settings
Configure module-wide settings including which meta tag groups appear on entity forms, meta tag value trimming, and widget display options.
/admin/reports/metatag-plugins
Report page showing all meta tag plugins available on the site. Lists each tag grouped by meta tag group with details including plugin ID, type, weight, provider module, and description.
/admin/config/search/metatag/custom/create
Create meta tag defaults for custom routes/paths. Provided by the Metatag Custom Routes submodule.
Permissions 1
Hooks 5
hook_metatag_route_entity
Allows modules to provide an entity for meta tag generation on custom routes not automatically detected.
hook_metatags_alter
Alter meta tag values before token replacement and rendering. Allows modifying or removing meta tags based on context.
hook_metatags_attachments_alter
Alter the rendered meta tag attachments before they are added to the page. Called after token replacement.
hook_metatag_migrate_metatagd7_tags_map_alter
Alter the mapping of Drupal 7 Metatag tag names to Drupal 8/9/10 tag IDs during migration.
hook_metatag_migrate_nodewordsd6_tags_map_alter
Alter the mapping of Drupal 6 Nodewords tag names to Drupal 8/9/10 tag IDs during migration.
Troubleshooting 5
Ensure the theme's html.html.twig outputs {{ page }} not {{ page.content }}. Check that the site is not in maintenance mode. Verify Global defaults are enabled at /admin/config/search/metatag.
Remove all Metatag fields from entity bundles before uninstalling. Check /admin/modules/uninstall for the specific field blocking removal.
Ensure the Token module is installed. Check that the correct token type is available for the context (e.g., [node:*] only works on node pages).
Use /admin/config/search/metatag/settings to limit which meta tag groups appear on each entity bundle. Only show groups actually needed for that content type.
Metatag automatically removes duplicate tags added by core. If duplicates persist, check for custom code or other modules adding the same tags.
Security Notes 4
- The 'administer meta tags' permission is marked as restricted access and should only be granted to trusted roles
- Meta tag values are sanitized before output to prevent XSS attacks
- Some meta tags marked as 'secure' will only output on HTTPS connections
- Extended permissions submodule allows fine-grained control over which users can edit which meta tags