Skip to content

feat: move TOC to sticky right sidebar for better readability #83

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
jiacai2050 merged 2 commits into from
Jan 13, 2026
Merged

feat: move TOC to sticky right sidebar for better readability #83

jiacai2050 merged 2 commits into from
Jan 13, 2026
+86 −34

Conversation

@jiacai2050
Copy link
Member

@jiacai2050 jiacai2050 commented Jan 13, 2026

  • Implement side-by-side layout for content and TOC using Flexbox.
  • Make TOC sticky on large screens (>= 1200px).
  • Update template inheritance to use id='content' for Zine compatibility.
  • Increase page max-width on wide screens to accommodate sidebar.

@jiacai2050
feat: move TOC to sticky right sidebar for better readability
1fe6450 
- Implement side-by-side layout for content and TOC using Flexbox.
- Make TOC sticky on large screens (>= 1200px).
- Update template inheritance to use id='content' for Zine compatibility.
- Increase page max-width on wide screens to accommodate sidebar.
Copilot AI review requested due to automatic review settings January 13, 2026 08:20
@jiacai2050
Copy link
Member Author

jiacai2050 commented Jan 13, 2026

/gemini review

Copilot AI reviewed Jan 13, 2026
View reviewed changes
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR restructures the documentation layout by moving the Table of Contents from its original position to a sticky sidebar on the right side of the page, improving readability on larger screens. The implementation uses a responsive flexbox layout that adapts to screen size.

Changes:

  • Wrap content and TOC in a flexbox container (.content-wrapper) with sidebar positioning on screens >= 1200px
  • Update template inheritance pattern from <body id="body"> to <div id="content"> in child templates for Zine SSG compatibility
  • Increase body max-width from 60vw to 80vw on large screens to accommodate the sidebar layout

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
layouts/templates/content.shtml Restructure layout with flexbox container, move TOC to sticky sidebar, add id="content" to main content div
layouts/learn.shtml Apply same flexbox layout and sidebar structure as content.shtml
layouts/post.shtml Change from <body id="body"> to <div id="content"> for template inheritance compatibility
layouts/page.shtml Change from <body id="body"> to <div id="content"> for template inheritance compatibility
layouts/monthly.shtml Change from <body id="body"> to <div id="content"> for template inheritance compatibility
assets/style.css Add responsive flexbox styles for sidebar layout with sticky positioning and increased page width on large screens

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

layouts/learn.shtml
<a href="$if.link()">
<span :text="$if.title"></span>
</a>
<div class="main-content">
Copy link

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The main-content div is missing the id="content" attribute in the learn.shtml template, while it is present in content.shtml. This inconsistency could cause issues if there's JavaScript or CSS targeting the #content selector, and breaks the pattern established in content.shtml for Zine compatibility as mentioned in the PR description.

Suggested change
<div class="main-content">
<div id="content" class="main-content">

Copilot uses AI. Check for mistakes.
@jiacai2050
style: improve TOC vertical centering and sticky behavior
0e87560 
- Change content-wrapper align-items to stretch to ensure sidebar height matches content.
- Remove top margin from toc-sidebar to improve alignment.
- Use top: 50% and transform: translateY(-50%) for precise vertical centering of sticky TOC.
@jiacai2050
Copy link
Member Author

jiacai2050 commented Jan 13, 2026

这次修改主要涉及了 Flexbox 布局、定位技术 和 响应式设计 三大块 CSS 核心知识。

以下是详细的知识点拆解：

1. Flexbox 布局 (Flexible Box Layout)

这是实现“左文右侧边栏”结构的基础。

  • display: flex: 启用了弹性盒模型。
  • flex-direction: row: 将排列方向改为水平（行），让正文和 TOC 并排显示。
  • align-items: stretch (关键修正点):
    • 这是默认值，但非常重要。它强制让侧边栏（TOC 的父容器）的高度自动拉伸，使其与正文区域的高度一致。
    • 为什么重要？ position: sticky 只有在其父容器有足够的高度供其“滑动”时才会生效。如果父容器高度只包裹了 TOC 本身，TOC 就没法相对于正文滚动的区域进行移动了。
  • flex: 1: 应用在正文区域 (.main-content)，让它占据剩余的所有可用宽度。
  • flex-shrink: 0: 应用在侧边栏 (.toc-sidebar)，防止当屏幕变窄时侧边栏被挤压变形，确保它始终保持 250px 宽。

2. 粘性定位 (Position Sticky)

这是让 TOC 随滚动固定的核心。

  • position: sticky:
    • 这是一个介于 relative 和 fixed 之间的混合定位模式。
    • 当元素在视口（Viewport）内时，它像普通元素一样占据空间。
    • 当页面滚动达到指定的阈值（如 top 值）时，它会表现得像 fixed 一样固定在窗口上，但它的活动范围被限制在其父容器内。
  • top: 50% + transform: translateY(-50%):
    • 这是一个经典的垂直居中技巧。
    • top: 50%: 将元素的顶部边缘推到视口垂直方向的 50% 处。
    • transform: translateY(-50%): 将元素沿着 Y 轴向上移动自身高度的 50%。
    • 两者结合，就实现了元素的中心点与视口的中心点对齐。

3. 响应式设计 (Responsive Design)

为了兼顾不同设备，使用了媒体查询。

  • @media screen and (min-width: 1200px):
    • 采用了移动优先 (Mobile First) 的思维。默认 CSS 是针对移动端的（TOC 在上方，垂直排列）。
    • 只有当屏幕宽度大于 1200px 时，才应用 Flex 行布局和 Sticky 效果。
  • 视口单位 (vw, vh):
    • max-width: 80vw: 这里的 vw 代表视口宽度的百分比。大屏下将宽度从 60% 增加到 80%，是为了给新增的侧边栏腾出空间。
    • max-height: 90vh: 限制 TOC 的最大高度为视口高度的 90%，防止 TOC 内容过长超出屏幕而无法看到底部。

4. 滚动行为控制

  • overflow-y: auto: 当 TOC 内容超过 90vh 时，允许 TOC 内部出现滚动条，确保长目录也能完整浏览。

总结来说，这次修改利用 Flexbox 搭建骨架，利用 Sticky 实现交互效果，再配合 Transform 进行精细的位置调整。

@jiacai2050 jiacai2050 merged commit c35a954 into main Jan 13, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@xihale xihale xihale approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@jiacai2050 @xihale