在 ESLint 文档站点中使用 link shortcode 渲染链接卡片【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslintESLint 官方文档站点基于 Eleventy11ty构建其内置的linkshortcode 可以把普通超链接渲染为带站点图标、标题和域名的链接卡片Link Card大幅提升规则文档中外部参考资料的阅读体验。本文以 ESLint 仓库中的 link-card.md 组件文档为主线结合 docs/.eleventy.js 中的 shortcode 实现、further_reading_links.json 元数据源与 resources.scss 样式表完整讲解该组件的用法、工作原理、数据约定与常见报错排查帮助你在自己的 Eleventy 文档站中复刻同样的链接卡片能力。组件定位Docs 组件库中的短代码ESLint 仓库的文档站把常用的渲染能力拆分为一组可复用组件集中登记在 component-library.html 页面中。按该页面说明这些组件包括 shortcode短代码、macro宏和 partial局部模板三类其中绝大多数是供各文档页面直接调用的 shortcode。link卡片正是其中之一与之并列的还有alert、fixable、related_rules等 shortcode各自都有对应的说明文档如 alert.md、related-rules.md、rule-categories.md。组件库文档集中放在docs/src/library/目录下link-card.md 就是该组件的权威用法说明。基础用法一行短代码生成卡片在原文档中链接卡片的用法极为简洁使用linkshortcode唯一必填参数就是希望抓取元数据的 URL。{% link https://thesiteurl.com %}只要传入一个字符串形式的 URL构建站点时就会在对应位置渲染出一张完整的链接卡片。原文档给出了两个实际示例{% link https://blog.izs.me/2010/12/an-open-letter-to-javascript-leaders-regarding/ %} {% link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get %}前者用于引用一篇关于 JavaScript 社区的重要博客文章后者用于引用 MDN 上的 getter 文档——这正是 ESLint 规则文档中进一步阅读Further Reading区块的典型形态将分散在站外的权威资料以统一、美观的卡片形式内嵌到文档页中。注意原文档中这两行示例被!-- markdownlint-disable MD034 --与!-- markdownlint-enable MD034 --注释包裹。MD034 是 markdownlint 的禁用裸链接bare-URL规则因为示例中出现了以...或裸 URL 形式书写的外部地址需要临时关闭该规则以避免 lint 报错。在你自己的 Markdown 文档中编写含裸 URL 的示例时可采用同样的做法。必填参数URL 与元数据抓取原文档明确说明linkshortcode唯一必填参数是 URL。该 URL 有两个用途作为卡片最终跳转的目标链接作为键去站点数据中查找对应的标题、域名与图标等元数据。理解抓取元数据这一说法需要结合实现细节这里的抓取并非构建期实时访问该 URL 去解析网页而是在构建时以该 URL 为键从站点级数据文件 further_reading_links.json 中读取预先人工维护好的元数据。也就是说新增一张卡片时需要同时完成两步在文档里调用 shortcode并把该 URL 的元数据登记进 JSON 数据文件。源码实现shortcode 如何在构建期工作linkshortcode 的定义位于 docs/.eleventy.js通过 Eleventy 的addNunjucksShortcode注册eleventyConfig.addNunjucksShortcode(link, function (url) { // eslint-disable-next-line no-invalid-this -- Eleventy API const urlData this.ctx.further_reading_links[url]; if (!urlData) { throw new Error( Data missing for ${url}. Did you forget to add the URL information to /docs/src/_data/further_reading_links.json?, ); } const { domain, title, logo } urlData; return article classresource div classresource__image img classresource__img width75 height75 src${logo} altAvatar image for ${domain} onerrorthis.onerror null; this.src /icon.svg / /div div classresource__content a href${url} classresource__title ${title} /abr span classresource__domain ${domain}/span /div svg classc-icon resource__icon width13 height12 viewBox0 0 13 12 fillnone path dM1.5 11L11.5 1M11.5 1H1.5M11.5 1V11 strokecurrentColor stroke-width2 stroke-linecapround stroke-linejoinround/ /svg /article; });从实现可以确认以下关键事实数据来源this.ctx.further_reading_links是 Eleventy 注入的全局上下文对应docs/src/_data/目录下的数据文件——凡放置在_data目录中的.json文件都会被 Eleventy 自动加载为全局数据因此 further_reading_links.json 会以further_reading_links为名出现在所有模板的上下文中。按 URL 精确索引shortcode 用传入的 URL 直接作为对象键去取值further_reading_links[url]因此文档中书写的 URL 字符串必须与 JSON 文件中的键完全一致包括协议、大小写、路径否则会命中缺失分支。缺失即报错若找不到元数据构建会直接抛出Error错误信息会提示开发者把该 URL 补充到docs/src/_data/further_reading_links.json。这种fail-fast设计把数据遗漏问题暴露在构建期而不是让页面渲染出残缺卡片。渲染结构卡片由三个部分组成——左侧 75×75 的站点图标resource__image、中间的内容区标题resource__title与域名resource__domain、右侧的外链箭头 SVG 图标resource__icon。图标加载失败时通过onerror回退到站点自身的/icon.svg默认图标。Nunjucks 上下文使用addNunjucksShortcode而非addShortcode是为了在函数体内通过this.ctx访问 Eleventy 全局数据这是该实现的技术前提。元数据数据源further_reading_links.json 的结构链接卡片的所有展示信息集中维护在 further_reading_links.json当前仓库中共 863 行、数十条记录每条记录以完整 URL 为键结构如下{ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get: { domain: developer.mozilla.org, url: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get, logo: https://developer.mozilla.org/favicon-48x48.cbbd161b.png, title: getter - JavaScript | MDN, description: The get syntax binds an object property to a function that will be called when that property is looked up. } }字段含义与对应关系字段说明在卡片中的用途domain站点域名渲染在卡片内容区的域名文本url目标链接与键一致卡片跳转目标logo站点图标 URL渲染为卡片左侧 75×75 的头像图title资源标题渲染为卡片标题可点击description资源摘要当前版本卡片模板未渲染此字段仅作数据留存对照 docs/.eleventy.js 中的解构语句const { domain, title, logo } urlData;可以看出shortcode 实际只消费domain、title、logo三个字段url用于与键保持一致description字段在当前卡片模板中并未输出。这意味着维护数据时这三个字段是卡片正常渲染的必要条件。卡片样式resources.scss 的视觉实现卡片的视觉呈现由独立样式表 resources.scss 定义其结构与 shortcode 输出的 HTML class 一一对应.resource卡片容器使用display: flex水平排布带圆角var(--border-radius)、1px 边框var(--divider-color)和浅色背景margin-bottom: 0.5rem保证多张卡片垂直堆叠时的间距悬停:hover时背景色加深增强可点击感。.resource__image左侧图标区固定 5.5rem 宽度flex: 1 0 5.5rem内部图片object-fit: contain等比缩放、满高显示。.resource__content中间内容区flex: 4占据主要宽度垂直居中内边距 0.75rem。.resource__title标题链接去下划线、使用--headings-color标题色并通过::after伪元素把整个卡片区域都扩展为可点击热区absolute 定位覆盖容器全尺寸。.resource__domain域名文本使用--body-text-color正文色字号 0.875rem。.resource__icon右侧外链箭头 SVG居中放置。样式依赖站点定义的 CSS 变量如--divider-color、--lightest-background-color因此卡片的明暗配色会自动跟随站点的主题切换机制。常见问题与排查思路在实际使用中最容易遇到的场景与对策如下1. 构建报错Data missing for URL这是linkshortcode 最典型的报错触发原因是文档中使用的 URL 没有出现在 further_reading_links.json 中。解决方法把该 URL 及其domain、url、logo、title元数据补充到该 JSON 文件中。注意 JSON 键必须与 shortcode 传入的 URL 字符串逐字符一致。2. 卡片图标空白或显示默认图标logo字段指向的远程图片加载失败时onerror事件会把图片回退为站点根目录的/icon.svg。如果图标地址失效请更新 JSON 中的logo字段。3. 想在页面中渲染多张卡片直接连续调用多个linkshortcode 即可.resource的margin-bottom会自动分隔相邻卡片形成列表式布局。4. 需要引用新站点无需修改 shortcode 或样式只需新增一条 JSON 记录并保证字段完整即可让任意站点的链接以卡片形式展示。在 ESLint 文档站中的实际应用在 ESLint 文档中linkshortcode 主要服务于规则文档页与指南页中的进一步阅读区块把规则原理对应的权威外部资料如 MDN 的 JavaScript 语法参考、社区博客的经典分析文章、相关规范页以统一卡片形式呈现。这也解释了为何 further_reading_links.json 中大量收录了 MDN、Wikipedia、GitHub 风格指南等 JavaScript 生态资料——它们与 lib/rules 下各规则文档中的推荐阅读一一对应。对于希望在自己的 Eleventy 文档站中复刻该能力的开发者核心步骤可归纳为三条在.eleventy.js中注册读取全局数据的 Nunjucks shortcode、把站点元数据集中维护在_data目录的 JSON 文件中、以 Flex 布局编写卡片样式并利用::after扩展点击热区。这套短代码 数据文件 样式表的组合正是 ESLint 文档站组件库见 docs/src/library 与 component-library.html中其他组件的通用设计范式。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 ESLint 文档站点中使用 link shortcode 渲染链接卡片【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslintESLint 官方文档站点基于 Eleventy11ty构建其内置的linkshortcode 可以把普通超链接渲染为带站点图标、标题和域名的链接卡片Link Card大幅提升规则文档中外部参考资料的阅读体验。本文以 ESLint 仓库中的 link-card.md 组件文档为主线结合 docs/.eleventy.js 中的 shortcode 实现、further_reading_links.json 元数据源与 resources.scss 样式表完整讲解该组件的用法、工作原理、数据约定与常见报错排查帮助你在自己的 Eleventy 文档站中复刻同样的链接卡片能力。组件定位Docs 组件库中的短代码ESLint 仓库的文档站把常用的渲染能力拆分为一组可复用组件集中登记在 component-library.html 页面中。按该页面说明这些组件包括 shortcode短代码、macro宏和 partial局部模板三类其中绝大多数是供各文档页面直接调用的 shortcode。link卡片正是其中之一与之并列的还有alert、fixable、related_rules等 shortcode各自都有对应的说明文档如 alert.md、related-rules.md、rule-categories.md。组件库文档集中放在docs/src/library/目录下link-card.md 就是该组件的权威用法说明。基础用法一行短代码生成卡片在原文档中链接卡片的用法极为简洁使用linkshortcode唯一必填参数就是希望抓取元数据的 URL。{% link https://thesiteurl.com %}只要传入一个字符串形式的 URL构建站点时就会在对应位置渲染出一张完整的链接卡片。原文档给出了两个实际示例{% link https://blog.izs.me/2010/12/an-open-letter-to-javascript-leaders-regarding/ %} {% link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get %}前者用于引用一篇关于 JavaScript 社区的重要博客文章后者用于引用 MDN 上的 getter 文档——这正是 ESLint 规则文档中进一步阅读Further Reading区块的典型形态将分散在站外的权威资料以统一、美观的卡片形式内嵌到文档页中。注意原文档中这两行示例被!-- markdownlint-disable MD034 --与!-- markdownlint-enable MD034 --注释包裹。MD034 是 markdownlint 的禁用裸链接bare-URL规则因为示例中出现了以...或裸 URL 形式书写的外部地址需要临时关闭该规则以避免 lint 报错。在你自己的 Markdown 文档中编写含裸 URL 的示例时可采用同样的做法。必填参数URL 与元数据抓取原文档明确说明linkshortcode唯一必填参数是 URL。该 URL 有两个用途作为卡片最终跳转的目标链接作为键去站点数据中查找对应的标题、域名与图标等元数据。理解抓取元数据这一说法需要结合实现细节这里的抓取并非构建期实时访问该 URL 去解析网页而是在构建时以该 URL 为键从站点级数据文件 further_reading_links.json 中读取预先人工维护好的元数据。也就是说新增一张卡片时需要同时完成两步在文档里调用 shortcode并把该 URL 的元数据登记进 JSON 数据文件。源码实现shortcode 如何在构建期工作linkshortcode 的定义位于 docs/.eleventy.js通过 Eleventy 的addNunjucksShortcode注册eleventyConfig.addNunjucksShortcode(link, function (url) { // eslint-disable-next-line no-invalid-this -- Eleventy API const urlData this.ctx.further_reading_links[url]; if (!urlData) { throw new Error( Data missing for ${url}. Did you forget to add the URL information to /docs/src/_data/further_reading_links.json?, ); } const { domain, title, logo } urlData; return article classresource div classresource__image img classresource__img width75 height75 src${logo} altAvatar image for ${domain} onerrorthis.onerror null; this.src /icon.svg / /div div classresource__content a href${url} classresource__title ${title} /abr span classresource__domain ${domain}/span /div svg classc-icon resource__icon width13 height12 viewBox0 0 13 12 fillnone path dM1.5 11L11.5 1M11.5 1H1.5M11.5 1V11 strokecurrentColor stroke-width2 stroke-linecapround stroke-linejoinround/ /svg /article; });从实现可以确认以下关键事实数据来源this.ctx.further_reading_links是 Eleventy 注入的全局上下文对应docs/src/_data/目录下的数据文件——凡放置在_data目录中的.json文件都会被 Eleventy 自动加载为全局数据因此 further_reading_links.json 会以further_reading_links为名出现在所有模板的上下文中。按 URL 精确索引shortcode 用传入的 URL 直接作为对象键去取值further_reading_links[url]因此文档中书写的 URL 字符串必须与 JSON 文件中的键完全一致包括协议、大小写、路径否则会命中缺失分支。缺失即报错若找不到元数据构建会直接抛出Error错误信息会提示开发者把该 URL 补充到docs/src/_data/further_reading_links.json。这种fail-fast设计把数据遗漏问题暴露在构建期而不是让页面渲染出残缺卡片。渲染结构卡片由三个部分组成——左侧 75×75 的站点图标resource__image、中间的内容区标题resource__title与域名resource__domain、右侧的外链箭头 SVG 图标resource__icon。图标加载失败时通过onerror回退到站点自身的/icon.svg默认图标。Nunjucks 上下文使用addNunjucksShortcode而非addShortcode是为了在函数体内通过this.ctx访问 Eleventy 全局数据这是该实现的技术前提。元数据数据源further_reading_links.json 的结构链接卡片的所有展示信息集中维护在 further_reading_links.json当前仓库中共 863 行、数十条记录每条记录以完整 URL 为键结构如下{ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get: { domain: developer.mozilla.org, url: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get, logo: https://developer.mozilla.org/favicon-48x48.cbbd161b.png, title: getter - JavaScript | MDN, description: The get syntax binds an object property to a function that will be called when that property is looked up. } }字段含义与对应关系字段说明在卡片中的用途domain站点域名渲染在卡片内容区的域名文本url目标链接与键一致卡片跳转目标logo站点图标 URL渲染为卡片左侧 75×75 的头像图title资源标题渲染为卡片标题可点击description资源摘要当前版本卡片模板未渲染此字段仅作数据留存对照 docs/.eleventy.js 中的解构语句const { domain, title, logo } urlData;可以看出shortcode 实际只消费domain、title、logo三个字段url用于与键保持一致description字段在当前卡片模板中并未输出。这意味着维护数据时这三个字段是卡片正常渲染的必要条件。卡片样式resources.scss 的视觉实现卡片的视觉呈现由独立样式表 resources.scss 定义其结构与 shortcode 输出的 HTML class 一一对应.resource卡片容器使用display: flex水平排布带圆角var(--border-radius)、1px 边框var(--divider-color)和浅色背景margin-bottom: 0.5rem保证多张卡片垂直堆叠时的间距悬停:hover时背景色加深增强可点击感。.resource__image左侧图标区固定 5.5rem 宽度flex: 1 0 5.5rem内部图片object-fit: contain等比缩放、满高显示。.resource__content中间内容区flex: 4占据主要宽度垂直居中内边距 0.75rem。.resource__title标题链接去下划线、使用--headings-color标题色并通过::after伪元素把整个卡片区域都扩展为可点击热区absolute 定位覆盖容器全尺寸。.resource__domain域名文本使用--body-text-color正文色字号 0.875rem。.resource__icon右侧外链箭头 SVG居中放置。样式依赖站点定义的 CSS 变量如--divider-color、--lightest-background-color因此卡片的明暗配色会自动跟随站点的主题切换机制。常见问题与排查思路在实际使用中最容易遇到的场景与对策如下1. 构建报错Data missing for URL这是linkshortcode 最典型的报错触发原因是文档中使用的 URL 没有出现在 further_reading_links.json 中。解决方法把该 URL 及其domain、url、logo、title元数据补充到该 JSON 文件中。注意 JSON 键必须与 shortcode 传入的 URL 字符串逐字符一致。2. 卡片图标空白或显示默认图标logo字段指向的远程图片加载失败时onerror事件会把图片回退为站点根目录的/icon.svg。如果图标地址失效请更新 JSON 中的logo字段。3. 想在页面中渲染多张卡片直接连续调用多个linkshortcode 即可.resource的margin-bottom会自动分隔相邻卡片形成列表式布局。4. 需要引用新站点无需修改 shortcode 或样式只需新增一条 JSON 记录并保证字段完整即可让任意站点的链接以卡片形式展示。在 ESLint 文档站中的实际应用在 ESLint 文档中linkshortcode 主要服务于规则文档页与指南页中的进一步阅读区块把规则原理对应的权威外部资料如 MDN 的 JavaScript 语法参考、社区博客的经典分析文章、相关规范页以统一卡片形式呈现。这也解释了为何 further_reading_links.json 中大量收录了 MDN、Wikipedia、GitHub 风格指南等 JavaScript 生态资料——它们与 lib/rules 下各规则文档中的推荐阅读一一对应。对于希望在自己的 Eleventy 文档站中复刻该能力的开发者核心步骤可归纳为三条在.eleventy.js中注册读取全局数据的 Nunjucks shortcode、把站点元数据集中维护在_data目录的 JSON 文件中、以 Flex 布局编写卡片样式并利用::after扩展点击热区。这套短代码 数据文件 样式表的组合正是 ESLint 文档站组件库见 docs/src/library 与 component-library.html中其他组件的通用设计范式。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考