Documentation HeadTag Manager

1. Install the package

1. Download the HeadTag Manager installation ZIP from your purchase.
2. In Joomla Administrator, open System → Install → Extensions.
3. Upload the complete package, for example pkg_headtagmanager_v1.2.5.zip. You do not need to extract it.
4. Open System → Manage → Plugins and check that System - HeadTag Manager is enabled.

The package installs the module, the head-output plugin and the update-key plugin together. The plugins are enabled automatically on a fresh installation.

2. Create your first module

1. Open Content → Site Modules → New and select HeadTag Manager.
2. Enter a title that helps you identify the tags, such as Home page sharing tags. Set Show Title to Hide.
3. Set Position to headtag-manager. If it is not listed, type the name and press Enter.
4. Paste your complete HTML tags into Custom head markup.
5. Leave Insert into head set to Yes and set Status to Published.
6. Choose the pages in Menu Assignment, then save the module.

3. Choose where the tags appear

Use the module's Menu Assignment tab:

• On all pages: apply the same tags wherever the module passes access, language, publishing and inheritance checks.
• Only on the pages selected: select the menu items that should receive the tags.
• On all pages except those selected: exclude specific menu items.
• No pages: keep the module without applying its tags.

Create separate HeadTag Manager instances when different pages need different tags. Joomla's access level, language and publishing dates also control when each instance applies.

Assignments follow the active Joomla menu item, not an exact URL. For category menu items, Include inherited pages defaults to No: tags stay on that category and its pagination. Set it to Yes to include articles and subcategories sharing the menu item. This restriction also applies to modules assigned to all pages. Automatic article tags are configured separately in the system plugin.

4. Example markup

Open Graph sharing tags

Copy this example into Custom head markup, then replace the title, description, page address and image address with your own values.

<meta property="og:title" content="My page title">
<meta property="og:description" content="A short description of this page.">
<meta property="og:type" content="website">
<meta property="og:url" content="https://example.com/my-page">
<meta property="og:image" content="https://example.com/images/share.jpg">

Use full public URLs for the page and image. For a title containing an ampersand, write Fish & Chips in the HTML attribute.

Structured data (JSON-LD)

This example describes an organization. Replace the example values and assign it to a suitable page.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "My Business",
  "url": "https://example.com",
  "logo": "https://example.com/images/logo.png"
}
</script>

5. Check the result

1. Open an assigned page on your website.
2. Use your browser's View Page Source option.
3. Search for a value you entered, such as og:title, and confirm that it appears inside <head>.
4. Check an unassigned page to confirm that the same module's tags are absent.

Clear Joomla and any page/CDN caches after changing tags or assignments if the old markup is still shown.

6. Automatic article sharing tags

Open System → Manage → Plugins → System - HeadTag Manager and enable Automatic article Open Graph. No module is needed. Remove the old Open Graph block from your article template override. Optionally enter your own Facebook App ID.

Under Article sharing options you can select categories and include descendants, enable image fallbacks (intro image, full image, default image), choose the description source and word-boundary length limit, and preserve existing tags or replace them with generated values.

Automatic article Open Graph is off by default. When enabled, it generates og:title, og:description, og:image, og:type and the absolute article URL in og:url. Empty descriptions and unavailable images are omitted. It runs on individual article pages, independently of module menu assignments.

For article overrides, create text, textarea and media/URL fields in Content → Fields, set their Automatic Display to Do not automatically display, enable Use article custom fields and enter their numeric IDs in the plugin. Fill in the fields on each article. Empty values fall back to article data. Joomla field publication, language and access rules apply.

Site name, locale, publication/modification dates and Twitter Card tags have separate optional switches. Existing settings are preserved; new optional features default to off.

Duplicate handling covers the rendered page head, including template and module tags, only for names generated on this article. Preserve keeps the first existing value; Replace uses the generated value. Extra duplicates of managed names are removed. Order this plugin after other tag-writing plugins and before page-cache plugins that save the response, then clear caches and check the output.

7. Automatic sharing tags for menu pages

1. Open System - HeadTag Manager → Menu sharing options.
2. Enable Automatic menu Open Graph; it is off by default.
3. Choose Selected menu items and select the pages, or choose All menu pages. An empty selection means no pages.
4. Under Individual menu images, add rows to assign pictures to menu items as described below.
5. Optionally choose a shared fallback under Menu sharing image, then save and clear caches.

Matching non-article component pages receive the page title (menu title fallback), page meta description (menu description fallback), og:type=website and an absolute menu URL. Empty descriptions and unset images are omitted. Add a meta description in the menu or component settings when needed. Pagination shares the menu landing-page URL.

Assign one picture to multiple menu items

1. Under Individual menu images, add a row.
2. In that row's Menu items selector, choose one or more menu items.
3. Choose the Sharing picture for those menu items.
4. Add another row, select another group of menu items and choose its picture. Repeat as needed.
5. Save, clear Joomla/page/CDN caches, and check a page from each group using View Page Source or the preview tool.

For example, select Home and About in the first row with your company picture, then select Services and Contact in a second row with another picture. You can also select just one menu item for a picture used only on that page. Existing single-menu selections remain supported after upgrading.

Image rows only choose pictures: pages must also be enabled by Menu scope and, when using Selected menu items, the main Menu items selection. For aliases, select the resolved target menu item.

If a menu item appears in several rows, its first matching row with a valid picture wins. Blank or invalid pictures are skipped. If no matching row has a valid picture, the plugin uses Menu sharing image as the shared fallback. Leave that fallback blank to generate no image for pages without a valid row picture. The chosen picture also supplies the Twitter Card image when Twitter Cards are enabled.

Keep or replace existing sharing images

Under Article sharing options → Existing sharing tags, choose how generated tags interact with existing tags. This policy also applies to automatic menu tags:

• Preserve existing values: keep the first existing og:image from a template, module or another extension. Use the configured picture when that tag is absent.
• Replace with generated values: use the picture selected from the image rows or shared fallback instead of an existing og:image.

Existing Open Graph and Twitter images are handled independently. If no valid picture is generated, existing image tags remain unchanged. The plugin does not scan menu-page content for images. Individual articles continue to use their separate article image and fallback settings.

Description length, existing-tag policy, site name, locale, Facebook App ID and Twitter Card settings also apply. These shared controls remain in the basic/article settings. Article-specific custom fields, image fallbacks, description source and dates do not apply to menu pages.

Individual articles still use Automatic article Open Graph and Article categories. Selecting a category menu does not enable its tags on inherited articles or subcategories. External links, headings, separators, edit forms and component actions are excluded. For menu aliases, select the resolved target menu item. Check third-party component routes using the preview tool.

8. Preview tags and diagnose duplicates

Open your Joomla site URL followed by /media/plg_system_headtagmanager/preview.html, keep any Joomla subdirectory in that URL, paste the complete rendered page source and click Inspect tags. The tool shows a text preview, tag values and warnings locally in your browser, without uploading source or fetching images.

The preview also reports why automatic menu tags were generated or skipped. To see generated candidates and their sources, enable Include tag diagnostics in the plugin, clear caches and copy fresh page source. Diagnostic data is public in the source. Disable it after checking and clear caches again. Existing raw tags can be identified as page-head tags, but their originating extension cannot be identified automatically.

9. Set up purchased updates

1. Open System → Manage → Plugins.
2. Find Installer - HeadTag Manager Update Key and check that it is enabled.
3. Paste the update key received with your purchase into Update key and save.
4. Use System → Update → Extensions to find and install available updates.

The key is used for protected update downloads. No key is needed to install, configure or run the module. If your update entitlement expires, your existing tags continue to work.

During a protected update download, the update plugin sends the key and your site's hostname to shop.topoweryou.com to validate the update entitlement and any update-domain limit. It does not make these requests during frontend page rendering. You do not need VirtueMart or VM Key Manager installed on your website.

Troubleshooting

Disable or uninstall

To stop a set of tags, unpublish its module or set Insert into head to No. To stop automatic article tags, set Automatic article Open Graph to No in the system plugin. To stop automatic menu tags, set Automatic menu Open Graph to No. Disable Include tag diagnostics separately if enabled, then clear caches. To remove the extension, first save any markup you want to keep, then open System → Manage → Extensions and uninstall the HeadTag Manager package.

Source code on GitHub

Browse the source code at Darko-F/HeadTag-Manager on GitHub. The repository includes the extension source and build tools. For the ready-to-install package and purchased updates, use your purchase download.