empty blocks use to add space between content are being ignored

[jencastrodoesstuff]

Summary

Single empty blocks used in Notion to create vertical spacing are removed during publishing.

Reproduction Steps

1. In Notion, insert an empty block between two content blocks to add extra vertical separation.
2. Run the standard sync to publish the page.
3. Inspect the rendered page on the docs site.

Current Behavior

The empty block is ignored, so the extra spacing disappears and grouped content collapses together.

Expected Behavior

Either preserve those intentional empty blocks as vertical spacing or provide another author-friendly way to add deliberate gaps between sections.

Additional Context

This contributes to layout differences between Notion and the published site, making visual grouping harder to control.

[luandro]

Research Notes

Key references

• Notion represents empty paragraphs as paragraph blocks whose rich_text array is empty (https://developers.notion.com/reference/block#paragraph-blocks). They are delivered by the API but are easy to drop when filtering falsy content during serialization.
• Markdown interprets blank lines as paragraph separators; to keep an intentional spacer we need a distinct token such as <br />,  , or a dedicated component (https://spec.commonmark.org/0.30/#blank-lines).

Findings

• Our pipeline likely removes blocks with no rich text to avoid empty markdown output. That loses intentional spacing that authors add between sections.
• Preserving a literal blank line will collapse in Markdown; we need to emit something tangible (HTML break, custom <Spacer /> component, or Infima utility).

Implementation directions

• Treat empty paragraph blocks as spacer tokens during conversion:
  • Emit <br /> (or <div class="notion-spacer"></div>) directly in markdown so MDX renders a vertical gap.
  • Alternatively, map to a custom MDX component like <DocSpacer size="md" /> and add a simple component in src/components to control spacing consistently.
• If opting for a custom component, register it through MDX provider to keep markdown clean and controllable.

Open questions / TODOs

• Should authors prefer a deliberate pattern (e.g., a Notion callout with property Spacer)? That might be more intentional than relying on empty blocks.
• Need to confirm whether Notion ever auto-inserts empty blocks at the end of pages; we should avoid rendering stray spacers at top/bottom.
• Decide on responsive behavior—do we want the same spacing on mobile, or should the component collapse at smaller breakpoints?

[luandro]

@codex review this PR, special attention to the image in the description, where image in the right (our app) should match as close as possible to the one in the left (Notion), in regards to spacing.

[chatgpt-codex-connector]

Summary

• Registered a Notion-to-Markdown custom transformer that emits spacer markup for empty paragraph blocks so intentional gaps survive publishing. scripts/notionClient.tsL259-L312
• Expanded the Notion client test suite and supporting mocks to cover the spacer transformer behavior and ensure fallback conversion still runs for populated paragraphs. scripts/notionClient.test.tsL75-L242 scripts/test-utils/mocks.tsL27-L32
• Styled the injected spacer element with a responsive height to align on-page spacing with Notion’s layout. src/css/custom.cssL318-L329

Testing

• ⚠️ bunx vitest run scripts/notionClient.test.ts (fails: Cannot find module 'vitest/config' in this environment).

View task →

[luandro]

fixed with #65