Highlighter Debugging

Purpose: Confirming a Highlighter template and its Highlights are deploying is a crucial first step when troubleshooting issues. This document describes processes fir confirming that markup generated by a Highlighter template is present on a page and loads within an acceptable timeframe.

Resources:

• Schema App: Highlighter
• Schema Markup Validator
• Rich Results Test
• Dev Tools in Chrome or equivalent (CTRL + Shift + "i") or (right click + "Inspect Page")

TABLE OF CONTENTS

• Finding your Deployed Markup
  • Option 1. Use Google's Testing Tools
  • Option 2. Search for ld+json
  • Option 3. Use Console
• If you cannot Find your Deployed Markup
• If the Markup you find is not Expected
  • Markup not Displaying Correctly
  • Highlight Failing to Show Up on your Page
• Tag List Highlights
  • Taglist XPath is Missing Content
• Content is Appearing Outdated

The first step in debugging a Highlighter issue is to determine if there is any markup deploying on the page at all.

Confirm Markup is Deploying

Option 1. Use Google's Testing Tools

The first step is to test your page online via one of Google's structured data testers. This will tell you what markup a search engine bot will see on your page when Google indexes your site.

Option 2. Search for ld+json

If the testing tools show now data (this is common with slower pages), check if the JSON-LD is deploying in your site's DOM. The best way to do this is go to your page in Chrome, right-click and select "Inspect." In the elements tab search for 'ld+json' and see if there is markup with the same schema type that you have specified in the Highlighter.

Option 3. Use Console

Following this, if you're still not seeing any markup, look at how highlight.js is evaluating the page. Right-click the page, select "Inspect". Go to the "Console" tab, paste in the following, and hit the enter key:

window.schema_highlighter_instance.applyTemplate('', false, (result) => { console.log(result) });

{
    failedHighlights: {}, // broken down by template any highlights that could not be resolved
    templatesMatched: [], // The ids of templates matched on the page
    results: [] // All the JSON-LD produced by the highlighter.
}

window.schema_highlighter_instance;

If you cannot Find your Deployed Markup

    If the previous step failed to print anything, printed an error, or printed "undefined":

1. Make sure that highlight.js is loading on the page (should see it in the sources tab of the inspect panel under cdn.schemaapp.com)
2. Make sure that highlight.js is present in the rendered HTML of the Rich Results Test or Schema Validator results for that page.

    If highlight.js is not showing a matching template:

1. Check that your template is published and sufficient time has been given for the template to deploy (5-10 minutes)
2. Check that the XPath or URL in the page set matches the page you are testing for markup on

If you've tried the above and the markup still isn't showing after waiting 24hrs and refreshing the page a few times, this is a bug and a ticket should be logged with [email protected].

If the Markup you find is not Expected

Markup not Displaying Correctly

If markup isn't displaying how you think it should be, take a couple minutes to review all the highlights you've made and confirm that the page layout matches the page you are trying to deploy to. Pay close attention to any highlights that were listed in the 'failedHighlights' section when you printed the contents of highlight.js above. Also note that the deployment to a page from the Highlighter is not instant and it may take some time and a couple page refreshes to see new markup or markup changes appear.

Highlight Failing to Show Up on your Page

Pop open the inspect panel again by right-clicking the page and selecting "Inspect". With this panel you can see the structure of the page as it is rendered. It's possible that with active JavaScrpt, some of the document has mutated and the XPath won't match. 

Find the desired element in the HTML of the page. Right-click the element and select "Copy" > "Copy XPath".

highlight.js runs the following command to evaluate XPaths. You can write this command in the Console to confirm it matches what you expect it to. 

var res = document.evaluate('[XPATH HERE]', document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE);

A real example from: https://www.greenroadsworld.com/collections/cbd-oil-pets/

var res = document.evaluate('//div[@class="w-tabs-sections-h"]/div', document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE);

Now you can check a few things, if you type "res" in the console and hit enter it will give you a preview of the result:

XPathResult {resultType: 7, invalidIteratorState: false, snapshotLength: 8}

The snapshotLength being greater than 0 means the xpath evaluated to something! If it's 0, the xpath did not resolve. 

To view the items that were found you can call the following function: 

res.snapshotItem(0);

Outputs:

<div class="w-tabs-section" id="1520500634883-8d5b1a32-a91a"><a href="#1520500634883-8d5b1a32-a91a" class="w-tabs-section-header"><div class="w-tabs-section-header-h"><h3 class="w-tabs-section-title">How is the CBD we give our pets different than the CBD humans take?</h3><div class="w-tabs-section-control"></div></div></a><div class="w-tabs-section-content" style="display: none;"><div class="w-tabs-section-content-h i-cf">

    <div class="wpb_text_column ">

        <div class="wpb_wrapper">

            <p>The CBD is the same. However, the concentrations and other ingredients aside from CBD are different. Green Roads pet formulas are blended with MCT oil, which is easy for your pet to digest. The pet formulas have CBD concentrations that are more appropriate to the size of your pet’s body.</p>



        </div>

    </div>

</div></div></div>

Note that if the snapshotLength is greater than 1, all of the matches will be joined together as a single value so be sure it reflects what you expect to appear. To see the next item, just add 1 to the number passed in, i.e.:

res.snapshotItem(1);
res.snapshotItem(2);
res.snapshotItem(3);
...

Tag List Highlights

Tag lists highlights use the same basic command as above but also combine the results of another XPath as the context to search for the next path. In the example above we used "document" which means the entire page. Using the same example above, it will iterate through all 8 elements and try to resolve the tag list highlights for each of those 8 results. 

var res = document.evaluate('//div[@class="w-tabs-sections-h"]/div', document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE);

var tagListHighlight = document.evaluate('.//p', res.snapshotItem(0), null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE);

tagListHighlight.snapshotItem(0);

It will repeat this same code for all 8 items that exist in "res" in a loop, and for each of those 8 elements it will create a separate object that all tag list highlights attach to. Results from these are considered independent from each other, so if the structure varies between the 8 results you may not get all XPaths matching for each tag list item. 

This is the actual data that is found via that xpath. If a snapshot item does not appear, look at the HTML and see if the structure differs from your xpath. 

<p>The CBD is the same. However, the concentrations and other ingredients aside from CBD are different. Green Roads pet formulas are blended with MCT oil, which is easy for your pet to digest. The pet formulas have CBD concentrations that are more appropriate to the size of your pet’s body.</p>

This is a trial and error process but will allow you to test your XPaths the same way the Highlighter does so you can confirm that your fix will work the first time. 

Taglist XPath is Missing Content

This is common when the items selected by the taglist XPath contain subtle differences. In this case, it's best to try using relative XPaths. Do this by finding a class that is common, or maybe there is only one paragraph tag, or header. 

<div class="w-tabs-section" id="1520500634883-8d5b1a32-a91a"><a href="#1520500634883-8d5b1a32-a91a" class="w-tabs-section-header"><div class="w-tabs-section-header-h"><h3 class="w-tabs-section-title">How is the CBD we give our pets different than the CBD humans take?</h3><div class="w-tabs-section-control"></div></div></a><div class="w-tabs-section-content" style="display: none;"><div class="w-tabs-section-content-h i-cf">

    <div class="wpb_text_column ">

        <div class="wpb_wrapper">

            <p>The CBD is the same. However, the concentrations and other ingredients aside from CBD are different. Green Roads pet formulas are blended with MCT oil, which is easy for your pet to digest. The pet formulas have CBD concentrations that are more appropriate to the size of your pet’s body.</p>



        </div>

    </div>

</div></div></div>

vs

<div class="w-tabs-section" id="1520500634883-8d5b1a32-a91a"><a href="#1520500634883-8d5b1a32-a91a" class="w-tabs-section-header"><div class="w-tabs-section-header-h"><h3 class="w-tabs-section-title">How is the CBD we give our pets different than the CBD humans take?</h3><div class="w-tabs-section-control"></div></div></a><div class="w-tabs-section-content" style="display: none;"><div class="w-tabs-section-content-h i-cf">

    <div class="wpb_text_column ">

        <a href="#"> <!-- LINK is different here -->

            <p>The CBD is the same. However, the concentrations and other ingredients aside from CBD are different. Green Roads pet formulas are blended with MCT oil, which is easy for your pet to digest. The pet formulas have CBD concentrations that are more appropriate to the size of your pet’s body.</p>



        </a>

    </div>

</div></div></div>

So if the previous XPath was `div/div/div/p` it would not match the second example because an <a> element doesn't match the expected pattern. However, we really only want the paragraph anyway, so write an XPath like the following: 

.//p -- Skip the other nonsense and get me the paragraph!

The '.' means start from this context and we need that because tag lists are very dependent on the context.

'//' means anything in between. 

Finally, 'p' is what we want. 

If the structure varies a lot, things can get very complicated, but you can start to string together XPaths using the "|" symbol which acts as an "or" function. For example: '( div/div/p | div/a/p )'. This will let the Highlighter try multiple options to select an item. Generally, it's rare to have to do this, so exhaust all other options first. 

Content is Appearing Outdated

This happens when debugging locally. If you have just made changes in the highlighter tool and have previously been to the page on the website it is likely your browser has cached the configuration (this is expected and ensures our solution impacts page loads minimally). To work around this you load the page with the webinspector (CTRL+SHIFT+I) open like below (with the cache disabled in the network tab) When you reload the page again it should grab the most recent copy and ignore the cached value.

The other option you have is to right click on the reload button in your browser and choose "Empty cache and hard reload". You will also need to have the web inspector open to view this.