Skip to content

{@example} may breakout of fenced code block, insufficient backticks #4284

Closed

Description

@jonasfj

In markdown you can have more than 3 backticks to make a fenced code block.

This can be necessary, if the thing you are trying has 3 backticks inside it.

When injecting examples dartdoc should probably increment backticks depending on the content inserted.

This is not a critical bug, but would be nice to fix. And probably super easy to do.


AI Explanation

{@example} always emits a 3-backtick fence, corrupting examples that contain a fence

_injectExamples wraps the example content in a hard-coded 3-backtick fence:

return '```$language\n$content$trailing```';

return '```$language\n$content$trailing```';

Per CommonMark a fenced
code block ends at the first closing fence of at least the opening length, so any
example whose content contains a ``` line truncates the block early and leaks
the remainder of the example into the page as markdown.

Reproduction

example/readme_snippet.md:

// #region snippet
Install it:

```console
dart pub add foo
```
// #endregion snippet

Referenced from a doc comment:

/// {@example /example/readme_snippet.md#snippet}
class Foo {}

Actual output — the block closes at the ```console line's matching fence,
so only Install it: is inside the code block and dart pub add foo plus the
trailing fence escape into the rendered page:

```md
Install it:

```console
dart pub add foo
```

Expected — a fence long enough to contain the content:

````md
Install it:

```console
dart pub add foo
```
````

Suggested fix

Compute the fence length from the content instead of hard-coding 3:

final longest = RegExp(r'^\s*(`{3,})', multiLine: true)
    .allMatches(content)
    .map((m) => m[1]!.length)
    .fold(2, max);
final fence = '`' * max(3, longest + 1);
return '$fence$language\n$content$trailing$fence';

Why it matters

This isn't hypothetical — it hits any example file that is itself markdown, any
Dart example containing a doc comment with a code sample, and any example
containing a string literal with a fence. The failure is silent: no warning, just
broken documentation.

Activity

  1. added
    type-bugIncorrect behavior (everything from a crash to more subtle misbehavior)
    P3A lower priority bug or feature request
    on Sep 17, 2026
  2. FMorschel commented on Sep 17, 2026

    @FMorschel
  3. jonasfj commented on Sep 20, 2026

    @jonasfj
    MemberAuthor

    @FMorschel please file as separate issues, this is unrelated to dartdoc.

    If there are markdown parsing issues in package:markdown file against that package.

  4. szakarias commented on Sep 22, 2026

    @szakarias
    Collaborator

    Fixed in #4285

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P3A lower priority bug or feature requesttype-bugIncorrect behavior (everything from a crash to more subtle misbehavior)

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions