AnQiCMS Template Inheritance Secrets:{% extends %}Does the blank line before the tag really affect the child template?

In website content operation and development, efficiency and maintainability are our core pursuits.AnQiCMS (AnQiCMS) is a powerful assistant for many small and medium-sized enterprises and content operation teams, with its high-performance architecture based on the Go language and flexible template system.The Anqi CMS adopts syntax similar to Django template engine, making template creation both powerful and easy to use.Among them, template inheritance (Template Inheritance) is undoubtedly a powerful tool for improving development efficiency and ensuring consistency in the site style.

However, when using this powerful feature, a seemingly insignificant detail often confuses developers: in sub-templates,{% extends %}If a blank line or any other content appears before the label, will it affect the normal inheritance of the template? Put it straightforwardly:Yes, it will have a very significant impact!

Understanding AnQiCMS's template inheritance mechanism

Let's briefly review the working principle of template inheritance in AnQiCMS.Imagine that your website has a unified layout including header, footer, sidebar, and other fixed elements, with only the content area in the middle changing according to different pages.This is where template inheritance comes into play.

We will create a "master" or "skeleton" template (usually namedbase.html），in this template define the overall structure of the website, and use{% block 块名 %}{% endblock %}such tags to mark those areas that can be overridden or extended by child templates.

For example, a basic onebase.htmlit might look like this:

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>{% block title %}我的AnQiCMS网站{% endblock %}</title>
    <link rel="stylesheet" href="/public/static/css/style.css">
</head>
<body>
    <header>{% include 'partial/header.html' %}</header>
    <main>
        {% block content %}
            <!-- 这里是默认内容，子模板可以覆盖 -->
        {% endblock %}
    </main>
    <footer>{% include 'partial/footer.html' %}</footer>
</body>
</html>

Then, the child template can be used{% extends 'base.html' %}to 'inherit' this master, and then fill in or override the definitions in the master according to its own needsblockArea. For example, a sub-template for an article detail page might be written like this: 

{% extends 'base.html' %}

{% block title %}文章标题 - 我的AnQiCMS网站{% endblock %}

{% block content %}
    <h1>{{ archive.Title }}</h1>
    <div class="article-body">{{ archive.Content|safe }}</div>
{% endblock %}

This mechanism greatly improves the reusability of templates, reduces duplicate code, and also keeps the visual style and structure of the website highly consistent.

Core rules:{% extends %}It must be the first tag

Now, let's return to the question at the beginning of our article. According to the explicit instructions of the AnQiCMS official template development document, there is a golden rule that must be strictly adhered to:

“Note: If you use it in a template,{% extends %}the tag must be the first tag in the template. In any other case, template inheritance will not work.”

This means, in the sub-template file,{% extends '母版文件名' %}This line of code must be the first line of the file, and there should be no content before it, including seemingly harmless blank lines, spaces, tabs, or even HTML comments.

Why is there such a rule?

This is a convention in the design of the template engine. When AnQiCMS's template parser reads a file, it expects to see something at the very beginning of the file.{% extends %}Label, used to identify that this is a child template inherited from another template. If the parser reads{% extends %}If it encounters any other character (even invisible whitespace), it will consider this file as an independent, non-inherited template file and ignore it.{% extends %}The label's instruction causes the template inheritance mechanism to fail.

Error example (❌):

{# 这是一个空行，或者任何其他内容 #}
{% extends 'base.html' %}

{% block content %}
    <h1>文章标题</h1>
{% endblock %}

In the above code,{% extends 'base.html' %}A blank line before the label will directly cause the template inheritance to fail. The child template will not be loaded correctly.base.htmlstructure.

Correct example (✅):

{% extends 'base.html' %}

{% block content %}
    <h1>文章标题</h1>
{% endblock %}

Only when{% extends %}AnQiCMS can correctly parse and execute template inheritance only when the tag is the first visible content of the file.

Not just empty lines: any 'extra' content will break inheritance

Please note that the 'blank line' mentioned here does not refer to carriage return specifically. Any{% extends %}characters that appear before the tag, including:

  • Spaces or tabs:Even several invisible spaces will be recognized as content by the template engine.
  • HTML comments:For example<!-- 这是注释 -->It is also content.
  • Other template tags:Any other{% ... %}or{{ ... }}Label.
  • Any text content:Even just some plain text.

This "extra" content will{% extends %}The label is no longer the first item in the file, thus breaking template inheritance. Possible consequences may include child templates failing to render correctly, blank page display, and even system errors in some cases.

Suggestions and practices in actual operation

As a content operator or developer of AnQiCMS, to avoid such problems, we have some suggestions:

  1. Develop the habit of:When creating a sub-template file, please make sure to put{% extends '母版文件路径' %}the label on the first line of the file, with no characters before or after it. This is the simplest and most effective preventive measure.
  2. Check the beginning of the file carefully:If you encounter an issue with template inheritance not working, the first step is to check the first line of the child template file. You can confirm this by using the 'Show whitespace characters' feature in a text editor (such as VS Code, Sublime Text), or by directly viewing the page source.{% extends %}Is it really at the beginning of the file.
  3. Use the automatic formatting feature of the editor:Many modern code editors have automatic formatting features, but be careful, as these features might add some whitespace characters at the beginning of the file without you noticing.Suggested to manually check the file header after saving.
  4. Use wisely-Remove blank lines:AnQiCMS template engine also provides-The symbol to control the blank lines around the label (refer)tag-remove.md). For example,{%- if condition %}or{{ variable -%}}.But please note that this feature is used to controlLabel internal logicorData outputThe blank lines generated, rather than used to solve{% extends %}The label must be a rigid requirement on the first line of the file.For{% extends %}The rule is rigid: it must be at the very beginning and have no adornments.

Summary

In AnQiCMS template development,{% extends %}Any blank lines or content before the label will directly cause the template inheritance to fail.This is not a Bug, but a strict specification made by the template engine to ensure parsing efficiency and structural consistency.Master this core rule and develop good coding habits, which will help you use the powerful template features of AnQiCMS more smoothly and efficiently, and build stable and elegant websites.

Common Questions (FAQ)

Q1: If{% extends %}What if there are HTML comments before the label? Will it also be invalid?

A1:Will do. AnQiCMS template engine in parsing{% extends %}Tags, when present, will strictly check whether it is the first "visible" content in the file. Even HTML comments are not considered whitespace by the template engine, and they will prevent{% extends %}Identified as the first label, causing inheritance failure. Remember,Any non-empty characteris not allowed to appear before it.

Q2: Why does AnQiCMS have such strict regulations? Are other template engines like this?

A2：This strictness is usually to ensure the efficiency and consistency of template parsing. Template