Define global table of contents settings for consistent sidebar headings

[luandro]

Background

Documentation pages rendered from Notion show inconsistent entries in the right sidebar table of contents. Some level 2 and level 3 headings appear while others are missing.

Findings

• docusaurus.config.ts currently relies on the Docusaurus defaults and does not populate themeConfig.tableOfContents.
• Notion generated Markdown sometimes emits heading levels at 2 and 3; Docusaurus requires explicit configuration to treat them uniformly.
• A previous worktree (worktrees/fix-toc-inconsistency/docusaurus.config.ts) demonstrates that setting tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 } yields consistent results.

Goal

Define global table of contents settings so that every heading at level 2 and level 3 appears in the sidebar across the site.

Acceptance Criteria

• themeConfig.tableOfContents is declared in docusaurus.config.ts with minHeadingLevel: 2 and maxHeadingLevel: 3.
• Verify the sidebar on "Setting up a device & maintaining it" and other Notion generated pages shows the correct level 2 and level 3 headings.
• Confirm handmade Markdown pages keep the expected sidebar hierarchy.
• Document any outliers that still fail so they can be tracked separately.

Testing

• bunx prettier --write docusaurus.config.ts
• Manual browser check of at least one Notion sourced page and one handwritten page after applying the configuration.

[github-actions]

🚀 Preview Deployment

Your documentation preview is ready!

Preview URL: https://pr-44.comapeo-docs.pages.dev

This preview will update automatically when you push new commits to this PR.

---

_{Built with commit a4f4af0}

[luandro]

Code Review Summary

What This PR Does

This PR fixes inconsistent table of contents (TOC) rendering in the documentation sidebar by:

• Adding explicit global TOC configuration to docusaurus.config.ts
• Setting minHeadingLevel: 2 and maxHeadingLevel: 3
• Ensures all H2 and H3 headings appear consistently in the right sidebar
• Resolves issues where some headings were missing from the TOC on Notion-generated pages

How It Solves the Issue

By explicitly configuring themeConfig.tableOfContents with defined heading levels, the PR ensures:

• Docusaurus no longer relies on default heuristics which were inconsistent
• All H2 headings will appear in the TOC
• All H3 headings will appear nested under their parent H2
• Consistent behavior across all pages regardless of content source

Potential Issues & Considerations

Strengths:

• ✅ Minimal, focused change (5 lines of config)
• ✅ Addresses root cause: missing explicit configuration
• ✅ No side effects - only affects TOC rendering
• ✅ Simple and maintainable

Areas to Watch:

• ⚠️ Heading Level Validation: Need to verify that Notion-generated content consistently uses H2/H3 for the intended TOC entries. Some content might use H4+ which would be excluded.
• ⚠️ Handwritten Pages: PR description mentions verifying handwritten pages maintain expected hierarchy - this should be manually tested
• ⚠️ Edge Cases: Need to verify pages with only H1 or no headings, and pages with H4+ headings

Code Quality:

• Clean, straightforward configuration change
• Follows Docusaurus configuration patterns
• Well-documented in the PR description with acceptance criteria

Testing:

• Only prettier formatting applied
• Manual browser testing recommended as noted in acceptance criteria
• Should verify on both Notion-generated and handwritten pages

Recommendation: ✅ Approve - Simple, well-targeted fix for a configuration issue. The explicit TOC settings will ensure consistent sidebar rendering across the site.

[github-actions]

🧹 Preview Deployment Cleanup

The preview deployment for this PR has been cleaned up.

Preview URL was: https://pr-44.comapeo-docs.pages.dev

---

_{Note: Cloudflare Pages deployments follow automatic retention policies. Old previews are cleaned up automatically.}