How to include external static resource files (CSS, JS, images) in a template?
When building a website using AnQiCMS, it is the basis of website aesthetics and functional realization to introduce static resources such as styles (CSS), interactive scripts (JS), and images for the page.Understand how to correctly introduce these files in the template, so that your website can not only look professional, but also be rich in features and maintain high efficiency and stable operation.AnQi CMS, with its concise and efficient architecture and flexible template engine, makes management and introduction of these resources very intuitive.
The AnQiCMS template system is very considerate, especially in handling static resources. It follows a clear set of conventions, allowing you to easily organize and call various files.
Understand the storage location of static resources
In AnQiCMS, all template files are stored in/templateUnder the directory, while the style sheets, JavaScript scripts, and images related to the template and other static resources have a dedicated location:/public/static/Directory. This is the default and recommended location for storing static resources.
For example, you can in/public/static/Create the following subdirectories under the directory to organize your resources:
/public/static/css/Used to store all your CSS files./public/static/js/Store all your JavaScript files./public/static/images/Store all your image files.
This structure helps to keep the file system tidy and convenient for the system to manage and load.
Introduce local static resources in the template
When your static resource files are stored in the above/public/static/When in the directory, AnQiCMS provides a named{{system.TemplateUrl}}The special variable, it will automatically resolve to the directory path of the static resources corresponding to the template used by the current website.Use this variable to build the URL for static resources, which is crucial to ensure that your website can load resources correctly in any environment (such as changing domain names, switching templates, or multi-site deployment).
1. Introduce CSS stylesheet:CSS files are usually placed in the HTML document's<head>Area to ensure that the style is applied as soon as the page is loaded.
<head>
<meta charset="UTF-8">
<title>{% tdk with name="Title" siteName=true %}</title>
<!-- 引入您的自定义CSS样式 -->
<link rel="stylesheet" href="{{system.TemplateUrl}}/css/style.css">
</head>
here,{{system.TemplateUrl}}Will automatically be replaced with similarhttp://您的域名/public/static/您的模板目录名Such a path, and then the system will loadstyle.cssfile.
2. Introduce JavaScript script:JavaScript files are generally recommended to be placed<body>The closing tag of the tag</body>earlier, which can avoid script blocking the page rendering and improve user experience.
<body>
<!-- 页面内容 -->
<!-- 引入您的自定义JavaScript脚本 -->
<script src="{{system.TemplateUrl}}/js/main.js"></script>
<script src="{{system.TemplateUrl}}/js/another-script.js"></script>
</body>
similar to CSS,{{system.TemplateUrl}}Ensured the correct path of the JS file.
3. Introduce the image file:Image files can be introduced in the HTML's<img>tags directly, or as CSS background images.
<body>
<!-- 作为img标签引入 -->
<img src="{{system.TemplateUrl}}/images/logo.png" alt="网站Logo">
<!-- 如果是作为CSS背景图，在CSS文件中可以这样写（假设CSS文件在{{system.TemplateUrl}}/css/中） -->
<!-- .hero-section {
background-image: url('../images/background.jpg');
} -->
</body>
In the CSS file, if the image path is fixed relative to the CSS file, you can use a relative path. However, for images in HTML, it is recommended to use{{system.TemplateUrl}}To maintain the dynamic adaptability of the path.
Introduce external CDN static resources in the template.
In addition to local resources, you can also introduce external static resources stored in a content delivery network (CDN).CDN can accelerate resource loading, alleviate server pressure, and is particularly suitable for scenarios where website users are widely distributed.
1. Introduce CSS styles from the external CDN:For example, you may need to introduce an external Markdown style library to beautify your content.
<head>
<!-- 引入外部CDN的CSS样式 -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.2.0/github-markdown.min.css" crossorigin="anonymous" referrerpolicy="no-referrer" />
</head>
2. Introduce the external CDN JavaScript script:Similarly, it is a common practice to directly include some commonly used JS libraries or specific features (such as formula rendering, flowchart libraries, etc.) from CDN.
<body>
<!-- 引入外部CDN的JavaScript脚本 -->
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
</body>
3. Introduce external CDN images:When your images are stored on a third-party image service or CDN, you can directly reference their complete URL.
<body>
<img src="https://your-image-cdn.com/path/to/product-image.webp" alt="产品图片">
</body>
Template integration and **practice
To manage the static resources of the website more efficiently, it is recommended that you centrally manage the code that introduces static resources. In the template structure of AnQiCMS, there is usually onebase.htmlfile, as the basic skeleton for all pages. You can define the page in it.<head>and<body>structure, and introduce common CSS and JS files.
- introduce centrally:Place the common CSS inclusion code in
base.htmlof<head>inside, place the common JS inclusion code inbase.htmlof</body>the tag before. - Modular reference:For CSS/JS needed only for specific pages or modules, consider locally including in the corresponding template file or using AnQiCMS's
{% include "partial/header.html" %}Tags for auxiliary labeling, split the head or tail segment out, convenient for maintenance. - Performance optimization:
- CSS first, JS after:Ensure that CSS files are loaded at the top of HTML and JS files at the bottom to optimize page rendering speed.
- Merge and compress: For multiple small CSS or JS files, merging and compressing before deployment can reduce the number of HTTP requests and file size.Although AnQiCMS itself does not have built-in these features, you can use external tools or build processes to complete them.
- Image optimization:Make sure the image is compressed and the appropriate size is processed. AnQiCMS supports Webp format conversion and automatic compression of large images in the background content settings, which is a good way to optimize images.
By following these simple rules and practices, you can easily and efficiently introduce various static resources in the AnQiCMS template, creating an excellent user experience and powerful features for your website.
Frequently Asked Questions (FAQ)
1. Why to use{{system.TemplateUrl}}Introduce local static resources instead of writing directly/public/static/template_name/...?Use{{system.TemplateUrl}}It is because it can provide stronger flexibility and compatibility. When the domain name of your website changes, or when different templates are configured for different sites in the multi-site management function of AnQiCMS, or even when the name of the template directory is updated, {{system.TemplateUrl}}It will automatically adapt to these changes, ensuring that the path of static resources is always correct.If the path is hardcoded, once these configurations change, you will need to manually modify all template files, which is very inconvenient.
2. Besides/public/static/Where can I put my static resources in AnQiCMS?AnQiCMS will provide by default./public/Access to all files in the directory. Therefore, theoretically you will place static resources in/public/Any location in the directory, and it can be accessed throughhttp://您的域名/文件名或路径Accessed directly. However, to maintain good organization and maintainability, it is strongly recommended to place all static resources related to the template/public/static/in the directory and use{{system.TemplateUrl}}Reference is made, which helps to distinguish between which are public resources at the AnQiCMS system level and which are resources of your custom template.
3. What built-in optimization features does AnQiCMS have when introducing a large number of images?Yes, AnQiCMS provides practical built-in image optimization features. You can find the related options in the background of"Backend settings" -> "Content settings". For example, you can chooseWhether to enable Webp image formatAutomatically convert uploaded JPG, PNG images to a smaller Webp format, as well as"Should large images be automatically compressed"Specify the compression width to effectively reduce the size of image files and speed up page loading. These features can help you automatically optimize images when uploading, without manual processing.