al-folio 博客文章 Tabs 标签页实战：基于 jekyll-tabs 的选项卡内容编写指南

al-folio 博客文章 Tabs 标签页实战：基于 jekyll-tabs 的选项卡内容编写指南

【免费下载链接】al-folioA beautiful, simple, clean, and responsive Jekyll theme for academics项目地址: https://gitcode.com/GitHub_Trending/al/al-folio

本文以 al-folio 仓库中的示例文章 _posts/2024-05-01-tabs.md 为骨架，完整讲解如何在 Jekyll 博客文章中通过jekyll-tabs插件生成可切换的选项卡（Tabs）内容，涵盖基础语法、多语言代码对比、数据结构对比、非代码内容等实战场景，并给出该功能在 al-folio 中的依赖配置与启用方式。读完本文，你可以在自己的学术主页文章中轻松组织"同一主题、多种视角"的内容，例如同一算法的 Python / JavaScript / Ruby 实现、同一数据的 YAML 与 JSON 表达，或一段说明、一条引言与一份清单的并列展示。

一、功能定位：al-folio 中的选项卡内容支持

al-folio 本身是一个面向学术工作者的 Jekyll 主题（详见 README.md），博客文章支持丰富的排版扩展。其中的 Tabs（选项卡）功能由第三方 Ruby 插件jekyll-tabs提供，仓库通过 Bundler 将其锁定在 1.2.1 版本（见 Gemfile.lock 中的jekyll-tabs (1.2.1)条目）。

在 al-folio 中，该插件是默认启用的核心排版插件之一：

• Gemfile 的:jekyll_plugins组中声明了gem 'jekyll-tabs'；
• _config.yml 的plugins:列表中登记了- jekyll-tabs，与jekyll-toc（目录）、jekyll-scholar（参考文献）、jekyll-feed（订阅源）等插件并列；
• 项目文档 docs/CUSTOMIZE.md 在插件清单中将其描述为 "Adds tabbed content support"，即"为内容增加选项卡式展示"。

也就是说，只要按标准流程安装依赖（bundle install）并在本地或远程构建（bundle exec jekyll serve预览，详见 docs/INSTALL.md 与 docs/QUICKSTART.md），无需额外配置即可在文章中使用 Tabs。

与许多把选项卡写死在主题模板里的方案不同，jekyll-tabs 的选项卡完全由文章正文中的 Liquid 标签驱动：内容是什么、分几个页签、每个页签叫什么名字，都由作者在 Markdown 里直接声明。这也正是示例文章强调的：Tabs 的用途不限于代码展示，凡是想把"多种表达方式并排呈现"的内容都可以用它组织。

二、基础语法：四个标签的完整骨架

Tabs 的写法非常直观，由四个 Liquid 标签组成。以示例文章中的通用模板为例（原文用{% raw %}包裹以保证模板本身不被渲染，写作时请注意这一转义技巧）：

{% tabs group-name %} {% tab group-name tab-name-1 %} Content 1 {% endtab %} {% tab group-name tab-name-2 %} Content 2 {% endtab %} {% endtabs %}

逐个标签说明其职责：

从源码结构看（插件实现位于 gem 内部，仓库中通过 Gemfile 依赖引入），group-name承担着"组关联"与"页签归属"的双重职责：同一个组内可以放任意多个{% tab %}，而不同组之间互不影响，可以在同一篇文章中并列使用多组 Tabs。

需要特别注意的是：

• 组名与页签名必须写对。{% tab %}的第一个参数若与{% tabs %}声明的组名不一致，页签将无法归属到该组；
• 每个页签内部是独立的 Markdown 上下文，可以放代码块、列表、引用、表格甚至图片，内容之间互不干扰；
• 为了在文章中展示"语法本身"，示例文档使用{% raw %} ... {% endraw %}包裹代码片段，避免 Jekyll 将其当作真正的 Liquid 标签执行——这是撰写此类教程时的常用手法。

三、实战一：多语言代码的并排对比

代码对比是 Tabs 最典型的应用场景。示例文章用一组名为log的选项卡，展示了三种语言输出 "hello" 的方式：

{% tabs log %} {% tab log php %} ```php var_dump('hello');

{% endtab %}

{% tab log js %}

console.log("hello");

{% endtab %}

{% tab log ruby %}

pputs 'hello'

{% endtab %}

{% endtabs %}

渲染效果为三个页签 `php` / `js` / `ruby`，读者点击任一页签即可切换查看对应语言的代码。这样做的好处很明显：同一段逻辑的不同实现被折叠在页签之后，文章正文保持精简，读者按需展开。 > 小提示：原文的 ruby 页签中，代码围栏误写成了 `javascript`，且 `pputs` 疑为 `puts` 的笔误（原样保留于 [_posts/2024-05-01-tabs.md](https://link.gitcode.com/i/e3279c85b3c4faa16467f4d31763ab8a) 中）。实际写作时请确保围栏语言与内容一致，例如 ruby 页签应使用 ` ```ruby ` 围栏——这恰好印证了"页签内容完全由作者控制、插件不做语言校验"的实现特征。 ## 四、实战二：同一数据的不同结构表达 Tabs 也适合用来对比同一份数据的不同序列化格式。示例文章用 `data-struct` 组，将同一个 `hello` 列表分别以 YAML 和 JSON 呈现： ```liquid {% tabs>{ "hello": ["whatsup", "hi"] }

{% endtab %}

{% endtabs %}

这种"一组页签对应同一主题"的写法，在技术博客中尤其适合：接口文档可以对比请求/响应示例，配置教程可以对比不同环境的配置，数据教程可以对比不同格式的等价表达。 ## 五、实战三：非代码内容的自由组合 正如示例文章开篇所强调的——"tabs could be used for different purposes, not only for code"（选项卡可以用于多种目的，不只是代码）。第三组 `something-else` 演示了文本、引用与列表三种非代码内容的组合： ```liquid {% tabs something-else %} {% tab something-else text %} Regular text {% endtab %} {% tab something-else quote %} > A quote {% endtab %} {% tab something-else list %} Hipster list - brunch - fixie - raybans - messenger bag {% endtab %} {% endtabs %}

这一组页签验证了插件的通用性：页签的"面板"中可以是任意 Markdown 块级元素——普通段落、引用块、无序列表，甚至嵌套其他结构。这意味着你完全可以用 Tabs 组织"观点 vs 反方观点"、"摘要 vs 详细版"、"结论 vs 附录"等内容形态，而不必局限于代码。

六、在 al-folio 中启用与配置 Tabs

1. 文章级开关：tabs: true

示例文章的 YAML 前置元数据（front matter）中有这样一行：

--- layout: post title: a post with tabs date: 2024-05-01 00:32:13 description: this is what included tabs in a post could look like tags: formatting code categories: sample-posts tabs: true ---

其中tabs: true是示例文章用于声明"本篇文章启用了 Tabs 展示"的元数据标记。它通常与主题的样式渲染逻辑配合，确保页面加载相应的选项卡交互样式。实际发布文章时，只要你的文章正文中使用了{% tabs %}标签，就应保留该声明以保证样式完整生效。

2. 站点级配置：插件已在默认列表中

Tabs 依赖项已在 al-folio 的默认配置中全部就绪：

• 依赖声明：Gemfile 中gem 'jekyll-tabs'；
• 版本锁定：Gemfile.lock 中jekyll-tabs (1.2.1)；
• 插件注册：_config.yml 中plugins:列表内的- jekyll-tabs。

因此新克隆仓库后只需执行常规安装流程即可使用：

bundle install # 安装 Gemfile 中锁定的所有插件 bundle exec jekyll serve # 本地预览，访问 http://localhost:4000 查看效果

部署到 GitHub Pages 或其他 Jekyll 托管平台时，上述依赖会随构建流程自动安装，无需额外操作。

七、注意事项与常见问题

1. 组名一致性：{% tabs xxx %}与每个{% tab xxx 名称 %}的第一个参数必须严格一致，否则页签无法正确归组；
2. 成对闭合：每个{% tab %}必须有对应的{% endtab %}，整组必须以{% endtabs %}收尾，缺一不可，否则 Liquid 解析会报错或导致页面结构错乱；
3. 演示代码要转义：若文章需要展示 Tabs 语法本身，务必用{% raw %}/{% endraw %}包裹，否则 Jekyll 会在构建时直接执行这些标签（示例文章正是这样做的）；
4. 语言围栏要与内容匹配：代码页签内的 Markdown 代码围栏语言标识应与实际内容一致，避免高亮错乱（可参考第三节中的原文笔误提醒）；
5. 与其他插件的共存：在 al-folio 的 plugins 列表 中，jekyll-tabs与jekyll-toc（自动目录）、jekyll-minifier（压缩）、jemoji（表情）等插件同时启用，说明 Tabs 可以放心与目录生成、资源压缩等站点级功能协同工作；
6. 自定义样式：如果希望调整页签的外观（如配色、边框、激活态），可参考 docs/CUSTOMIZE.md 中对主题定制体系的说明，从站点样式入口入手覆写。

结语

Tabs 是 al-folio 博客排版能力中"轻量但高频"的一环：语法只有四个标签，却能显著提升长文章的信息组织效率。无论是多语言代码对照、多种数据格式对比，还是观点与引用的并列展示，只要记住"组名一致、成对闭合、内容任意"这三个要点，即可在 _posts/ 目录下的任意文章中使用这一能力。若想继续探索 al-folio 的其他内容排版特性，可对照示例文章目录 _posts/ 中的 code、tables、custom-blockquotes 等样例，并结合 docs/CUSTOMIZE.md 逐步搭建属于自己的写作工具箱。

【免费下载链接】al-folioA beautiful, simple, clean, and responsive Jekyll theme for academics项目地址: https://gitcode.com/GitHub_Trending/al/al-folio