readme_helper

Description:

readme helper

readme_helper #
Helpful code generator for the README and other markdown files.
Quickstart #
1. Install or update readme_helper:
flutter pub global activate readme_helper
copied to clipboard
2. Start using these "magical" comment commands:
Insert code example from external file:
<!-- #code path/to/file.dart -->

Create a table of contents based on used headlines:
<!-- #toc -->

This will include another markdown file:
<!-- #include path/to/other_markdown.md -->
copied to clipboard
3. Run readme_helper for current project:
flutter pub global run readme_helper
copied to clipboard

Table of Contents #
Quickstart
Motivation
Usage
Commands

Code embedding
Table of Contents generation
Include markdown files
Generate line breaks


Motivation #
A good documentation is the key in connecting package creators and developers.
Embedding code examples is essential, but they might deprecate over the time.
This tool enables you to use external code files, the correctness is ensured by your IDE.
Additional tooling like markdown inclusion or table of contents generation, will help you save time.
Usage #
The readme_helper is a Dart application, that can be installed or updated with:
flutter pub global activate readme_helper
copied to clipboard
You can run the readme_helper with:
flutter pub global run readme_helper
copied to clipboard
It will take care of all markdown files within the current directory and it's sub-directories.
Alternately you can process only a single file with:
flutter pub global run readme_helper path/to/file.md
copied to clipboard
Commands #
You can specify commands by using HTML comments in your markdown files. Each readme_helper command starts with a #:
<!-- #command argument -->
copied to clipboard
Code embedding #
You can embed external files by defining the relative path to it.
<!-- #code path/to/code.dart -->
copied to clipboard
This will add a code block with the content of that file.
Scope comments
You can use comments to control the part of the external file shown.
import 'dart:math';

// #begin
class MyClass {
// #skip
int someMethod() {
return Random().nextInt(1);
}
// #resume

String interestingMethod() {
return 'Foo';
}
}
// #end
copied to clipboard
This will add the following code block:
class MyClass {
...

String interestingMethod() {
return 'Foo';
}
}
copied to clipboard
Indentions
By indenting the // #begin scope comments, you can hint to remove leading whitespace.
class AnotherClass {
// #begin
int importantMethod() {
return 42;
}
// #end
}
copied to clipboard
This will add the following code block:
int importantMethod() {
return 42;
}
copied to clipboard
Table of Contents generation #
The readme_helper will scan all markdown headlines (## and ###) and generate a table of contents.
# project_name

<!-- #toc -->

## chapter a
### section 1
### section 2

## chapter b
### section 3
### section 4
copied to clipboard
This will create something like this:

chapter a

section 1
section 2


chapter b

section 3
section 4



Include markdown files #
You can include parts from other files into the current markdown file, by using an include:
<!-- #include path/to/part.md -->
copied to clipboard
Generate line breaks #
By default you can't have more then one new line. For esthetics you might want to extend this limit.
<!-- #space 2 -->
copied to clipboard
This will generate line breaks with &nbsp; characters.