Example - keep markdown code samples up to date

This tool updates examples in fenced code blocks in markdown files to match source files in example/ or test/, using the same #region, #endregion, and #hide markers as dartdoc's {@example} directive.

Disclaimer: This is not an officially supported Google product.

Usage

Mark a region in an example or test file:

import 'package:test/test.dart';

void main() {
  test('greets the world', () {
    // #region greeting
    final message = 'Hello, world!';
    print(message);
    // #endregion greeting
    expect(message, isNotEmpty);
  });
}

Reference the file (or #region) after @example in your markdown fence's info string:

```dart @example example/hello_world.dart#greeting
final message = 'Hello, world!';
print(message);
```

A leading / resolves from the package root; any other path resolves relative to the markdown file. Pass indent=keep (default indent=strip) to keep shared leading indentation.

Update all markdown files locally (requires Dart 3.12+):

$ dart run example@ update

Validating in CI

Check that no markdown code block is out of date:

$ dart run example@ validate

In GitHub Actions, call the reusable workflow (pinned to a commit SHA):

jobs:
  examples:
    uses: google/dart-neats/.github/workflows/validate-examples.yml@<commit-sha>

Libraries