formatTextBlocks

Format text blocks into readable string output

Function Signature

export const formatTextBlocks = (
  textBlocks: TextBlock[],
  footerSymbol?: string
): string

Location: src/index.ts:11

Description

Formats an array of text blocks into a readable string with proper paragraph breaks and spacing. This is the final stage of the paragraph reconstruction pipeline.

The function handles:

• Proper line breaks between paragraphs
• Extra spacing after headings
• Optional symbol insertion before the first footnote
• Preservation of document structure through formatting

Parameters

textBlocks · TextBlock[] · required

Array of text blocks to format. These are typically paragraph-level blocks from mapTextLinesToParagraphs.

Each TextBlock can have:

• text: The paragraph content
• isHeading: If true, adds extra spacing after the heading
• isFootnote: If true and footerSymbol is provided, adds symbol before first footnote

footerSymbol · string

Optional symbol to insert before the first footnote.

Common values:

• "---" - Horizontal rule separator
• "***" - Asterisk separator
• "\n---\n" - Separator with extra spacing
• "[Footnotes]" - Text label

Returns

return · string

Formatted text string with proper line breaks and spacing.

• Paragraphs are separated by single newlines
• Headings have an extra blank line after them
• Footer symbol (if provided) appears before the first footnote
• All content is joined with newline characters

Example

import { formatTextBlocks } from 'kokokor';

const textBlocks = [
  {
    text: 'Chapter One',
    bbox: { x: 100, y: 50, width: 120, height: 20 },
    isHeading: true
  },
  {
    text: 'This is the first paragraph of the chapter.',
    bbox: { x: 50, y: 100, width: 300, height: 15 },
    isHeading: false,
    isFootnote: false
  },
  {
    text: 'This is the second paragraph.',
    bbox: { x: 50, y: 140, width: 280, height: 15 },
    isHeading: false,
    isFootnote: false
  },
  {
    text: 'See reference for more details.',
    bbox: { x: 50, y: 750, width: 200, height: 12 },
    isHeading: false,
    isFootnote: true
  }
];

const formatted = formatTextBlocks(textBlocks, '---');

console.log(formatted);
// Output:
// Chapter One
//
// This is the first paragraph of the chapter.
// This is the second paragraph.
// ---
// See reference for more details.

Example without Footer Symbol

const simpleBlocks = [
  {
    text: 'Introduction',
    bbox: { x: 100, y: 50, width: 100, height: 20 },
    isHeading: true
  },
  {
    text: 'This is a simple paragraph.',
    bbox: { x: 50, y: 100, width: 200, height: 15 }
  }
];

const output = formatTextBlocks(simpleBlocks);

console.log(output);
// Output:
// Introduction
//
// This is a simple paragraph.

Formatting Rules

Block Type	Formatting
Regular paragraph	Single newline separator
Heading (isHeading: true)	Text + empty line (double newline)
First footnote with footerSymbol	Symbol on its own line + footnote text
Subsequent footnotes	Single newline separator

Notes

• The function uses a single-pass algorithm for efficiency
• Footer symbol is inserted only once, before the first footnote
• Headings automatically get extra spacing for visual separation
• The output is plain text suitable for display or further processing
• Line breaks use \n (newline) characters