fix: preserve manual line breaks and match Notion spacing #57

luandro · 2025-10-23T20:38:11Z

Summary

This PR fixes two related content rendering issues to improve consistency between Notion and published documentation:

Issue Preserve manual line breaks from Notion in generated Markdown #47: Preserve manual line breaks from Notion in generated Markdown
Issue Match paragraph and list spacing with Notion layout #48: Match paragraph and list spacing with Notion layout

Changes

Issue #47: Manual Line Breaks

Modified scripts/notion-fetch/exportDatabase.ts to preserve manual line breaks (Shift+Enter) from Notion
Converts newline characters (\n, \u2028, \u2029) to HTML   tags
Applied to rich_text arrays, title blocks, captions, and code blocks
Ensures consistent line break preservation across all block types

Issue #48: Spacing Adjustments

Updated src/css/custom.css to reduce paragraph and list spacing
Reduced paragraph margin-bottom from ~1rem to 0.5rem
Reduced list margin-bottom to 0.75rem
Added nested list spacing adjustments
Scoped to .theme-doc-markdown to avoid affecting other components

Testing

✅ All existing Vitest tests pass (13/13 in runFetchPipeline.test.ts)
✅ Linting and formatting applied with no errors
✅ Pre-commit hooks passed successfully
✅ No breaking changes to existing functionality

Manual Testing Needed

Visual verification of CSS spacing on docs pages with paragraphs and lists
Before/after screenshots for CSS changes (to be added to PR comments)
Test with a Notion page containing manual line breaks to verify they render correctly

Notes

CSS changes are scoped to avoid affecting landing pages, admonitions, tables, and other components
The manual line break feature works with MDX/Docusaurus which supports inline HTML ( )
Pre-existing ESLint security warnings in exportDatabase.ts are unrelated to these changes

Closes #47
Closes #48

luandro · 2025-10-23T20:43:27Z

Testing Update

Added comprehensive test coverage for line break preservation in commit f4e7f66:

✅ 6 new test cases covering all line break scenarios
✅ Tests for \n, \u2028, and \u2029 character conversion
✅ Tests for rich_text, captions, and code blocks
✅ All tests passing (8/8 in exportDatabase.test.ts)

Visual Comparison Needed

The CSS spacing changes in src/css/custom.css (Issue #48) require before/after screenshots for visual verification.

To capture screenshots:

1. Revert CSS changes temporarily:

git stash
# Or checkout the CSS file from main:
# git checkout main -- src/css/custom.css

2. Start dev server:

bun run dev

3. Capture BEFORE screenshots:

# Example for a docs page with paragraphs and lists
bun scripts/screenshot-prs.ts --url /docs/overview --name before-spacing

4. Re-apply CSS changes:

git stash pop
# Or re-checkout this branch's version:
# git checkout fix/preserve-line-breaks-and-spacing -- src/css/custom.css

5. Capture AFTER screenshots:

# Same page as before
bun scripts/screenshot-prs.ts --url /docs/overview --name after-spacing

6. Upload screenshots:

Edit this comment
Drag and drop screenshots/before-spacing.png and screenshots/after-spacing.png
Preview to verify images display correctly
Save comment

Expected Changes

The CSS modifications reduce vertical spacing to match Notion's layout:

Paragraph spacing: ~1rem → 0.5rem
List spacing: reduced to 0.75rem
List item spacing: reduced to 0.25rem
Nested list spacing: 0.25rem top/bottom margins

The visual difference should show more compact, readable content that better matches the source Notion pages.

github-actions · 2025-10-24T08:15:47Z

🚀 Preview Deployment

Your documentation preview is ready!

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

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

_{Built with commit 4c90b1b}

luandro · 2025-10-31T20:51:05Z

Code Review Summary

What This PR Does

This PR addresses two separate but related issues in the content rendering pipeline:

Issue #47 - Manual Line Breaks Preservation:

Modifies extractTextFromBlock() in exportDatabase.ts to convert newline characters (\n, \u2028, \u2029) to HTML   tags
Applied consistently across rich_text arrays, title blocks, captions, and code blocks
Adds 6 comprehensive test cases covering various line break scenarios including Unicode separators

Issue #48 - Spacing Alignment:

Updates custom.css to reduce paragraph spacing from ~1rem to 0.5rem
Reduces list margins to better match Notion's visual rhythm
All changes scoped to .theme-doc-markdown to avoid affecting other components

How It Solves the Issues

Line Breaks: The regex replacement .replace(/[\n\u2028\u2029]/g, " \n") ensures Shift+Enter line breaks in Notion are preserved through the export pipeline and render correctly in the final documentation
Spacing: CSS margin adjustments align the visual spacing between paragraphs and lists with Notion's tighter layout, improving consistency between authoring and published experience

Potential Issues & Considerations

Strengths:

✅ Comprehensive test coverage (224 lines of new tests)
✅ Proper scoping with .theme-doc-markdown to avoid side effects
✅ Handles Unicode line separators (U+2028, U+2029) correctly
✅ All existing tests pass (13/13)

Areas to Watch:

⚠️ PR fix(docs): align docs spacing with notion #51 Duplicate: This PR includes spacing changes that overlap with PR fix(docs): align docs spacing with notion #51 (also about spacing). If both merge, there could be conflicting CSS rules
⚠️ Manual Testing Needed: As noted in the PR description, visual verification of spacing changes should be performed with screenshots
⚠️ Security Warning: Pre-existing ESLint security warnings in exportDatabase.ts are noted as unrelated but should be addressed separately

Code Quality:

Clean, focused changes with good test coverage
Follows existing code patterns
Proper error handling for edge cases (multiple consecutive line breaks)

Recommendation: ✅ Approve - Good implementation with solid test coverage. Just coordinate with PR #51 to avoid CSS conflicts.

luandro · 2025-11-05T18:37:09Z

@codex pull from main resolving conflicts and review this PR making sure it's ready for merge.

chatgpt-codex-connector · 2025-11-05T18:43:39Z

Summary

Centralized HTML line break conversion by introducing shared constants and expanding replacements to cover Windows-style \r\n and standalone \r sequences across rich text, titles, captions, and code exports. scripts/notion-fetch/exportDatabase.tsL17-L18 scripts/notion-fetch/exportDatabase.tsL218-L279
Added vitest cases that validate CRLF and CR handling so exported content continues to render   tags for Windows-authored Notion blocks. scripts/notion-fetch/exportDatabase.test.tsL320-L390

Testing

⚠️ bunx vitest run scripts/notion-fetch/__tests__/exportDatabase.test.ts (fails: npm registry returned 504 while fetching vitest)

View task →

chatgpt-codex-connector

💡 Codex Review

comapeo-docs/scripts/notion-fetch/exportDatabase.ts

Lines 293 to 304 in 1b7eeb4

    
           function analyzeBlock(block: Record<string, any>): BlockAnalysis { 
        
             const blockType = block.type || "unknown"; 
        
             const textContent = extractTextFromBlock(block); 
        
             const hasContent = textContent.length > 0 && textContent.trim() !== ""; 
        
             const hasChildren = 
        
               block.has_children || (block.children && block.children.length > 0); 
        
             const childrenCount = hasChildren ? block.children?.length || 0 : 0; 
        
             return { 
        
               type: blockType, 
        
               hasContent, 
        
               contentLength: textContent.length,

Avoid counting HTML   in content scoring

Manual line breaks are now converted to " \n" inside extractTextFromBlock, but analyzeBlock immediately uses the mutated string to compute contentLength. Each former newline now contributes six extra characters, so blocks with many line breaks (especially code blocks) will score much higher than before and can exceed thresholds like >50 or >100 characters without having additional textual content. This inflates the contentScore, totalTextLength, and related analytics emitted by exportNotionDatabase, defeating the purpose of those metrics. Consider measuring length before injecting   or strip the HTML tags when calculating scores.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

github-actions · 2025-11-06T00:42:54Z

🧹 Preview Deployment Cleanup

The preview deployment for this PR has been cleaned up.

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

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

digidem deleted a comment from github-actions bot Oct 31, 2025

This was referenced Oct 31, 2025

fix(docs): align docs spacing with notion #51

Draft

fix: render notion soft line breaks #50

Closed

luandro marked this pull request as draft November 5, 2025 13:36

luandro marked this pull request as ready for review November 5, 2025 20:27

chatgpt-codex-connector bot reviewed Nov 5, 2025

View reviewed changes

luandro added 4 commits November 5, 2025 19:39

fix(notion): preserve manual line breaks

5dd501d

test(notion): add regression coverage for line breaks

665fb3b

test(notion): add introduction markdown inspection

cc88150

style(css): match paragraph and list spacing with Notion

d63c759

luandro force-pushed the fix/preserve-line-breaks-and-spacing branch from 7fe544a to d63c759 Compare November 5, 2025 22:42

luandro added 5 commits November 5, 2025 19:55

test(notion): avoid requiring Notion env at import time

79b34e7

test(notion): lazily import markdown helpers

d67081c

test(notion-fetch): decouple introduction markdown check

3b55ee1

test(notion-fetch): decouple introduction markdown check

f2f9d0c

test(notion-fetch): decouple introduction markdown check

4c90b1b

luandro merged commit bb8f021 into main Nov 6, 2025
4 checks passed

luandro deleted the fix/preserve-line-breaks-and-spacing branch November 6, 2025 00:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: preserve manual line breaks and match Notion spacing #57

fix: preserve manual line breaks and match Notion spacing #57

Uh oh!

luandro commented Oct 23, 2025

Uh oh!

luandro commented Oct 23, 2025

Uh oh!

github-actions bot commented Oct 24, 2025 •

edited

Loading

Uh oh!

luandro commented Oct 31, 2025

Uh oh!

luandro commented Nov 5, 2025

Uh oh!

chatgpt-codex-connector bot commented Nov 5, 2025

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

github-actions bot commented Nov 6, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	function analyzeBlock(block: Record<string, any>): BlockAnalysis {
	const blockType = block.type \|\| "unknown";
	const textContent = extractTextFromBlock(block);
	const hasContent = textContent.length > 0 && textContent.trim() !== "";
	const hasChildren =
	block.has_children \|\| (block.children && block.children.length > 0);
	const childrenCount = hasChildren ? block.children?.length \|\| 0 : 0;

	return {
	type: blockType,
	hasContent,
	contentLength: textContent.length,

fix: preserve manual line breaks and match Notion spacing #57

fix: preserve manual line breaks and match Notion spacing #57

Uh oh!

Conversation

luandro commented Oct 23, 2025

Summary

Changes

Issue #47: Manual Line Breaks

Issue #48: Spacing Adjustments

Testing

Manual Testing Needed

Notes

Uh oh!

luandro commented Oct 23, 2025

Testing Update

Visual Comparison Needed

To capture screenshots:

Expected Changes

Uh oh!

github-actions bot commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Preview Deployment

Uh oh!

luandro commented Oct 31, 2025

Code Review Summary

What This PR Does

How It Solves the Issues

Potential Issues & Considerations

Uh oh!

luandro commented Nov 5, 2025

Uh oh!

chatgpt-codex-connector bot commented Nov 5, 2025

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

github-actions bot commented Nov 6, 2025

🧹 Preview Deployment Cleanup

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Oct 24, 2025 •

edited

Loading