企业官网建设流程全解析

在 ESLint 文档站点中使用 Alert 组件：warning、tip 与 important 三种提示的 Shortcode 完全指南

【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint

ESLint 官方文档站点（docs/src/library/alert.md）内置了一套轻量级Alert（提示框）组件，用于在 Markdown 页面中插入三种不同语义的提示：警告（warning）、提示（tip）与重要说明（important）。本文以该组件文档为骨架，结合站点源码中的 Nunjucks 宏实现、SCSS 样式与真实使用场景，完整讲解三种 Alert 的语法、参数、渲染效果与自定义方式，帮助你为 ESLint 文档或基于该站点的组件库贡献高可读性的提示内容。

三种 Alert 类型总览

Alert 组件在视觉与语义上分为三种固定类型，分别对应不同的内容场景：

从站点样式实现（alert.scss）可以看到，每种类型都拥有独立的配色变量，彼此在页面上通过颜色即可区分，且全部支持深色主题适配。

Usage：三种 Shortcode 的调用语法

Alert 组件的使用方式是通过shortcode（短代码）在 Markdown 正文中直接嵌入。每种类型都有对应的一个 shortcode，语法统一为：

{% warning "text", "/link/to/learn/more" %} {% tip "text", "/link/to/learn/more" %} {% important "text", "/link/to/learn/more" %}

调用时需提供两个位置参数：

1. text：提示正文，用双引号包裹的字符串；
2. url：Learn more（了解更多）链接的目标地址，同样用双引号包裹。

原文档给出的完整示例：

{ % warning "This rule has been removed in version x.xx", "/link/to/learn/more" % } { % tip "Kind reminder to do something maybe", "/link/to/learn/more" % } { % important "This rule has been deprecated in version x.xx", "/link/to/learn/more" % }

渲染结果示例

站点文档中的实际渲染效果如下（原文档 alert.md 的 Examples 章节）：

{% warning "warning text", "/" %} {% tip "tip text", "/" %} {% important "text", "/" %}

三个 shortcode 会分别渲染为带图标、类型标签与Learn more链接的提示框。其中url传/表示链接指向站点首页，实际编写时请替换为目标文档的相对路径（如指向具体规则的链接）。

深入源码：Alert 的 Nunjucks 宏实现

shortcode 背后是由站点使用的 Nunjucks 模板引擎的macro（宏）实现，定义于 alert.macro.html。三个宏的结构完全一致，均输出语义化的<aside role="note">提示框，这里以warning为例：

{%- macro warning(params) -%} <aside role="note" class="alert alert--warning"> <svg class="alert__icon" aria-hidden="true" focusable="false" width="19" height="20" viewBox="0 0 19 20" fill="none"> <!-- 警告图标 path --> </svg> <div class="alert__content"> <span class="alert__type">Warning</span> <div class="alert__text">{{ params.text }}</div> <a href="{{ params.url }}" class="alert__learn-more">Learn more</a> </div> </aside> {%- endmacro -%}

从源码可以提炼出 Alert 组件的渲染结构：

• 容器：<aside role="note">，使用role="note"向辅助技术（屏幕阅读器）声明这是一个补充性说明区域，而非正文核心内容；
• 图标：内联 SVG，aria-hidden="true"且focusable="false"，图标仅作视觉装饰，不干扰读屏；
• 类型标签：<span class="alert__type">，显示Warning/Tip/Important文本；
• 正文：<div class="alert__text">，即 shortcode 传入的text参数；
• 了解更多链接：<a class="alert__learn-more">，即 shortcode 传入的url参数，固定文案为Learn more。

三种类型只是类名与 SVG 图标不同：warning使用圆形感叹号图标，important使用三角形警示图标，tip使用带对勾的灯泡图标（源码见 alert.macro.html）。

宏的导入与调用方式

当需要在一个模板中直接使用 Alert 组件（而非通过 Markdown shortcode）时，通过 Nunjucks 的 import 语句引入，例如文档页布局 doc.html 中的写法：

{% from 'components/alert.macro.html' import important %}

随后即可在模板中调用：{% important text, url %}。这与 Markdown 中的 shortcode 语法相互对应——shortcode 本质上是将 Markdown 中的参数透传给同名宏进行渲染。

实际应用场景：规则文档中的弃用提示

Alert 组件在站点中最具代表性的应用，是规则文档页顶部自动生成的“已弃用”提示。在 doc.html 中，当某条规则被标记为弃用（rule_meta.deprecated）时，站点会调用：

{% important deprecated_description, rule_meta.deprecated.url %}

即把规则元数据中预置的弃用说明文本与“了解更多”链接地址，作为important宏的两个参数渲染成重要提示框，并附带替换规则的指引文案（如“请使用 xxx 规则替代”）。这展示了 Alert 组件在真实页面中的典型用法：给读者发出强语义信号，并引导跳转到详细说明页面。

因此，在为 ESLint 仓库编写或修改规则文档时，若规则涉及移除、弃用等变更，可以在 rules 目录 对应文档中直接使用warning/importantshortcode，向读者明确传达变更信息。

样式与主题适配

Alert 组件的视觉样式由 alert.scss 定义，核心规则如下：

• 布局：采用 CSS Grid 双列布局（grid-template-columns: auto 1fr），左侧图标列、右侧内容列，align-items: start保证内容较多时图标不拉伸；
• 边框与圆角：border: 1px solid currentColor使边框跟随文本色，圆角使用站点统一的--border-radius变量；
• 配色变量：背景与文字颜色通过语义化 CSS 变量注入，例如--alert-warning-background-color、--alert-important-color、--alert-tip-heading-color等；
• 深色主题：在[data-theme="dark"]选择器下，.alert__learn-more会切换为更亮的浅色系（如--color-rose-200），保证深色背景下的可读性；
• 间距规范：提示框底部留有1.5rem外边距（margin-block-end），与正文段落间距保持一致。

配色变量的具体取值定义在 themes.scss 中：亮色主题下tip使用绿色系（success）、important使用琥珀色系（warning）、warning使用玫红色系（rose）；深色主题则统一加深背景、提亮文字，形成完整的两套色板。

在组件库页面中的定位

Alert 是站点**组件库（Component Library）**中的一员，与按钮（buttons.md）、代码块（code-blocks.md）、代码页签（code-tabs.md）等组件并列于 library 目录。组件库页面通过 library.json 配置渲染：页面使用components.html布局，最终输出路径为/component-library/{{ page.fileSlug }}.html，即每个组件文档会生成独立的静态页面供站内查阅与复用。

这意味着 Alert 不仅服务于规则文档，也面向站点维护者与贡献者，作为一套统一、可复用的提示 UI 规范沉淀在组件库中。

小结

• 三种语义类型：warning（警告）、tip（提示）、important（重要说明）；
• 统一参数签名：{% 类型 "正文文本", "了解更多链接URL" %}；
• 底层实现为 alert.macro.html 中的 Nunjucks 宏，输出语义化<aside role="note">结构，内置 SVG 图标、类型标签与Learn more链接；
• 样式由 alert.scss 与 themes.scss 中的语义化变量驱动，开箱支持深色主题；
• 站内已用于规则文档的弃用提示（见 doc.html），是编写 ESLint 文档时传递重要信息的标准姿势。

当你在 ESLint 文档中需要强调规则变更、给出使用建议或标记弃用信息时，直接选用对应类型的 Alert shortcode，即可获得风格统一、语义清晰且无障碍友好的提示效果。

【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint