# Magento 2 HTML Sitemap - Sitemap User Guide

> Add a searchable, hierarchical HTML sitemap to your Magento 2 store covering categories, products, CMS pages, and custom links - all in one place.

---

## Overview

Sitemap adds an interactive HTML sitemap page to your Magento 2 storefront. It builds a hierarchical view of your store's category tree, products, CMS pages, and any custom links you choose to include. A real-time search bar lets shoppers filter the sitemap as they type, and a responsive multi-column layout keeps the page usable on mobile.

![Sitemap configuration overview](images/overview.png)

This module helps you:

- Give shoppers a single page where they can browse or search your entire store structure
- Surface CMS pages that would otherwise be hard to discover through normal navigation
- Add hand-curated internal or external links alongside your category tree
- Put a footer link to the sitemap on every page of your store
- Keep empty categories out of the sitemap so shoppers see only useful content

---

## When to use this

Use Sitemap when you want to:

- Provide a fallback navigation aid for shoppers who can't find what they're looking for through menus
- Improve crawlability by giving search engines a single page that links to all major sections
- Showcase seasonal or promotional CMS landing pages alongside your category structure
- Include partner or reference links in an organised section of your store
- Reduce support queries from customers who ask "where do I find X?"

---

## Key capabilities

- **Category tree display** - Renders your full category hierarchy as nested H2 headers and subcategory links, with optional product counts
- **Product listings** - Optionally shows products within each category so shoppers can jump straight to a product
- **CMS page integration** - Picks specific CMS pages from a multi-select list and includes them in the sitemap
- **Custom links** - Accepts a plain-text list of URLs and anchor labels, with optional `<em>` styling and `<h2>` section headings
- **Real-time search** - Filters category and product links as the shopper types, hiding non-matching items without a page reload
- **Footer link** - Optionally injects a "Sitemap" link into your store's footer on every page
- **Empty-category suppression** - Hides categories that have no products, keeping the sitemap clean

---

## Installation

Sitemap installs via Composer, then activates with a license key from your Moogento.com account. The whole flow takes about 5 minutes.

### Step 1: Get your Composer keys from Moogento.com

1. Sign in at **https://www.moogento.com** and open **My Plugins** in your account menu.
2. Find **Sitemap** in the list of plugins you own.
3. Generate (or reveal) the Composer access keys for that plugin - a **public key** and a **private key**.
4. **Add your install domain to the key.** Each Composer key is tied to a specific domain - if you're installing on `yourstore.com`, add `yourstore.com` to the key's allowed domains. The Composer download will be rejected on any other domain.

If you run staging and production on different domains, add both - separate keys per environment are fine too.

### Step 2: Install the module with Composer

From your Magento 2 root directory:

```
composer require moogento/module-sitemap
```

When Composer asks for credentials, paste the **public key** as the username and the **private key** as the password. They'll be cached in `~/.composer/auth.json` for future runs.

### Step 3: Enable the module in Magento

```
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:clean
```

If you run `php bin/magento module:status Moogento_Sitemap` you should see it listed as enabled.

### Step 4: Add your license key in the Moogento admin

1. Still on **https://www.moogento.com > My Plugins**, copy the **license key** for Sitemap (separate from the Composer keys you used above).
2. In your Magento admin, go to **Stores > Configuration > Moogento > Licenses**.
3. Find the row for **Sitemap** and paste the license key.
4. Click **Save Config**, then run `php bin/magento cache:clean` once.

The license validates within a few seconds. You should see the module's status flip to active. If it stays inactive, double-check the domain on the license matches where you've installed - domain mismatch is the most common cause.

---

## Setup overview

Most setup happens in:

Stores > Configuration > Moogento > Sitemap

You'll mainly work with:

- **General** - master enable/disable switch, footer link, category and product display, CMS pages, and custom links

All settings are available at the default, website, and store-view scopes.

---

## Common setups

### Turn on the sitemap and add a footer link

You've just installed Sitemap and want shoppers to be able to find it from every page.

#### How to set it up

1. Go to:
   Stores > Configuration > Moogento > Sitemap > General

   ![General config group](images/config-sitemap.png)

2. Set:
   - **Enable: Sitemap** = Yes
   - **Add: Sitemap link to footer** = Yes
   - **Include: Categories & products** = Yes

3. Click **Save Config**, then run:
   ```
   php bin/magento cache:clean
   ```

4. Visit your storefront. A "Sitemap" link should appear in the footer, and navigating to `/sitemap/index/index` should show the category tree.

#### Notes

- The footer link respects the **Add: Sitemap link to footer** config value (`moositemap/sitemap/footer`). If the link does not appear, verify the field is set to Yes at the correct store scope and that your theme's footer block is not overriding the layout.
- On Hyvä storefronts the footer link is rendered by the `Hyva_MoogentoSitemap` compatibility module; no extra action is required as long as that module is enabled.

---

### Add selected CMS pages to the sitemap

You have landing pages - a returns policy page, a brand story page - that you want shoppers to discover from the sitemap.

#### How to set it up

1. Go to:
   Stores > Configuration > Moogento > Sitemap > General

2. Set:
   - **Include: Specific CMS pages** = Yes

3. The **Filter: CMS pages** multi-select becomes visible. Select each page you want to include. Only active pages are listed; 404 and cookie pages are excluded automatically.

4. Click **Save Config**, then run:
   ```
   php bin/magento cache:clean
   ```

#### Notes

- The list shows pages valid for the current store scope. If a page is missing, confirm it is active and assigned to the current store view.
- Technical paths: `moositemap/sitemap/include_cms_yn` and `moositemap/sitemap/include_cms_listing`.

---

### Add custom links and section headings

You want to include links to your social media profiles, a partner site, or a promotional microsite - with a clear "More resources" heading separating them from your categories.

#### How to set it up

1. Go to:
   Stores > Configuration > Moogento > Sitemap > General

2. Set:
   - **Include: Additional links** = Yes

3. In the **Links** textarea that appears, enter one link per line using the format `{url},{anchor text}`. Supported extras:
   - Wrap anchor text in `<em>…</em>` to apply emphasis styling.
   - Use a bare `<h2>…</h2>` line (no URL, no comma) to insert a section heading that starts a new block.

   Example:
   ```
   <h2>More resources</h2>
   https://www.instagram.com/yourstore/,Follow us on Instagram
   https://www.yourpartner.com/,Partner Site <em>Exclusive deals</em>
   ```

4. Click **Save Config**, then run:
   ```
   php bin/magento cache:clean
   ```

#### Notes

- Only the following HTML tags are permitted in anchor text: `<em>`, `<b>`, `<span>`, `<br>`, `<h2>`, `<strong>`, `<ul>`. Any other tags are stripped.
- Technical path: `moositemap/sitemap/include_links_listing`.

---

## Features reference

### Hide empty categories

Keeps the sitemap focused by omitting categories that contain no products. Useful for stores with seasonal or draft categories that you haven't populated yet.

- **What it does**: Checks each category's product count before rendering. Categories with zero visible products are skipped.
- **When to use it**: When your category tree includes placeholder categories that shoppers would find confusing or misleading.
- **Config path**: Stores > Configuration > Moogento > Sitemap > General > **Hide: Empty categories** (`moositemap/sitemap/hide_empty_categories_yn`)

---

### Show products within categories

Renders individual product links indented beneath each category in the sitemap, letting shoppers jump directly to a product page.

- **What it does**: Queries each category's product collection (active, visible, store-scoped) and outputs links beneath the category heading. Product count is shown in parentheses next to the category name when more than one product is present.
- **When to use it**: For smaller catalogs where surfacing products in the sitemap adds navigation value. For large catalogs this can make the page unwieldy - consider leaving it disabled and relying on the category links alone.
- **Config path**: Stores > Configuration > Moogento > Sitemap > General > **Show: products** (`moositemap/sitemap/show_products`)

---

### Real-time search

A search bar at the top of the sitemap page filters visible links as the shopper types, hiding non-matching category and product names without a page reload.

- **What it does**: Compares each category or product link label (case-insensitively) against the typed query and toggles a CSS class to hide non-matches. The product count badge is also hidden for filtered-out items.
- **When to use it**: Always active when the module is enabled - no separate configuration is required.
- **Frontend URL**: `/sitemap/index/index`

---

## Advanced configuration

### Scope of hide-empty-categories and show-products

The **Hide: Empty categories** and **Show: products** fields are `showInDefault="1"` only - they are not available at website or store-view scope. Set them at the default configuration level and they apply globally. If you need per-store behaviour, consider using store-specific category visibility settings in the Magento catalog instead.

#### Notes

- Changing these values requires a cache flush: `php bin/magento cache:clean layout block_html full_page`.

---

### Performance on large catalogs

If your store has thousands of categories or products and the sitemap page is slow to load:

1. Enable **Hide: Empty categories** to reduce the number of nodes rendered.
2. Set **Show: products** = No - product queries run per-category and are the primary contributor to load time on large catalogs.
3. Enable Magento's full-page cache (FPC). The sitemap block is marked `cacheable="false"` because it is personalisation-free, but the page itself can be cached by Varnish or the built-in FPC.
4. If memory exhaustion occurs, increase `memory_limit` in your PHP configuration and reindex: `php bin/magento indexer:reindex catalog_category_flat catalog_product_flat`.

---

## Tips & best practices

- Run `php bin/magento cache:clean` after every config change - the sitemap page renders PHP blocks that pick up config values at page load time.
- Set **Hide: Empty categories** = Yes on production stores so shoppers never land on a category with no products via the sitemap.
- Use `<h2>` section headings in the custom links field to visually group external links and prevent a long flat list.
- Keep the custom links list short - the sitemap search only filters category and product links, not custom links, so very long custom link sections are harder for shoppers to scan.
- On Hyvä storefronts, no additional compatibility steps are required beyond having the `Hyva_MoogentoSitemap` module enabled. It replaces the Luma stylesheet automatically and uses Tailwind-scoped CSS.
- Verify the sitemap renders at the correct store scope before going live - config values are scope-sensitive and a "Yes" at default level can be overridden to "No" at store-view level.

---

## Troubleshooting

### Sitemap page shows no content

The sitemap URL (`/sitemap/index/index`) loads but the page is blank or has no links.

- **Cause:** The module is disabled or **Include: Categories & products** is set to No with no CMS pages or custom links enabled either.
- **Check:** In the admin go to Stores > Configuration > Moogento > Sitemap > General and confirm **Enable: Sitemap** = Yes and at least one content type (categories, CMS pages, or custom links) is enabled.
- **Resolution:** Enable the module and at least one content source, save config, then run `php bin/magento cache:clean`.

---

### A category does not appear in the sitemap

One or more categories are missing from the sitemap even though they exist in the catalog.

- **Cause:** The category is inactive, not assigned to the current store, or is empty and **Hide: Empty categories** is set to Yes.
- **Check:** In the Magento catalog, confirm the category's **Enable Category** flag is Yes and it is included in the store's root category. Check that the category has at least one active, visible product if **Hide: Empty categories** is enabled.
- **Resolution:** Activate the category, assign it to the correct store view, or add at least one product. Clear cache after any change.

---

### Footer link does not appear

The "Sitemap" link is not visible in the storefront footer despite **Add: Sitemap link to footer** being set to Yes.

- **Cause:** Layout cache is stale, or the theme's footer block is overriding the layout XML that inserts the link.
- **Check:** Run `php bin/magento cache:clean layout block_html full_page` and reload the storefront. If still missing, inspect the page source for the `moo_sitemap_footer_link` block - if absent, the theme may be replacing the `footer_links` block entirely.
- **Resolution:** Flush the layout cache. If the theme overrides `footer_links`, add the sitemap link directly to the theme's footer template or use a layout override that references the correct parent block.

---

### Search bar does not filter results

Typing in the sitemap search input has no effect - links remain visible regardless of what is typed.

- **Cause:** A JavaScript conflict is preventing the `filterable-list` RequireJS component from initialising, or jQuery is not loaded.
- **Check:** Open the browser console and look for JavaScript errors. Confirm that `Moogento_Sitemap::js/filterable-list.js` is included in the page source.
- **Resolution:** Resolve any JS conflicts reported in the console. If running on a custom theme that does not load jQuery, add jQuery as a dependency. On Hyvä, the compat module handles the Alpine.js-based equivalent - ensure `Hyva_MoogentoSitemap` is enabled.

---

## FAQs

<!-- seo: FAQPage schema - the page converter should emit JSON-LD for this section -->

## How do I add a sitemap link to my store's footer?

Go to Stores > Configuration > Moogento > Sitemap > General and set **Add: Sitemap link to footer** to Yes, then save and flush your cache. The link appears automatically in the footer on Luma, Porto, and Hyvä storefronts.

## How do I include CMS pages in the sitemap?

Set **Include: Specific CMS pages** to Yes, then select the pages you want from the **Filter: CMS pages** multi-select that appears. Only active pages are listed, and pages like the 404 or cookie policy are excluded automatically.

## Why are some categories missing from my sitemap?

The most common reason is that **Hide: Empty categories** is set to Yes and those categories have no active, visible products. Check your category status in the Magento catalog and either add products or set **Hide: Empty categories** to No if you want all categories displayed.

## How do I add external links or partner URLs to the sitemap?

Enable **Include: Additional links**, then enter one link per line in the **Links** field using the format `https://example.com/,Link label`. Add a bare `<h2>Section heading</h2>` line above a group of links to create a labelled section. See [Common setups - Add custom links](#add-custom-links-and-section-headings) for the full format.

## What happens if I disable Sitemap?

Disabling the module (setting **Enable: Sitemap** to No) makes the sitemap page return a 404 and hides the footer link. No store data is deleted. Re-enabling it restores the page immediately after a cache flush.

## Is Sitemap compatible with Hyvä, Luma, and Porto?

Yes. Luma and Porto use the standard layout and Luma stylesheet. Hyvä requires the companion `Hyva_MoogentoSitemap` compatibility module, which replaces the Luma CSS with Tailwind-scoped styles and provides an Alpine.js-aware footer link block.

## Does the sitemap search slow down the page?

No. The search is entirely client-side JavaScript - it filters already-rendered links without making any server requests. The only performance consideration is the initial page load, which depends on the number of categories and products rendered. For large catalogs, disable **Show: products** to keep load times short.

## How much does Sitemap cost and which plan do I need?

Sitemap is a standalone plugin purchased through **https://www.moogento.com**. Visit the pricing page on the site for current pricing - no subscription tier is required; it is a one-time purchase per domain.

## Can I add styled text to custom link labels?

Yes. Wrap anchor text in `<em>…</em>` for italics or `<b>…</b>` for bold. Tags outside the allowed set (`<em>`, `<b>`, `<span>`, `<br>`, `<h2>`, `<strong>`, `<ul>`) are stripped automatically before rendering.

## Where is the sitemap page URL?

The sitemap page is always at `/sitemap/index/index` relative to your store base URL. You can link to it from any CMS block, page, or menu using that path.

---

## Related guides

- **SmartCategories** - manages category display rules and sorting; pairs with Sitemap if you want the category tree in the sitemap to reflect SmartCategories visibility rules
- **NoMoreSpam Pro** - spam protection for your store's forms; no direct integration with Sitemap

---

## Need help?

- moo@moogento.com
- Include:
  - Magento version
  - Module name
  - What you're trying to do