How to reference static resources (such as CSS/JS/images) in Anqi CMS template to beautify content display?

In content operation, the aesthetics of the website and user experience are crucial, and this largely depends on the reasonable referencing and management of static resources (such as CSS stylesheets, JavaScript scripts, and images).For users of AnQiCMS, mastering how to efficiently and规范ly reference these resources in templates is a key step in building high-quality websites.

The AnQi CMS has fully considered the management of static resources in its design, providing a set of clear conventions and convenient template tags to enable developers to easily achieve visual beautification and interactive enhancement of content.

AnQiCMS Static Resources Storage Agreement

Firstly, understanding the static resource storage structure of Anqi CMS is fundamental. According to the system convention, the styles, JavaScript scripts, images, and other static resources used by the templates are all uniformly stored on the site./public/static/Under the directory. When you create or modify a set of templates, you usually will/templateUnder the directory, a dedicated folder for your templates will be created (for exampledefault），while all the static resources (CSS, JS, images, etc.) of this template will be placed in/public/static/your_template_name/In such a structure. This separation helps to maintain the purity of the template file, and it also facilitates the efficient processing and caching of static files by the server.

Core: How to reference static resources in templates

In the template files of Anqi CMS, we can make use of the system-providedSystemLabel to dynamically obtain the static file address of the current template, thereby realizing flexible resource reference. This key variable is{{ System.TemplateUrl }}It will be parsed as the URL path of the static resource directory corresponding to the currently enabled template.

1. Refer to the CSS stylesheet

CSS files are responsible for the layout and visual style of the website. In a template, referencing CSS is usually done in the.<head>use a control character inside<link>.

For example, if your template has a static resources directory with a file namedcss/style.cssThe style file, you can refer to it like this:

<link rel="stylesheet" href="{{ System.TemplateUrl }}/css/style.css">

This method ensures that the CSS path is correctly resolved regardless of which domain or subdirectory the website is deployed to.

2. Reference JavaScript script

JavaScript files are used to implement interactive features of the page. They are typically in<body>Label closing before reference to avoid blocking page rendering.

If there is a file namedjs/script.jsin your template static resource directory, you can reference it like this:

<script src="{{ System.TemplateUrl }}/js/script.js"></script>

Sometimes, you may need to execute some scripts immediately when the page loads, or reference some external libraries, and you can also place them in<head>tags, but be aware of the performance impact.

3. Reference Image

Images are an indispensable part of the website content, they may be decorative images built into the template, or content images uploaded by users through the backend.

  • Template default images:For images stored in the template static resource directory, for exampleimg/logo.png, you can directly access through{{ System.TemplateUrl }}to refer:

    <img src="{{ System.TemplateUrl }}/img/logo.png" alt="网站Logo">

  • User uploaded images:[User uploaded images on the backend, for example as document thumbnails or images within the content, whose paths are usually dynamically generated by the system and are not stored directly in the static resource directory of the template, but are located]/uploads/In the directory. In the template, you can directly access the image path variables, for example:

    <img src="{{ archive.Logo }}" alt="{{ archive.Title }}">

    Herearchive.Logowill output the complete image URL. The Anqi CMS also providesthumbFilter that can generate thumbnails of images according to system settings, which helps optimize loading speed:

    <img src="{{ archive.Logo|thumb }}" alt="{{ archive.Title }}">

    If the document content contains images and lazy loading is enabled,archiveDetailTags also supportlazyParameters, convenient for integrating front-end lazy loading libraries.

4. Refer to external static resources (CDN)

In addition to locally hosted static resources, we sometimes also use third-party CDNs (Content Delivery Networks) to reference some public libraries or frameworks, such as jQuery, Bootstrap, font icons, etc.In this case, since the resource is not on your AnQiCMS server, you only need to use the complete URL provided by the CDN directly in the template.

For example, refer to an external CSS file from CDN:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css">

Reference an external JavaScript file from a CDN:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js"></script>

For rendering mathematical formulas and flowcharts in Markdown editors, the document also mentions that it can be achieved by introducing external scripts such as MathJax and Mermaid through CDN.

Some practical tips and注意事项

  • Path normalization:Always use{{ System.TemplateUrl }}To refer to the built-in static resources of the template, this ensures the universality of the path, even if the website changes its domain name or is deployed in a subdirectory, no manual modification of the template code is required.
  • Resource organization:Under your template static resource directory, it is recommended to create subfolders based on resource types, such ascss//js//img/Keep the file structure clear, which is convenient for management and maintenance.
  • Browser cache:After modifying CSS or JS files, the page may not take effect immediately. This may be due to browser caching. You can try clearing the browser cache or appending a version number to the resource URL (for example?v=1.0.0or timestamp) to force the browser to load the latest file.
  • AnQiCMS Cache:In addition to browser caching, AnQiCMS itself may also have a caching mechanism.After modifying templates or system configurations in the background, if the front-end page does not update in time, you can try to clear the system cache by using the "Clear Cache" feature in the background.
  • Performance optimization:Compress CSS and JavaScript files as much as possible, merge small CSS/JS files to reduce HTTP requests.For images, choosing the appropriate format (such as WebP) and size, and considering the use of lazy loading technology, can significantly improve page loading speed.

By following these principles and techniques, you can effectively manage and reference static resources in the AnQiCMS template, thereby creating a website that is both beautiful and efficient.

Common Questions (FAQ)

  1. Why did the front-end page not take effect after I modified the CSS or JS files in the template?

    • Answer:This is usually caused by browser caching. Your browser may still be loading old versions of styles or scripts. You can try clearing your browser cache or pressingCtrl + F5[en] (Windows)Cmd + Shift + RPerform a forced refresh (Mac). Additionally, if AnQiCMS has enabled system caching, you may also need to log in to the admin backend and clear the system cache in the 'Update Cache' feature.

  2. Question: How should I organize static resources in my template to facilitate management?

    • Answer:It is strongly recommended that you organize the static resources in your template-specific directory (for example,/public/static/your_template_name/Underneath, create subfolders based on resource type. For example, there can becss/to store all style sheets,js/to store all JavaScript scripts,img/Store all images. This not only makes the file structure clear at a glance, but also helps with team collaboration and subsequent maintenance.

  3. Question: Can I put all static resources on a CDN? Does AnQiCMS support it?

    • Answer:AnQiCMS itself does not provide direct CDN integration functionality (i.e., it will not automatically push your local static files to CDN), but of course, you can manually upload your theme CSS, JS, and image static files to a CDN service provider. Once the files are on CDN, you just need to use the complete URL provided by CDN to reference these resources in the template, instead of using{{ System.TemplateUrl }}This method helps improve the global access speed and concurrent carrying capacity of the website.