How to troubleshoot when AnQiCMS breadcrumb navigation does not display or displays incorrectly?

Breadcrumbs navigation is an indispensable user experience and SEO element of a website, which can clearly indicate the user's position in the website and provide a convenient return path.When you are using AnQiCMS and find that the breadcrumb navigation does not display as expected or an error occurs, it can indeed be a headache.As an experienced website operations expert, I will give you a detailed explanation of how to systematically troubleshoot based on the powerful functions and template mechanism of AnQiCMS.

AnQiCMS is developed in Go language, known for its efficient and flexible template engine, and has borrowed a lot from Django template syntax.This often relates to the correct use of template tags, the passing of data context, and system configuration, whether the breadcrumb navigation is displayed or not.

Understand the working principle of AnQiCMS breadcrumb navigation

The implementation of breadcrumb navigation in AnQiCMS mainly relies on built-inbreadcrumbTemplate tag. This tag is designed to automatically obtain the hierarchical information of the current page and organize it into a list that can be rendered by the template. Typically, you will find it in the common segments of the template file (such aspartial/header.htmlorpartial/breadcrumb.htmlfor referencedesign-director.mdThe template creation directory convention is called this tag.

{% breadcrumb crumbs with index="首页" title=true %}It is a typical calling method. It will return an array object namedcrumbsEach element containsName(link name) andLink(Link address) two fields. The template loops through thiscrumbsArrays, to output the breadcrumb path one by one. Therefore, any configuration or code problem at any link may lead to an abnormal navigation of breadcrumbs.

2, Systematic troubleshooting steps

Next, we will start from several key aspects and investigate one by one the reasons that may cause the breadcrumb navigation not to display or display incorrectly.

1. Check the calling and rendering of template tags.

First, the most direct point of investigation is your template code. Please check the template file containing breadcrumb navigation to ensurebreadcrumbthe label is called and rendered correctly.

  • is the syntax of the label correct?Confirm that you are using{% breadcrumb crumbs with ... %}such label format, not other variants. The Go template engine is case-sensitive, make surebreadcrumb/crumbs/index/titlethe spelling and case of the parameters are completely consistent withtag-breadcrumb.mdthe specifications in the document.
  • Is the loop body complete and correct?Breadcrumbs datacrumbsIt is an array, it needs to be passed through{% for item in crumbs %}Loop to traverse and output each breadcrumb item. Please check if the loop inside is used correctly.{{item.Name}}To display the name as well{{item.Link}}To generate a link. If the loop body is incorrect, it may cause the data to be unable to be normally parsed or displayed.
  • Is the parameter configuration as expected? breadcrumbTag supportindex(Custom home page name),title(Whether to display the current page title) andsiteIdParameters such as (multiple site IDs). If you want the 'home page' to display as 'website homepage', you need to setindexthe parameter to"网站主页".titleparameters according to your needs.trueorfalseEven custom display text. Incorrect parameter configuration may lead to missing or incorrect display of some content.

2. Verify the integrity and relevance of page data.

AnQiCMS's breadcrumb navigation is automatically built based on the current page type (article, category, single page, etc.) and its hierarchical relationship.If the data on the page itself is problematic, the breadcrumbs will naturally not be generated correctly.

  • Does the content on the current page exist?Ensure that the page (article, category, or single page) you are visiting exists in the background and is published.
  • The page title and URL alias are filled in completely?The text of the breadcrumb navigation usually comes from the page title (Title) or URL alias (filename/catname) Check the article (help-content-archive.md）、Category（help-content-category.md) or single page (help-source-page.mdThe backend editing interface, make sure that the title, custom URL (alias), and other key information have been filled in correctly.
  • Is the classification hierarchy clear?For articles and category pages, the breadcrumbs will trace back to the level of the category they belong to.If a category is deleted, not published, or its parent category relationship is confused, the breadcrumb path will be interrupted.Please check the completeness and logicality of the category tree under "Content Management" –> "Document Categories".

3. Check for static rule issues and URL generation problems

AnQiCMS supports flexible pseudo-static rule configuration, which directly affects the generation of page links.If the URL structure is incorrect, the links in the breadcrumb navigation may also fail or point to the wrong address.

  • Are the static rules correctly configured?In the "Feature Management" -> "SEO Rules" section, check if the SEO rules you are currently using match the structure of your website. Pay special attention to the rules in{filename}/{catname}/{module}The correct use of variables, which determine the composition of the URL. Refer tohelp-plugin-rewrite.md.
  • Is there a conflict with the custom URL alias?If multiple pages (articles, categories, single pages) use the same custom URL alias, or the alias does not meet the specifications, the system may automatically add a random number suffix to ensure uniqueness, which may cause the breadcrumb links to be different from what you expect.

4. Clean system cache

AnQiCMS to improve access speed, it will enable the cache mechanism.After you modify the website configuration, template file, or page content, if the breadcrumb navigation does not update in time, it is likely a cache-related problem.

  • Manually update cache:In AnQiCMS backend, find the "Update Cache" feature (usually located at the bottom of the left menu or in the "Backend Settings" area, see the referencehelp-index.mdClick to clear all cache. This is a universal solution for many front-end display anomalies. Please refresh the page after clearing to view the effect.

5. Check the template file and encoding

Breadcrumb navigation usually exists as a reusable code snippet. If there is a problem with the template file it is in, it will also affect the display.

  • Does the template file exist?Confirmpartial/Does the directory (or the custom path you specified) contain a breadcrumb navigation template fragment file, for example?breadcrumb.html.
  • Is the encoding of the template file UTF-8?Based ondesign-convention.mdThe convention, all template files must use UTF-8 encoding. If the encoding is incorrect, it may cause page garbled and affect the normal parsing of tags.

6. Under the multi-site environment.siteIdConfiguration

If you are using the multi-site feature of AnQiCMS and the breadcrumb navigation is having an issue on a specific site, then `site