feat(content): expose auto-generated TOC as post.toc

[x3ek]

Closes #49.

Summary

python-markdown's TocExtension was already registered (markdown.py:87) — the output was just being discarded. This PR threads it through to themes via post.toc.

Changes

• services/markdown.py — render_markdown() now returns tuple[str, str] (html, toc). parse_post pulls the TOC; parse_page discards it (pages don't carry a TOC per the issue framing).
• models/content.py — FrontMatter.toc: bool = True (per-post opt-out via toc: false in frontmatter); Post.toc: str = "" (rendered fragment).
• All three bundled themes opt in to demonstrate the "theme decides presentation" principle:
  • default — inline accent-bordered card above the post body
  • blue-tech — <details> collapsible, closed by default
  • terminal — floating right-side sticky sidebar anchored to the article column edge (hidden below 1140px viewport)
• Tests — render returns toc, parse_post populates, frontmatter toc: false opt-out works, parse_page doesn't carry toc

Why three different theme treatments?

The engine just exposes post.toc as raw HTML — every UX decision (inline vs sidebar, collapsible, where to place it, when to render) belongs to the theme. Wiring all three to render it differently demonstrates that contract and gives theme authors three reference patterns to start from.

Test plan

• python scripts/run-checks.py — 237 tests pass, ruff clean, 0 pyright errors
• Playwright verified across all 3 themes with a post containing nested h2/h3 headings (Grandma's Intergalactic Gumbo)
• Manually verified toc: false frontmatter opt-out (no TOC renders)
• Verified anchor links jump to correct heading IDs (existing HeadingAnchorExtension already wires those)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR surfaces the existing python-markdown TocExtension output to themes by threading a rendered TOC fragment through the content pipeline as post.toc, with a per-post frontmatter opt-out (toc: false). It updates all bundled themes to demonstrate different TOC presentations and extends the markdown test suite accordingly.

Changes:

• Update markdown rendering to return (html, toc) and plumb TOC into Post.toc (with frontmatter opt-out).
• Extend FrontMatter/Post models to carry TOC configuration and the rendered TOC fragment.
• Update bundled themes and add/adjust tests to cover TOC behavior.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/squishmark/services/markdown.py	Return TOC alongside HTML; populate post.toc in parse_post and discard for pages.
src/squishmark/models/content.py	Add FrontMatter.toc opt-out and Post.toc field.
tests/test_markdown.py	Update render_markdown call sites and add TOC-related tests.
themes/default/post.html	Render post.toc above the post body when present.
themes/default/static/style.css	Style TOC as an inline card.
themes/blue-tech/post.html	Render post.toc inside a collapsed-by-default <details>.
themes/blue-tech/static/style.css	Style the <details> TOC presentation.
themes/terminal/post.html	Render post.toc as a floating sidebar <aside>.
themes/terminal/static/css/style.css	Add floating TOC positioning/styling rules.

Comments suppressed due to low confidence (1)

tests/test_markdown.py:54

• The comment here mentions the TOC extension adding a permalink, but TocExtension(permalink=False) is configured in MarkdownService._get_markdown_instance(). This is slightly misleading about what’s providing the self-link behavior.

— GitHub Copilot

    # Verify the HTML output contains expected elements
    # The TOC extension adds id and permalink to headings
    assert html.startswith("<h1"), f"Expected HTML to start with h1 tag, got: {html[:50]}"