Creating a Responsive, Dark Mode–Ready Table of Contents Box in Hugo’s beautifulhugo Theme

When using the beautifulhugo theme for your Hugo-powered blog, you might want to add a clean and stylish Table of Contents (TOC) to your posts. But, like many users, you may run into issues, especially with dark mode and mobile:

• The TOC box background and text can become unreadable in dark mode.
• On mobile, the box might blend in with the page background or lose its margin.

This guide will show you how to fix these issues using only CSS classes, no inline styles!, for maximum flexibility and maintainability.

---

1. The Problem

Most default TOC implementations (or copy-pasted snippets) use inline styles like this:

<div class="toc-wrapper toc-box" style="text-align:center; margin: 2em auto;">
  <div class="toc-inner" style="display: inline-block; background: #f8f8f8; border: 1px solid #ccc;">
    <!-- TOC content here -->
  </div>
</div>

Why is this bad?

• Inline styles (the style=”…” attributes) are hard to override, especially when you want different looks for dark mode or on mobile devices.
• In dark mode, if the TOC box uses a light background (like #f8f8f8) but the text switches to light, your TOC can turn white-on-white (invisible).
• On mobile, the background or border might not stand out, reducing the visibility of the box.

---

2. The Solution: Classes + CSS

Remove all inline styles from your HTML. Use only classes to control layout.

Example: Clean HTML in single.html

{{ $toc := .TableOfContents }}
{{ if gt (len (plainify $toc)) 0 }}
  <div class="toc-wrapper toc-box">
    <div class="toc-inner">
      <h2>
        {{ if eq .Site.Language.Lang "ja" }}
          目次
        {{ else }}
          Table of Contents
        {{ end }}
      </h2>
      <nav id="TableOfContents">
        {{ $toc | safeHTML }}
      </nav>
    </div>
  </div>
{{ end }}

No inline styles!

---

Example: Robust CSS (add to your custom.css)

.toc-wrapper {
  text-align: center;   /* Centers the box horizontally */
  margin: 2em auto;
}
.toc-inner {
  display: inline-block;
  background: #f8f8f8;
  border: 1px solid #ccc;
  border-radius: 10px;
  padding: 1em 2em;
  box-shadow: 0 2px 8px rgba(0,0,0,0.06);
  text-align: left;     /* Contents are left-aligned */
}
.toc-inner h2 {
  margin-top: 0;
  text-align: center;   /* TOC title is centered */
}
/* Dark Mode */
@media (prefers-color-scheme: dark) {
  .toc-inner {
    background: #222;
    border-color: #444;
    color: #f8f8f8;
  }
  .toc-inner a {
    color: #aadfff;
  }
}

---

3. Why This Works

• All styling is handled in CSS, not inline, so you can override or extend it as needed.
• The TOC box is centered on the page but the TOC entries are left-aligned, clean and readable.
• Dark mode is handled via a media query for perfect contrast on any device.
• On mobile devices, the box remains consistent and doesn’t suddenly turn invisible or blue.
• It’s easy to further customize spacing, radius, etc., all in your CSS file.

---

4. Extra Tips

• Never override styling for just mobile unless you want it to look different!
• To make your site easier to maintain: use only CSS classes for visual design and avoid inline styles.
• Always test both desktop and mobile, in both light and dark modes.

---

5. Conclusion

Designing a Table of Contents box that works on all devices and in dark mode is easy if you rely on classes and modern CSS, instead of inline styles. Just follow the simplified HTML and CSS patterns above, and your TOC will always look beautiful, readable, and consistent.