Projects › BibleWeb › Commentaries › Paragraph-aware rendering
Needs Design

Paragraph-aware rendering

Area: Commentaries Milestone: v2

Context

Problem: Commentary text is currently rendered by splitting on newline characters, which works but doesn't capture the original paragraph structure of the commentary. Some commentary entries have logical sections, sub-headings, or numbered points that would benefit from better visual formatting.

Solution: Implement smarter paragraph detection that can identify structural elements in commentary text — section breaks, numbered lists, and quoted Scripture — and render them with appropriate visual formatting.

Not included: Full rich-text/HTML rendering or user-editable formatting. This is about detecting and displaying the existing structure in the plain-text commentary data.

Functional

Commentary text should display with visual paragraph breaks that respect the original structure of the commentary, rather than treating every newline as an equal paragraph break.

TODO: Define what structural elements exist in the commentary data (headers, lists, quotations?) TODO: Survey a sample of commentary entries to identify common patterns

UX & Design

Expected improvements:

  • Clear visual separation between paragraphs
  • Possible indentation for quoted Scripture passages
  • Possibly bolder text for section headers within long entries

TODO: Design the visual treatment for different paragraph types TODO: Mockup showing before/after comparison

Technical

Current rendering (in CommentaryDrawer.svelte):

  • Text split by \n into lines
  • Empty lines filtered out
  • Each non-empty line wrapped in a <p> tag
  • No structural analysis

Proposed approach:

  • Analyze text patterns: detect Scripture quotations (e.g., lines starting with verse references), section headers, numbered lists
  • Wrap different elements in appropriate semantic HTML
  • Apply CSS styling per element type

TODO: Analyze the actual commentary text data to identify patterns worth formatting

Files:

  • apps/web/src/lib/components/bible/CommentaryDrawer.svelte (modify)

Status

Current: NEEDS_DESIGN Milestone: v2 Priority: Low — current paragraph rendering works, this is a polish feature

History:

  • Current implementation does basic newline-splitting
  • No equivalent existed in BibleGame (it had simpler text rendering)

Design questions:

  1. What structural patterns exist in the commentary data?
  2. Is the effort worth it or is newline-splitting good enough?
  3. Should this apply to all three commentary sources equally?

Dependencies:

  • Requires: commentary drawer (DONE), commentary data (DONE)
  • Blocks: nothing
← Back to Commentaries features