Let me help you with your readme!

For over two years now, I am creating Flutter and Dart packages. In this time I learned one important thing:

Providing an awesome readme file is the key, to enable developers leverage your piece of technology.

I spent hours in providing the best possible documentation for my packages. But the more content I produced, the more confusing the readme file got. Also my code examples deprecated over time.

To counter that, I’ve written a Dart script that

• automatically embeds code examples from external Dart files, so the IDE can check for syntax errors
• creates the “Table of Contents” based on used markdown headlines, to create large but clear readme files
• uses markdown includes, to structure the readme in multiple files

This month I rewritten that script into the Dart app readme_helper, so every Flutter an Dart developer can use these features in own projects.

The readme_helper is a markdown code generator that looks for special type of HTML comments in your markdown files:

<!-- #code path/to/file.dart -->

The code generator will replace the comment with the code included. If the external file changes, it will update it.

For the scoped code embedding, you can place marker comments:

This will create the following:

And whenever the API of my examples breaks, the Dart analyzer in my IDE will hint on errors in my file.dart .

You can install the readme_helper with

flutter pub global activate readme_helper

and run the readme_helper with

flutter pub global run readme_helper .

For more information read the package readme, to discover all features.

I’ll hope you enjoy it.

Until next time
— Felix —