Bug Report: format:docs removes empty lines inside code blocks

Open Beginner friendly
#22,167 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
83/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
javascript, node.js

Research direction

Start with scripts/fix-mdx.js, especially removeMultipleEmptyLines, and inspect how it handles fenced code blocks compared with normalizeIndentation. Run node scripts/fix-mdx.js contents/docs/workflows/transactional-emails/python.mdx and review the diff. Done means formatting leaves lines inside fenced code blocks unchanged, including the two blank lines before @shared_task.

Written by the indexing model from the issue text.

Description

Report

pnpm format:docs runs scripts/fix-mdx.js. The script changes the content of fenced code blocks.

removeMultipleEmptyLines in scripts/fix-mdx.js removes each empty line that follows another empty line. It does not skip fenced code blocks. normalizeIndentation in the same file skips code blocks, but this function does not.

Python style (PEP 8) puts two empty lines before a top-level function. The script changes those two empty lines to one, so a Python example in the docs no longer follows PEP 8.

To reproduce, on master at 31163f30ae:

  1. Run node scripts/fix-mdx.js contents/docs/workflows/transactional-emails/python.mdx.
  2. Run git diff.

Result: the script removes one of the two empty lines before @shared_task in the Python code block, near line 141:

 RETRYABLE_CODES = {"network_error", "idempotency_key_in_flight", "throttled", "delivery_unavailable"}

-
 @shared_task(bind=True, max_retries=5)

The script also adds an empty line between <details> and <summary> on each page that has a <details> block. That change is not in a code block, but it changes more lines than an author expects from a formatter.

Technical info

  • Script: scripts/fix-mdx.js, run by pnpm format:docs
  • Node 24, Linux

Expected outcome, or solution

The script does not change lines between the opening and closing fence of a code block.

Dominant language
TypeScript
Stars
1.2k
Forks
952
Avg merge
1d 17h
Merged PRs (30d)
747

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from PostHog/posthog.com

All issues in PostHog/posthog.com

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.