How to reference static resources (such as CSS/JS/images) in AnQi CMS template to beautify content display?
In content operation, the aesthetics and user experience of the website are crucial, and this largely depends on the reasonable reference 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 a high-quality website.
AnQi CMS has taken full consideration of the management of static resources, providing a clear set of conventions and convenient template tags, allowing developers to easily realize the visual beauty and interaction enhancement of content.
AnQiCMS Static Resource 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 template are all uniformly stored on the site./public/static/Under the directory. When you create or modify a set of templates, you usually will/templateCreate a dedicated folder for your template under the directory, for exampledefault), and all the static resources (CSS, JS, images, etc.) will be placed in/public/static/your_template_name/This structure. This separation helps maintain the purity of the template file, and also facilitates the efficient processing and caching of static files by the server.
Core: How to reference static resources in the template
In the Anqi CMS template files, we can use the system providedSystemThe label is used to dynamically obtain the static file address of the current template, thereby realizing the flexible reference of resources. 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. CSS is usually referenced in templates.<head>Use within tags<link>elements.
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 can be correctly resolved regardless of the domain or subdirectory where the website is deployed.
2. Reference JavaScript script
JavaScript files are used to implement page interactions. They are usually in<body>Referencing before closing the tag to avoid blocking page rendering.
If there is a script file named under your template's static resource directory namedjs/script.jsYou can refer to 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 refer to some external libraries, in which case you can also place them inside<head>tags, but be aware of the performance impact.
3. Reference Image
Images are an indispensable part of website content, they may be decorative images from the template itself, or content images uploaded by users through the backend.
Default image provided by the template:For images stored in the template's static resource directory, for example:
img/logo.pngYou can directly go through{{ System.TemplateUrl }}to refer:<img src="{{ System.TemplateUrl }}/img/logo.png" alt="网站Logo">User uploaded images:Images uploaded by users on the backend, for example as document thumbnails or images in the content, the path is usually dynamically generated by the system and is not directly stored in the static resource directory of the template, but located in
/uploads/In the directory. You can directly obtain the path to these images through the corresponding variables in the template, for example:<img src="{{ archive.Logo }}" alt="{{ archive.Title }}">Here
archive.LogoIt will directly output the complete image URL. Anqi CMS also providesthumbA filter that can generate thumbnails of images according to the system settings, which helps to 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 just 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 implementing it by introducing external scripts like MathJax and Mermaid through CDN.
Some practical tips and precautions
- Path normalization:Always use
{{ System.TemplateUrl }}To reference the static resources included in the template, this ensures the universality of the path, even if the website changes the domain name or is deployed in a subdirectory, there is no need to manually modify the template code. - Resource organization:Under your template static resource directory, it is recommended to create subfolders according to the type of resources, such as
css//js//img/etc., to maintain a clear file structure for easy management and maintenance. - Browser Caching:After modifying CSS or JS files, the page may not take effect immediately, which may be due to browser caching. You can try clearing the browser cache or adding 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 cache, AnQiCMS may also have its own caching mechanism.After modifying the template or system configuration in the background, if the front-end page does not update in time, you can try to clear the system cache in the "Update 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.
Frequently Asked Questions (FAQ)
Ask: Why did the front page not take effect after I modified the CSS or JS files in the template?
- Answer:This is usually due to browser caching. Your browser may still be loading old versions of styles or scripts. You can try clearing your browser cache or pressing
Ctrl + F5(Windows)/Cmd + Shift + R(Mac) Perform a forced refresh. Additionally, if AnQiCMS has enabled system caching, you may also need to log in to the backend and clear the system cache in the "Update Cache" feature.
- Answer:This is usually due to browser caching. Your browser may still be loading old versions of styles or scripts. You can try clearing your browser cache or pressing
Ask: How should I organize my template static resources to facilitate management?
- Answer:It is strongly recommended that you organize the static resources directory exclusive to your template (for example
/public/static/your_template_name/Under, create subfolders according to the resource type. For example, there can becss/Store all style sheets,js/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.
- Answer:It is strongly recommended that you organize the static resources directory exclusive to your template (for example
Ask: Can I put all static resources on CDN? Does AnQiCMS support it?
- Answer:AnQiCMS itself does not provide 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 provider. Once the files are on CDN, you simply need to use the complete URL provided by CDN to reference these resources in the template, rather than using
{{ System.TemplateUrl }}This approach helps to improve the global access speed and concurrent carrying capacity of the website.
- Answer:AnQiCMS itself does not provide 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 provider. Once the files are on CDN, you simply need to use the complete URL provided by CDN to reference these resources in the template, rather than using