Do not copy the removed lines from a diff code block

[nohwnd]

Fix #459

I went through the tutorial copying only the code blocks and the suite broke on 8 pages. Two causes, both fixed here.

The copy button handed you the removed lines. diff-add and diff-remove are declared as magicComments, and the + and - glyphs come from CSS ::before. Pseudo element content is not in the DOM, so a copied diff block contained the old line and the new line with nothing to tell them apart. On the coverage page that gave two $Name parameters and killed the whole suite with Missing ')' in function parameter list.

src/theme/CodeBlock/Buttons/CopyButton now re-provides the code block context with the diff-remove lines dropped, so only the copy button sees the trimmed code. Rendering is untouched, the red lines stay on the page.

A title="path" on a block that is not the whole file. The tutorial teaches that a titled block is a file to save, so an excerpt or a # ... the four existing It blocks ... placeholder under that title deletes the rest of the file. Complete files are now printed where the title stays, and the title is gone where the block really is an excerpt.

Also moved the "this is an illustration" notes in front of the blocks they apply to instead of after them.

Verification

Built the site and drove the real copy button in the browser, capturing what it writes to the clipboard.

The -Force block on tutorial/6-code-coverage/1-measuring.mdx, before and after:

# before, what you got from the copy button
        [string] $Name = '*'
        [string] $Name = '*',

        [switch] $Force

# after
        [string] $Name = '*',

        [switch] $Force

The three blocks where I replaced a placeholder with the complete file were diffed against the files the tutorial actually produces, taken from a full run of the tutorial. All three match exactly:

MATCH   Planetarium/Public/Get-Planet.Mocking.Tests.ps1
MATCH   Planetarium/Private/Get-PlanetData.Tests.ps1
MATCH   Planetarium/Public/Export-PlanetReport.Tests.ps1

Checked that a block with no diff copies exactly as before, and that the removed lines still render in red.

🤖

[nohwnd]

@fflaten this is a stack of five. I ran the tutorial end to end against 6.1.0 a few times, each time reading it the way a different kind of reader would, and these are the things that came out of it. Each PR is based on the previous one, so merge from the bottom up:

1. pester/docs#464 — Do not copy the removed lines from a diff code block, for pester/docs#459 — Copying a tutorial code block often gives you broken code
2. pester/docs#465 — Fix four wrong statements in the tutorial, for pester/docs#460 — Four wrong statements in the tutorial
3. pester/docs#466 — Refresh the tutorial output blocks against 6.1.0, for pester/docs#461 — Tutorial output blocks were written against 6.0.0
4. pester/docs#467 — Say how the exit code behaves in the CI we actually build, for pester/docs#462 — The exit code lesson does not survive into the CI workflow
5. pester/docs#468 — Give returning v5 users the assertion rename map, for pester/docs#463 — Give returning v5 users the assertion rename map

Only the first one touches the theme. It is a wrapper swizzle on the copy button so that a diff block stops putting the old line and the new line on your clipboard together. That one is worth looking at properly, the rest is content and you can skim it.

The reason it matters: reading the tutorial by copying the blocks, which is what most people do, breaks the suite on 8 pages. The worst case is silent. On tutorial/6-code-coverage/2-closing-the-gaps.mdx you lose four tests and the run still passes at 95%, so the page about reading coverage output teaches you the wrong lesson without ever going red.

Two notes on reviewing:

Netlify only built a preview for #464, the other four target a branch rather than main so they get no check. All five build locally, and I verified the copy button on the #464 deploy preview rather than only on my machine.

The tutorial itself still ends at 26 tests and 100% coverage. The blocks where I replaced a # ... the four existing It blocks ... placeholder with the whole file were diffed against the files a real run of the tutorial produces, so they are not retyped.

Happy to squash the content ones into a single PR if five is too many, I split them by the kind of change mostly so the theme change is reviewable on its own. LMK.

🤖