Troubleshooting Cross-Linking Issues

Symptoms:

• Keyword exists in the content but no link is generated
• Page renders normally without any cross-links

Solution:

1. Verify the module is enabled in General → Enabled
2. Verify the entity type is enabled (e.g., Products → Enable for Products)
3. Check that the cross-link rule is Active and the keyword is correct
4. Confirm the rule's Store Views includes the store you're viewing
5. Flush all caches: bin/magento cache:flush
6. Enable debug mode and check var/log/debug.log for messages

Prevention:

• Always flush cache after making configuration or rule changes
• Double-check store view assignments when creating rules

Symptoms:

• Cross-links work on product pages and CMS pages, but not on the Hyva default homepage
• Content rendered by .phtml templates doesn't get cross-links

Solution: This is expected behavior, not a bug. The module replaces keywords in content that passes through Magento's CMS template filter:

• Product descriptions (rendered via Magento\Catalog\Helper\Output)
• Category descriptions (rendered via Magento\Catalog\Helper\Output)
• CMS page and block content (rendered via Magento\Cms\Model\Template\Filter)

Content hardcoded in .phtml templates (like the Hyva default homepage hero section) does not pass through these filters and cannot be processed.

Workaround:

• Move content from .phtml templates into CMS blocks or CMS pages
• Use CMS block widgets in your layout XML instead of hardcoded templates

Symptoms:

• A keyword is replaced more times than expected
• A keyword is only replaced once when you expected more

Solution:

1. Check the rule's Max Replacements setting — this limits replacements per keyword per page
2. Check the entity type's Max Links Per Page setting — this limits total links across all rules
3. A Max Replacements of 0 means unlimited (up to the page-level max)
4. Remember that higher-priority rules consume the page-level limit first

Prevention:

• Set clear max replacements per rule (1 is recommended for most cases)
• Set reasonable page-level limits (5-10 for most pages)

Symptoms:

• Rule for "yoga mats" exists but "yoga" gets linked instead
• Shorter keyword takes precedence over longer, more specific one

Solution:

1. Set higher priority on the longer/more specific keyword
2. The module processes rules by priority DESC, then keyword length DESC
3. "yoga mats" with priority 10 will match before "yoga" with priority 5
4. With equal priority, longer keywords match first automatically

Prevention:

• Always give longer, more specific keywords equal or higher priority than shorter ones
• Review rule priorities when adding new keywords that overlap with existing ones

Symptoms:

• Link is inserted inside an attribute value
• Page layout breaks after enabling cross-links

Solution: The module uses word boundary matching and skips content inside HTML tags and existing <a> tags. If you're seeing broken HTML:

1. Check if the keyword appears in an unusual context (e.g., inside inline JavaScript or CSS)
2. Verify the content doesn't have malformed HTML that confuses the parser
3. Disable the rule temporarily and check if the page renders correctly

Prevention:

• Avoid keywords that commonly appear in code or attribute values
• Use multi-word keywords instead of single generic words

Symptoms:

• Changed settings but the page still shows old behavior

Solution:

1. Flush full page cache: bin/magento cache:flush full_page
2. Flush block HTML cache: bin/magento cache:flush block_html
3. Or flush all caches: bin/magento cache:flush
4. Hard-refresh your browser (Ctrl+Shift+R / Cmd+Shift+R)

Prevention:

• Always flush cache after any configuration change
• Remember that Varnish or CDN caches may also need purging

Symptoms:

• Links appear on the default store but not on a secondary store view
• Same keyword works for one store but is ignored on another

Solution:

1. Check the rule's Store Views setting — it may be assigned to specific stores
2. Verify the entity type is enabled for the affected store view (configuration is per-store)
3. Check that the content actually contains the keyword on the other store (translated content won't match English keywords)
4. Flush cache for all store views: bin/magento cache:flush

Prevention:

• Use "All Store Views" for universal rules (brand names, product codes)
• Create separate rules per store view for translated keywords
• Use the CLI preview command with --store-id to test per-store:

bin/magento magmodules:crosslinking:preview --entity-type=product --entity-id=42 --store-id=2

Symptoms:

• Cross-links were working before but stopped after updating the module
• No error messages in logs

Solution:

1. Run bin/magento setup:upgrade to apply any database changes
2. Run bin/magento setup:di:compile to regenerate dependency injection
3. Flush all caches: bin/magento cache:flush
4. Verify configuration — new versions may add settings that need to be configured (e.g., per-entity-type enable toggles)

Prevention:

• Always run setup:upgrade after updating any Magento module
• Check the CHANGELOG for breaking changes before updating

Navigate to: Stores → Configuration → Magmodules → Cross-Linking → Debug & Logging

Set Debug Mode to Yes and save.

Debug logs: var/log/debug.log Error logs: var/log/error.log

When debug mode is enabled, the module logs:

• Which keywords were replaced and how many times
• Which store view the replacement occurred on
• Any errors loading cross-link rules

Example log entry:

[Replacer] Replaced "yoga" 1 time(s) in store 1

If you don't see any log entries when visiting a page with matching keywords, the module's filter is not being triggered for that content type.

Use the built-in self-test at Debug & Logging → Self-Test to check:

• Module enabled status
• PHP version compatibility
• Magento version compatibility