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
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 —