Breadcrumb navigation code converter

You probably got the news. Google announced that it would stop supporting markup for the breadcrumb feature in its search results. The deadline is April 6, 2020. If you still use the old schema and want to keep your pages appearing at Google's adorned with a neat navigation trail, it's time for some breadcrumb update. Read on!

Renovation tools—time for a change

You may want to rotate your phone in order to improve your browsing experience on this site.

Quick links

What is breadcrumb navigation?

Breadcrumb navigation is a simple way of showing your web visitors "You are here". At the same time, it provides a nice overview of how the current page fits into your site structure and a handy means of traversing the latter — all in one place.

Breadcrumb trail exampleBreadcrumb navigation on a sample web page

To make it work for the visitor doesn't require it to conform to any rules. A string of connected links is all a human needs to grasp it.

This is different with a crawling algorithm. For it, to understand that a series of links defines a navigation trail requires a special format to designate them as such.

The breadcrumb markup is this designation. If done correctly, it enables the Google crawler to interpret it and include it in search result listings.

Breadcrumb trail in Google SERPGoogle search results featuring the same breadcrumb trail

Admittedly, Google takes the liberty to modify your original markup for use on its SERPs, as with everything else there.

Thus, your top tier item is rendered like the default URL from your site property in Google Search Console, not like you designed it.

Also, only items with links in the original code feature in page snippets.

Finally, the navigation trail itself is lost, as the entire structure links solely to the featured page.

Still, this is a nice touch hinting at what your site is about and what else there is to find, hopefully helping to get the click.

Now, with the aforementioned announcement, Google changes the rules of recognizing the breadcrumb markup by its crawler. In order to ensure the navigation trail will appear in Google search results in the future, it has to conform to the new schema rules.

Leaving it be?

Let's make it clear, you don't have to act. If you leave your existing markup as is, your visitors — obviously — will still be able to use it. Your pages won't disappear from Google search results either.

The only consequence will be the loss of the navigation trail in your pages' listings. If you can live with it, you will save a significant amount of time, depending on your site size, by ignoring the issue.

However, if you find the feature helpful and intend using it in the future, you need to act.

Dealing with it

Depending on your configuration, you might face a fair amount of work. This is very much the case If you have to attend to every page by hand.

Below is a simple helper tool to convert your outdated breadcrumb navigation code online. All you need to do is copy and paste your old markup into the box, choose appropriate settings and click the arrow button.

The utility will then try to analyze your existing HTML and transform it into the up-to-date markup.

You can get started right away or scroll down for explanations first. Hard choice! 😉

How it works

Mechanical watch movement detail

In general, the utility inserts your old breadcrumb navigation code into a div on this page, then tries (hard) to transform it in place and populates the output box with the resulting HTML. The latter can then be selected and copied, ready for pasting into your HTML or online template editor. 

Step by step: Input

The input markup is expected to represent one breadcrumb trail, that is, consist of several span elements belonging together and conforming to the rules, optionally enclosed by one container element like <p> or <div>.

The script in the background will analyze the provided markup looking for distinctive elements and attributes of schema and trying to convert them into new corresponding elements and attributes as defined by the rules.

All other tags included with your input will be left mostly untouched, or that's the idea. Since your HTML will be inserted for treatment into this very page, it will be parsed beforehand and stripped of any possibly dangerous parts. So, please be nice and restrain from including them.

Available options

There are five settings you can use to affect tool's behaviour. All of them are disabled by default.

Update breadcrumb links to HTTPS will transform your old link URLs from HTTP to HTTPS. (Your site is sure HTTPS by now, isn't it?) This is safe to set just in case, to catch any stray links which are still HTTP.

Of course, do not activate this option if your site isn't HTTPS yet.

The setting only makes sense, and has effect, for absolute URLs (those which start with http://).

Generate link to current page. If you are like me, your last breadcrumb in the trail aiming at the current page isn't styled as a link. After all, it doesn't make much sense to provide a link to the page the visitor is already on!

There are, however, some reasons for using the link. For one thing, when placed at the bottom of the page, the link could double as the back-to-top shortcut. This could be of use to humans, too.

Then, as mentioned — and illustrated — above, Google ignores unlinked breadcrumb items when presenting its search results.

Third, more often than not, plain text is styled and displays differently from links.

If any of this bothers you, you can select the option to generate a link to top of the current page in a breadcrumb where there is none. Setting it will make no difference for breadcrumbs already in use as links.

Remove outer container element. You can opt for this choice if you had your navigation trail enclosed by another element which wasn't used for anything other than being that, a container, and you included it in your input.

According to the new schema definition, the breadcrumb list will appear as a single <ol> (ordered list) tag. This is a block element which can be styled on its own and doesn't need an extra container.

The option is also useful in case you had the breadcrumbs two levels below their "real" parent, e.g., inside a paragraph (for grouping) within a div (for styling). The paragraph will become redundant in the new scheme of things and can go.

If you don't include a container in your input, the option will have no effect.

Remove breadcrumb separators, when set, will result in a trail without white space between the items. This may sound strange at first but is, in fact, quite reasonable.

There is no need including the same piece of text over and over again, after every breadcrumb item, when all of them can be generated by a single CSS rule defined in one place.

My breadcrumbs are styled this way. The huge advantage is, you can change the separator character(s) on a whim within seconds to something completely different, for all breadcrumbs, at once.

Imagine having to do this on every page by hand!

Don't format output HTML will deliver transformed HTML in one long line, without breaks and added white space. This might be advisable when the simple formatting routine included in the utility doesn't live up to the task and delivers suboptimal results for your input. It will then be skipped during the process.

Transformation process

Just for the record and without delving into much detail, here's how the transformation algorithm works.

  • Your old breadcrumb navigation markup is parsed and stripped of white space and active content, e.g., scripts.
  • The routine tries to identify plain text with a specific role in the old markup, like breadcrumb separators and non-linked navigation items.
  • The trimmed HTML is then injected in two divs on this page, the first one serving as "before" display, the other one reserved for "after" comparison.
  • The second div is transformed in place to comply with the new schema, its resulting markup is fetched from the browser, formatted and streamed into the output box.

Known issues

The tool isn't sophisticated enough to handle every possible input. It won't:

  • Create something which isn't there. If your code does not conform to the rules, the handling script will fail.
  • Validate or enhance your markup. Aside from actions and options outlined above, your HTML won't be manipulated.
  • Handle deep HTML layering. If your breadcrumbs are buried inside a deep node hierarchy, items without a link will be missing in the resulting markup. Select your input to include no more than one container around your breadcrumb trail.
  • Transform multiple breadcrumb trails at once. If you have several different navigation trails on a page, please convert them one by one. (Otherwise positions will extend over trail limits to build one sequence.)
  • Convert more than one unlinked breadcrumb item when several are present in the trail, e.g., Home › ChaosChapters › Chapter I.
  • Possibly work on input with a plain text trail item repeated somewhere else inside the trail, e.g., HomePages › My Pages › Page (Unlinked text "Page" is contained in "Pages" and "My Pages". For transformation to work, the "free" text has to be unique within the trail, for example, "Page 1". The script will still try to do its best, but the outcome is uncertain — test if it would work for you.)

Best practice

Screwdrivers and screws

Here is an example of how to work with the utility to get the best out of it in the shortest time.

  • Load a page in need of updating into your HTML or template editor.
  • Find the old breadcrumb navigation code and make sure it complies to the rules.
  • Copy navigation trail items, optionally include their closest container element with its other content. Leave the selection in place ready for later replacement.
  • Paste the clipboard into the input box. Select the desired transformation options. (If this is a repeating process, the two working divs and the output box will go empty before the next round.)
  • Press the arrow button to start the routine.
  • Compare the result with the old look. Check the output for error signs. These could be: the markup is missing, or stays the same, or still features references to data-vocabulary; the position sequence is not consecutive, or is shorter or longer than the number of trail items; the HTML is not well-formed, e.g., misses closing tags, or has other issues…
  • Test the transformed navigation links by opening them in a new tab or window. (This will only work for absolute URLs including your domain name. The generated link to top of the page is not one of those.)
  • If there is an error, try to tweak the input HTML: consult the next section for advice on possible problems. Repeat the process and check again.
  • If everything seems OK, copy the resulting markup and paste it back into your page. (The output box is editable if you want to change anything ad hoc.)
  • Repeat for the next breadcrumb trail on the page.
  • Repeat for the next page.

Working around problems

Most conversion failures can be remedied by correcting the input. For some issues mentioned above there is a clear path to success.

With breadcrumbs sitting inside a deep node structure, plain text items won't be identified and skipped during transformation.
— Make sure your input includes at most one enclosing element. Also, consider removing it during conversion.

Transform multiple breadcrumb trails for the same page one by one.

If the resulting breadcrumb trail looks OK on page but its markup seems incomplete — some missing closing tags at the bottom would be a hint — try to repeat the process without HTML formatting in the end.
— The formatting function is rather limited in its possibilities.

If your input doesn't change at all, look for these possible reasons:

  • Check if the unlinked item's label is part of other trail elements' wording (it shouldn't be).
  • Try to remove white space, empty lines, etc., from the original markup.

If the output box is empty, something went wrong parsing your input. The markup might be malformed, or not conform to the data-vocabulary schema.

If you are at a loss, feel free to use the contact form or comments below for help.

Styling the new markup

Paintbrush and paint

If everything works for you, congratulations! Still, you need to provide a bit of style for your updated breadcrumbs.

The new schema uses ordered lists for its markup. Browsers usually present them one item per line, indented and preceded by a sequence number — this is what "ordered" and "list" imply after all.

Use the following to position the entire trail inline without either indentation or enumeration.

If you are used to working with containers to style their child elements, place your breadcrumb trail inside a div with a dedicated class:

Then style container contents:

If you decided to remove separators from the markup, include another rule to generate them after all trail items but the last one:

Test the rule by clicking the button and checking the effect on the last result. Modify if needed with your favourite character. (Depending on this, you may need to use its hexadecimal value.)

With the styling div around, the rule changes to

Need help? Get in touch!

Please note that all fields followed by an asterisk must be filled in.

In this series

Custom site search with DuckDuckGo
Build your own custom search widget for your website or blog! Use the easy to follow steps to generate its code, and test it on the fly — within minutes.
How to embed YouTube videos
See examples for embedding videos on your website or blog in creative and unusual ways. Learn about player parameters and IFrame Player API. Get ideas and inspiration for your own online projects.

Unattributed images on this page are sourced from public domain via Pixabay.

  1. Home
  2. Web watch
  3. Breadcrumb markup converter

Back to Top

Tell me what you think!

Is it useful 👍? Awful 👎? Leave a message! Your comments help make this site better (and give me a kick—one way or another).

Popular articles

  1. A kind of magic

    If a digital picture has to be seen in the real world, printed on a real medium and displayed in a real showcase, its transition from RAW to real is better done in an old school image editor. Enter A…

    Read on

  2. A duck for a dog

    If you got your own place on the Internet, helping your visitors find what they are looking for is a great way to engage them and keep them staying a bit longer. A custom site search can achieve just …

    Read on

  3. "Might as well have the best"

    Aiming for better images? Think better lenses! This is your most important piece of gear, so you better get it sorted out. — Need some advice?

    Read on

Back to Top

📨 Subscribe!

Featured content