如何在GitHub Pages站点左侧添加自定义层级目录

最通用的零依赖方案，不需要引入第三方工具，适配纯静态HTML、Jekyll等所有GitHub Pages常用的构建形式，直接复制代码调整即可使用。

1. 基础结构调整 #

首先给正文里的所有层级标题设置唯一id，方便锚点跳转，规则是id和标题对应，全小写、空格替换为短横线即可，比如：

<h2 id="introduction">Introduction</h2>
  <h3 id="characters-and-products">Characters and Products</h3>
<h2 id="step-1-ask">Step 1 - Ask</h2>
  <h3 id="list-item">List item</h3>
<h2 id="step-2-prepare">Step 2 - Prepare</h2>
<!-- 后续所有章节标题按相同规则加id -->

之后把所有正文内容包裹在一个带main-content类的div里，避免后续固定侧边栏时挡住正文：

<div class="main-content">
  <!-- 这里放所有正文内容、标题、段落、图片等 -->
</div>

2. 插入目录结构 #

在页面<body>标签开头的位置，插入目录的导航结构，层级完全匹配你需要的格式：

<nav class="sidebar-toc">
  <h3>Table of Contents</h3>
  <ul>
    <li>
      <a href="#introduction">Introduction</a>
      <ul>
        <li><a href="#characters-and-products">Characters and Products</a></li>
      </ul>
    </li>
    <li>
      <a href="#step-1-ask">Step 1 - Ask</a>
      <ul>
        <li><a href="#list-item">List item</a></li>
      </ul>
    </li>
    <li><a href="#step-2-prepare">Step 2 - Prepare</a></li>
    <!-- 后续章节按相同格式追加即可 -->
  </ul>
</nav>

如果不想手动维护目录条目，可以直接用自动生成脚本，把下面这段代码放到页面</body>标签前，会自动识别正文里的h2、h3标题生成对应层级的目录，不需要手动写上面的li条目：

const tocRoot = document.querySelector('.sidebar-toc ul');
const headings = document.querySelectorAll('.main-content h2, .main-content h3');
let activeH2Item = null;

headings.forEach(heading => {
  const item = document.createElement('li');
  const link = document.createElement('a');
  link.href = `#${heading.id}`;
  link.textContent = heading.textContent;
  item.appendChild(link);

  if (heading.tagName === 'H2') {
    activeH2Item = item;
    tocRoot.appendChild(item);
  }
  if (heading.tagName === 'H3' && activeH2Item) {
    let subList = activeH2Item.querySelector('ul');
    if (!subList) {
      subList = document.createElement('ul');
      activeH2Item.appendChild(subList);
    }
    subList.appendChild(item);
  }
});

3. 添加样式固定到左侧 #

把下面这段CSS放到页面的<style>标签里，或者站点的全局CSS文件中，就能把目录固定在左侧，样式可以根据现有站点的配色自行调整：

/* 侧边栏目录基础样式 */
.sidebar-toc {
  position: fixed;
  top: 2rem;
  left: 2rem;
  width: 220px;
  max-height: 90vh;
  overflow-y: auto;
  padding: 1rem;
  border-right: 1px solid #e5e7eb;
  font-size: 0.95rem;
  line-height: 1.5;
}
.sidebar-toc h3 {
  margin-top: 0;
  font-size: 1.1rem;
}
.sidebar-toc ul {
  list-style: none;
  padding-left: 0;
  margin: 0.5rem 0;
}
/* 二级目录缩进样式 */
.sidebar-toc ul ul {
  padding-left: 1rem;
  font-size: 0.9rem;
  color: #4b5563;
}
.sidebar-toc a {
  display: block;
  padding: 0.25rem 0;
  color: inherit;
  text-decoration: none;
}
.sidebar-toc a:hover {
  color: #2563eb;
}
/* 正文偏移，避免被目录遮挡 */
.main-content {
  margin-left: 280px;
  max-width: 800px;
  padding: 2rem;
}

可选优化 #

• 调整CSS里的left、width、margin-left数值，可以修改目录的位置、宽度和正文的偏移距离，适配站点现有布局
• 加滚动监听可以实现当前阅读章节对应的目录项高亮效果，只需要监听页面滚动，判断当前进入视口的标题，给对应目录链接加高亮类即可
• 移动端适配可以加媒体查询，屏幕宽度小于768px时把目录改成顶部横向固定、宽度100%，正文的左边距改为0、顶部预留目录高度，避免小屏幕上目录遮挡正文。

如果你是用Markdown写内容、通过Jekyll自动构建GitHub Pages，不需要写上面的自动生成JS，直接在布局模板的侧边栏位置用内置的目录过滤器就能自动生成全站点的目录结构，维护成本更低。

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