在 AnQiCMS 的模板中引用和显示外部静态资源，如 CSS 样式表和 JavaScript 脚本，是构建功能完善、视觉美观网站的关键步骤。了解其工作原理和推荐的做法，能让我们的网站开发工作更加高效和灵活。

静态资源存放位置

在使用 AnQiCMS 构建网站时，样式表（CSS）、JavaScript 脚本（JS）以及图片等静态文件是构成网站视觉和交互体验不可或缺的部分。AnQiCMS 对这些静态资源的组织有清晰的约定：所有的静态文件都应该存放在您的 AnQiCMS 安装目录下的 /public/static/ 文件夹中。

例如，如果您的 CSS 文件名为 style.css，您会将其放置在 /public/static/css/style.css。同样，JavaScript 文件如 script.js 则可能位于 /public/static/js/script.js。这个 /public/static/ 目录在您的网站部署后，会通过 Web 服务器（如 Nginx 或 Apache）直接映射到您的网站根目录下，这意味着它们可以直接通过 URL 访问。

在模板中引用本地静态资源

当您需要将这些本地存储的静态资源引入到 AnQiCMS 的模板中时，系统提供了一个非常便捷的标签来帮助我们动态生成正确的路径，那就是 TemplateUrl。这个 TemplateUrl 标签会根据您网站的配置，自动获取模板文件所在的根路径，确保您的资源链接始终是正确的，无论您的网站部署在哪个子目录或子域名下。

引用 CSS 样式表：

要引用一个 CSS 文件，通常在模板的 <head> 区域内使用 <link> 标签，并结合 {% system with name="TemplateUrl" %} 标签来构建路径。

假设您的 CSS 文件在 /public/static/css/main.css，在模板中可以这样写：

<link rel="stylesheet" href="{% system with name="TemplateUrl" %}/static/css/main.css">

这里，{% system with name="TemplateUrl" %} 会被替换为您的模板根目录的 URL，然后加上 /static/css/main.css 即可指向您的样式文件。

引用 JavaScript 脚本：

类似地，引入 JavaScript 文件通常在 <head> 或 <body> 结束标签前使用 <script> 标签。

如果您的 JS 文件在 /public/static/js/app.js，模板引用方式如下：

<script src="{% system with name="TemplateUrl" %}/static/js/app.js"></script>

如果您希望在模板代码中直接构建更复杂的 URL，也可以先将 TemplateUrl 赋值给一个变量再使用，例如：

{% system templateUrl with name="TemplateUrl" %}
<link href="{{ templateUrl }}/static/css/style.css" rel="stylesheet">

引用外部 CDN 静态资源

除了本地资源，我们常常也会使用外部 CDN（内容分发网络）提供的静态资源，例如一些流行的前端框架（如 Bootstrap、jQuery）或特定的库文件。

引用 CDN 资源则更为直接，因为它们通常提供完整的 URL 地址。您只需将这些 URL 直接放入 <link> 或 <script> 标签中即可。

例如，要引入一个 GitHub Markdown 样式表，您可以这样操作：

<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" />

引入 MathJax 或 Mermaid 等 JavaScript 库也遵循相同的模式：

<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

一些实用的小技巧

  • 合理组织文件： 为了保持项目整洁，建议在 /public/static/ 目录下创建 css、js、images 等子文件夹，并根据功能或模块进一步细分，例如 css/pages/home.css 或 js/modules/slider.js。
  • 处理缓存问题： 在开发或更新静态资源后，有时浏览器可能会因为缓存而显示旧版本。除了清除浏览器缓存外，您也可以通过在资源链接后添加版本号或时间戳来强制浏览器重新