Skip to content

docs: add worked examples for the remaining forms - #59

Draft
mcanouil wants to merge 4 commits into
mainfrom
docs/worked-examples
Draft

mcanouil wants to merge 4 commits into
mainfrom
docs/worked-examples

Conversation

@mcanouil

Copy link
Copy Markdown
Owner

The examples page showed a section, a div, a line range, a dedent and a shift. It now covers the rest, filled in place, with three more sample files under docs/_examples/.

The whole file with no fragment, a single line, the canonical shift-heading-level-by spelling rather than the shift alias the page always used, a negative shift that promotes headings, a heading pushed past level one, what happens to links inside an included file, a missing target, and a URL. The last two print their calls rather than running them, so the site's own build neither fails nor fetches anything.

A heading pushed past level one becomes a bold paragraph and loses its identifier, which the page states and its example relies on.

Two corrections to the reference page came out of the reading, and one is worth attention.

The validation table promised that every failure leaves the surrounding document intact and removes only the shortcode. A target that cannot be read or fetched stops the render instead. pandoc.mediabag.fetch raises rather than returning nothing, so the extension's if not fetched guard and the error message beneath it are never reached. Running the fetch directly under the pandoc Quarto ships confirms it. The fix belongs in the Lua, as a pcall around the fetch, and until then the page says what happens.

The dedent note said an unrecognised value is read as if the attribute had not been written, without a warning. The first half is still true and the second is not: the pinned validator coerces only true and false, so the four other spellings the extension honours are reported, and so is anything it ignores.

Verified with a full quarto render docs, no warnings and no unresolved cross-references, markdownlint-cli2 clean, all five reference anchors resolving, and no duplicate identifier on the page. Quoted messages were copied from real failed renders rather than reconstructed.

The page showed a section, a div, dedenting, a demoted heading, a line
range and a `.md` file. It did not show a whole-file include, a single
line, a promoted heading, a heading pushed past level one, the full
`shift-heading-level-by` spelling, a path written inside the included
file, a missing target or a URL.

Three supporting files join `_examples/`, so no identifier reaches the
page twice. The missing-target and URL sections print their call rather
than run it, so the site's own build does not fail and does not wait on
a network request.
Pandoc raises rather than returning nothing when a fetch fails, so the guard the extension holds for that case is never reached and the render dies. The validation table said the shortcode was removed and the document left intact, which is true of every other failure and false of this one.

Also correct the dedent note. The extension still honours yes, no, 1 and 0, and the pinned schema validator now reports every spelling but true and false, so the note saying nothing is reported is no longer right.
My dedent rewrite said every spelling but true and false is reported even though the extension honours it. The extension honours four extra spellings and reads anything else as if the attribute had not been written, which the previous text said and my replacement dropped.

The failure sentence covered the two shift rows, where the content is included anyway with no shift or a truncated one, so nothing is removed there.

Name the sections that print their call rather than counting from the end, and describe the page's sample files as they are now.
Both run only when their attribute is written, and only the shortcode escaping is unconditional for a markdown file. The sentence read as though all three always happen.

Also correct the overlap claim: several examples do pull the same content, and no identifier repeats because extracting a div drops the wrapper that carries it.
@mcanouil mcanouil self-assigned this Sep 18, 2026
@mcanouil mcanouil added the Type: Documentation 📝 Issues related to documentation label Sep 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Type: Documentation 📝 Issues related to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant