Copying a tutorial code block often gives you broken code

[nohwnd]

I went through the whole tutorial copying only the code blocks, which is how a lot of people read a tutorial. The suite breaks on 8 pages and needs 10 manual repairs that the tutorial never asks for.

Two causes.

A diff block copies both the old line and the new line. We declare diff-add and diff-remove as magicComments in docusaurus.config.js, and style them in custom.css with ::before for the + and -. Pseudo element content is not in the DOM, so the copy button hands you the removed lines and the added lines as plain text with nothing to tell them apart.

Worst one is the -Force block in tutorial/6-code-coverage/1-measuring.mdx. Copy gives you this:

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

and the whole suite dies, on a page that says "Still all green":

Missing ')' in function parameter list.
Tests Passed: 1, Failed: 23, Skipped: 0, Inconclusive: 0, NotRun: 0

Same shape in tutorial/3-organising-tests/2-choosing-what-runs.mdx (twice), tutorial/4-mocking/3-verifying-calls.mdx, tutorial/2-testing-a-module/3-public-functions.mdx and tutorial/4-mocking/1-a-real-dependency.mdx. That last one is the nastiest because it parses fine. You keep the hard coded array and add Get-PlanetData, so Get-Planet returns 10 planets and 3 tests fail on the page titled "Nothing should have broken".

A title="path" on a block that is not the whole file. The tutorial teaches "titled block means save it to that path", and then breaks that rule 12 times, either with a # ... the four existing It blocks ... placeholder or with a three line excerpt.

• tutorial/2-testing-a-module/1-setup.mdx, the FunctionsToExport = '*' block titled Planetarium.psd1, replaces the generated 132 line manifest
• tutorial/6-code-coverage/2-closing-the-gaps.mdx, three $config.CodeCoverage.* lines titled test.ps1, deletes the whole runner
• tutorial/4-mocking/3-verifying-calls.mdx, two blocks with placeholders, you lose BeforeAll and the mock

The one I care about most is in tutorial/6-code-coverage/2-closing-the-gaps.mdx. Saving that block drops the four TestDrive tests and the run still passes, 22 tests and 95% coverage, no error at all. The missed commands table then points at a different line than the page says. So we silently teach the wrong lesson on the page about reading coverage output.

What I want to do:

• swizzle the copy button so it skips lines marked code-block-diff-remove-line
• print the complete file under every title=, and drop the title from excerpt blocks
• mark the illustration blocks as illustrations, they currently look exactly like steps and pasting them gives errors like You cannot call a method on a null-valued expression that mention neither Pester nor the block

Pure diff-add over a complete file is fine, tutorial/7-ci/1-test-script.mdx already does that and copies clean.

🤖