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

Breadcrumbs navigation is an indispensable user experience and SEO element for a website, which can clearly indicate the user's position within the site and provide convenient return paths.When you are using AnQiCMS, if you find that the breadcrumb navigation does not display as expected or an error occurs, it can indeed be a headache.As an experienced website operation expert, I will thoroughly explain how to systematically troubleshoot based on the powerful functions and template system of AnQiCMS.

AnQiCMS based on Go language development, known for its efficient and flexible template engine, and has borrowed a lot of syntax from Django templates.This means that the display of breadcrumb navigation is often closely related to the correct use of template tags, the transmission of data context, and system configuration.

一、Understand the working principle of AnQiCMS breadcrumb navigation.

In AnQiCMS, the implementation of breadcrumb navigation mainly relies on the built-in breadcrumbTemplate tag. This tag is intended to automatically obtain the hierarchical information of the current page and organize it into a list that can be rendered by the template. Usually, you will find it in the public fragments of template files (such aspartial/header.htmlorpartial/breadcrumb.htmlfor referencedesign-director.mdThe template directory agreement is called by this tag.

{% breadcrumb crumbs with index="首页" title=true %}It is a typical calling method. It returns an array object namedcrumbsEach element containsName(link name) andLinkauto two fields. The template goes through this loopcrumbsArray, output the breadcrumb path one by one. Therefore, any configuration or code issues at any stage may cause the breadcrumb navigation to be abnormal.

Step 2: Systematic troubleshooting steps

Next, we will start from several key aspects and investigate each possible cause that may lead to the breadcrumbs navigation not displaying or displaying incorrectly.

1. Check the invocation and rendering of template tags

Firstly, the most direct point of investigation is your template code. Please check the template file containing breadcrumb navigation carefully to ensure.breadcrumbThe tags are called and rendered correctly.

  • Is the tag syntax correct?Confirm you are using{% breadcrumb crumbs with ... %}this kind of tag format, not other variants. Go template engine is case-sensitive, please ensurebreadcrumb/crumbs/index/titlethe spelling and case of parameters such astag-breadcrumb.mdare in accordance with the specifications in the document.
  • Loop body is complete and correct?Breadcrumbs datacrumbsIt is an array, need to pass through{% for item in crumbs %}Loop to iterate over and output each breadcrumb item. Please check if the loop inside is used correctly.{{item.Name}}to display the name, as well as{{item.Link}}to generate the link. If the loop body is incorrect, it may cause the data to be unable to be normally parsed or displayed.
  • Does the parameter configuration meet the expectations? breadcrumbtag supportindex(custom home page name),title(Whether to display the current page title) andsiteId(Multiple site IDs) and other parameters. If you want the "Home" page to display as "Website Home Page", you need to set theindexparameter settings"网站主页".titleparameter to be configured 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.

The breadcrumb navigation of AnQiCMS is automatically constructed based on the type of the current page (article, category, single page, etc.) and its hierarchical relationship.If the data on the page itself has a problem, the breadcrumbs cannot be generated correctly naturally.

  • Is the content of the current page existing?Make sure the page (article, category, or single page) you are visiting exists in the background and is published.
  • 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) Please check the article (help-content-archive.md）Categories（help-content-category.md) or the single page (help-source-page.mdThe backend editing interface, make sure the title, custom URL (alias) and other key information have been filled in correctly.
  • Is the hierarchical relationship of categories clear?For articles and category pages, the breadcrumb will trace back to the level of the category it belongs to.If a category is deleted, not published, or its parent-child relationship is confused, the breadcrumb path will be interrupted.Please check the completeness and logic of the category tree in "Content Management" -> "Document Categories".

3. Check for rules of pseudo-static and URL generation

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 to work or point to incorrect addresses.

  • Are the pseudo-static rules correctly configured?In the "Feature Management" -> "URL Rewrite Rules", check whether the current URL rewrite rules you are using match your website structure. 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.
  • Whether the custom URL alias conflicts?If multiple pages (articles, categories, single pages) use the same custom URL alias, or if the alias does not meet the specifications, the system may automatically add a random number suffix to ensure uniqueness. This may cause the breadcrumb links to be different from what you expect.

4. Clean system cache

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

  • 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, refer tohelp-index.md），Click to clear all cache. This is a 'panacea' for solving many front-end display exceptions. Please refresh the page after clearing to view the effect.

5. Check the template file and encoding

Breadcrumbs navigation usually exists as a reusable code snippet. If the template file itself has a problem, it will also affect the display.

  • Does the template file exist?Confirmpartial/Does the template fragment file containing breadcrumb navigation exist in the directory (or a custom path you specify), for examplebreadcrumb.html.
  • Template file encoding is UTF-8?Based ondesign-convention.mdThe agreement, all template files must use UTF-8 encoding. If the encoding is incorrect, it may cause the page to display garbled text, which can affect the normal parsing of tags.

6. In a 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