Add translatable "On this page" title to desktop table of contents (#103)

* feat(toc): add translatable 'On this page' title to desktop TOC

Add a custom TOC component that displays a translatable "On this page"
title above the table of contents on desktop. This improves consistency
with the mobile TOC dropdown which already has a title.

Changes:
- Create custom TOC wrapper component in src/theme/TOC/index.tsx
- Add "On this page" title using @docusaurus/Translate for i18n support
- Add CSS styling for .toc-heading class with theme support
- Include Portuguese translation: "Nesta página"
- Include Spanish translation: "En esta página"

The component wraps the default Docusaurus TOC and adds a styled heading
that adapts to light/dark themes.

* fix(toc): restore sticky positioning to TOC wrapper

The TOC wrapper div was missing sticky positioning, causing the TOC
to scroll away instead of remaining fixed while scrolling the page.

Changes:
- Add .toc-wrapper class to the wrapper div
- Apply position: sticky to .toc-wrapper in CSS
- Set appropriate top offset relative to navbar height
- Add max-height and overflow-y for scrollable TOC on long pages

This fixes the regression introduced in the previous commit where
wrapping the TOC component broke the default sticky behavior.

* fix(toc): add pagination-nav padding for last item focus

Add bottom padding to .pagination-nav to allow the last heading
on a page to scroll high enough to trigger the active state in
the table of contents.

Changes:
- Add 50vh padding-bottom to .pagination-nav
- Enables last TOC item to become focused/active when scrolled to

Without this padding, the page cannot scroll far enough for the
last heading to reach the scroll position required to activate
its TOC link.

* fix(spacing): balance pagination-nav padding and add footer margin

Reduce excessive bottom padding on pagination-nav and distribute
it more evenly between top and bottom. Add matching margin-bottom
to doc footer for visual balance.

Changes:
- Change pagination-nav from 50vh bottom-only to 2rem top + 20vh bottom
- Add 3rem margin-bottom to .theme-doc-footer (matching margin-top)

This provides enough space for the last TOC item to activate while
maintaining better visual balance and less excessive whitespace.

* fix(spacing): remove padding-top from pagination-nav

Remove the 2rem top padding from pagination-nav, keeping only
the bottom padding needed for last TOC item activation.

Changes:
- Remove padding-top: 2rem from .pagination-nav
- Keep padding-bottom: 20vh for TOC functionality

---------

Co-authored-by: Claude <[email protected]>

Author: luandro

i18n/es/code.json

@@ -0,0 +1,6 @@
+{
+  "theme.TOC.title": {
+    "message": "En esta página",
+    "description": "Title for the table of contents section"
+  }
+}

i18n/pt/code.json

@@ -0,0 +1,6 @@
+{
+  "theme.TOC.title": {
+    "message": "Nesta página",
+    "description": "Title for the table of contents section"
+  }
+}

src/css/custom.css

@@ -508,3 +508,36 @@ article {
     padding-top: 2rem;
   }
 }
+
+/* TOC wrapper with sticky positioning */
+.toc-wrapper {
+  position: sticky;
+  top: calc(var(--ifm-navbar-height, 60px) + 1rem);
+  max-height: calc(100vh - var(--ifm-navbar-height, 60px) - 2rem);
+  overflow-y: auto;
+}
+
+/* TOC heading styling */
+.toc-heading {
+  font-size: 0.875rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--ifm-color-emphasis-700);
+  margin: 0 0 0.75rem 0;
+  padding-left: 0.5rem;
+}
+
+[data-theme="dark"] .toc-heading {
+  color: var(--ifm-color-emphasis-600);
+}
+
+/* Add padding to pagination nav to allow last TOC item to scroll into view */
+.pagination-nav {
+  padding-bottom: 20vh;
+}
+
+/* Add bottom margin to doc footer matching top margin */
+.theme-doc-footer {
+  margin-bottom: 3rem;
+}

src/theme/TOC/index.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import TOC from "@theme-original/TOC";
+import type TOCType from "@theme/TOC";
+import type { WrapperProps } from "@docusaurus/types";
+import { translate } from "@docusaurus/Translate";
+
+type Props = WrapperProps<typeof TOCType>;
+
+export default function TOCWrapper(props: Props): JSX.Element {
+  return (
+    <div className="toc-wrapper">
+      <h2 className="toc-heading">
+        {translate({
+          id: "theme.TOC.title",
+          message: "On this page",
+          description: "Title for the table of contents section",
+        })}
+      </h2>
+      <TOC {...props} />
+    </div>
+  );
+}