如何为自定义Jekyll主题创建文档片段及实现标题pilcrow图标链接

文档片段是可复用的HTML模块，通过Jekyll的include标签快速调用，实现步骤如下：

• 创建片段文件：在主题的_includes目录下新建HTML文件（比如callout.html），写入可复用结构，支持通过参数自定义内容：

<div class="callout callout-{{ include.type | default: 'info' }}">
  <h4>{{ include.title }}</h4>
  <p>{{ include.content }}</p>
</div>

• 在页面/布局中调用：在需要插入片段的位置，用Liquid标签调用并传入参数：

{% include callout.html title="注意" type="warning" content="这是一个警告类型的文档片段" %}

• 添加样式（可选）：在主题CSS文件中为片段添加样式，区分不同类型：

.callout {
  padding: 1.5rem;
  margin: 1rem 0;
  border-radius: 4px;
}
.callout-warning {
  background-color: #fff3cd;
  border-left: 4px solid #ffc107;
  color: #856404;
}

该功能结合Kramdown锚点生成、JavaScript注入图标和CSS样式控制，具体实现：

第一步：配置Kramdown自动生成标题ID #

在站点_config.yml中添加Kramdown配置，确保标题自动生成锚点ID：

kramdown:
  auto_ids: true
  id_prefix: ""
  anchor_separator: "-"

第二步：用JavaScript为标题添加pilcrow锚点 #

在主题JS文件（比如assets/js/site.js）中加入以下代码，页面加载后自动遍历标题并插入锚点链接：

document.addEventListener('DOMContentLoaded', () => {
  const headings = document.querySelectorAll('h1, h2, h3, h4, h5, h6');
  headings.forEach(heading => {
    if (heading.id) {
      const anchor = document.createElement('a');
      anchor.href = `#${heading.id}`;
      anchor.className = 'pilcrow';
      anchor.textContent = '¶';
      anchor.setAttribute('aria-label', '跳转到该标题');
      heading.appendChild(anchor);
    }
  });
});

第三步：添加CSS样式控制显示 #

在主题CSS文件中添加样式，让pilcrow图标默认隐藏，鼠标悬停标题时显示：

h1, h2, h3, h4, h5, h6 {
  position: relative;
  padding-left: 1.2rem;
}

.pilcrow {
  position: absolute;
  left: 0;
  opacity: 0;
  text-decoration: none;
  color: #666;
  transition: opacity 0.2s ease;
}

h1:hover .pilcrow,
h2:hover .pilcrow,
h3:hover .pilcrow,
h4:hover .pilcrow,
h5:hover .pilcrow,
h6:hover .pilcrow {
  opacity: 1;
}

测试验证 #

启动Jekyll本地服务bundle exec jekyll serve，打开文档页面，鼠标悬停标题会显示¶图标，点击后地址栏出现对应标题的锚点链接，页面自动滚动到该标题位置。

内容的提问来源于stack exchange，提问作者Skrillx