diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7ca5030
--- /dev/null
+++ b/README.md
@@ -0,0 +1,187 @@
+# pattern-expander
+[![Build Status](https://travis-ci.org/DevWurm/pattern-expander.svg?branch=master)](https://travis-ci.org/DevWurm/pattern-expander)
+[![Coverage Status](https://coveralls.io/repos/github/DevWurm/pattern-expander/badge.svg?branch=master)](https://coveralls.io/github/DevWurm/pattern-expander?branch=master)
+[![Gitter](https://badges.gitter.im/DevWurm/pattern-expander.svg)](https://gitter.im/DevWurm/pattern-expander?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
+
+A JavaScript library to expand a pattern with permutations of specified values.
+
+`pattern-expander` expands a pattern by applying a set of rules to it.
+An example:
+The pattern `pattern-a-b` and the rules
+```yaml
+Pattern 1:
+ variable: a
+ values:
+ - 1
+ - 2
+
+Pattern2:
+ variable: b
+ values:
+ - 3
+ - 4
+```
+would expand to the following results:
+```
+pattern-1-3
+pattern-1-4
+pattern-2-3
+pattern-2-4
+```
+It's great for generating date lists, file lists, etc.
+
+## Installation
+To use `pattern-exoander` in your project, just install it via `npm`:
+```shell
+npm install -S pattern-expander
+```
+
+## Usage
+To expand a pattern import the `expand` function and the `Rule` constructor from the `pattern-expander` module:
+```javascript
+import {expand, Rule} from 'pattern-expander';
+```
+After this, [set up a list of rules](#create-rules) and [expand your pattern string(s)](#expand-patterns).
+
+### Create Rules
+To create rules, create an Array, containing `Rule` objects.
+The `Rule` constructor can be used in two different ways:
+* `Rule(variable, values, padChar)`:
+ * `variable {String}`: the variable, which should be substituted
+ * `values {[String]}`: the values, which should be used for expansion
+ * `padChar {String} [Optional]`: The character used for padding, if the variable block occupies more characters than the value (Default: `'0'`)
+* `Rule(variable, from, to, padChar)`:
+ * `variable {String}`: the variable, which should be substituted
+ * `from {Number}`: the beginning of the numeric range used for expansion
+ * `to {Number}`: the end of the numeric range used for expansion
+ * `padChar {String} [Optional]`: The character used for padding, if the variable block occupies more characters than the value (Default: `'0'`)
+
+**Example:**
+creating two rules, which expand the variable `a` with the values `"a"` and `"b"`, padded with `x`es and the variable `b` with the values `"1"` and `"2"`
+```javascript
+const rules = [new Rule('a', ['a', 'b'], 'x'), new Rule('b', 1, 2)];
+```
+
+### Expand Patterns
+If you have set up your rules, just pass your pattern string (which may contain your variable(s)) or even an array of pattern strings to the `expand` function with the signature `expand(pattern, rules)`. Consecutive occurrences of a variable are treated as a variable block and are just substituted once with the value and may be padded with the `padChar`, if the value is shorter than the variable block. If the value is longer than the variable block, it will be inserted completely.
+
+**Example:**
+```javascript
+const pattern = 'aa-b';
+
+const result = expand(pattern, rules);
+/*
+result:
+[
+ 'xa-1',
+ 'xa-2',
+ 'xb-1',
+ 'xb-2'
+]
+ */
+```
+
+### Example
+A practical example:
+You want to write a function, which prints out all the days of the year.
+```javascript
+import {expand, Rule} from 'pattern-expander';
+
+function printYear(year) {
+ const pattern = 'yyyy-mm-dd';
+
+ // setup the needed rules
+ const yearRule = new Rule('y', [String(year)]);
+ const monthRule = month => new Rule('m', [String(month)]);
+ const days28DaysRule = new Rule(`d`, 1, 28);
+ const days30DaysRule = new Rule(`d`, 1, 30);
+ const days31DaysRule = new Rule(`d`, 1, 31);
+
+ // generate an Array containing the numbers 1 -12 and map the
+ // expansion rules for the months onto it and expand them
+ const months = Array.from(new Array(12), (val, key) => key + 1)
+ .map(month => {
+ let rules = [yearRule, monthRule(month)];
+
+ // add the correct rule for the month
+ if (month == 1) {
+ rules.push(days28DaysRule);
+ } else if ((month <= 7 && month % 2 == 0) || (month > 7 && month % 2 != 0)) {
+ rules.push(days30DaysRule);
+ } else {
+ rules.push(days31DaysRule);
+ }
+
+ return rules
+ })
+ .map(rules => expand(pattern, rules));
+
+ // flatten the month array
+ const days = [].concat.apply([], months);
+
+ // output the days
+ days.forEach(day => console.log(day));
+}
+```
+calling `printYear(2016)` would now generate the following ouput (excerpt):
+```
+2016-01-01
+2016-01-02
+2016-01-03
+2016-01-04
+2016-01-05
+2016-01-06
+2016-01-07
+2016-01-08
+2016-01-09
+2016-01-10
+2016-01-11
+2016-01-12
+2016-01-13
+2016-01-14
+2016-01-15
+2016-01-16
+2016-01-17
+2016-01-18
+...
+2016-12-10
+2016-12-11
+2016-12-12
+2016-12-13
+2016-12-14
+2016-12-15
+2016-12-16
+2016-12-17
+2016-12-18
+2016-12-19
+2016-12-20
+2016-12-21
+2016-12-22
+2016-12-23
+2016-12-24
+2016-12-25
+2016-12-26
+2016-12-27
+2016-12-28
+2016-12-29
+2016-12-30
+2016-12-31
+```
+
+##License
+`pattern-expander` is offered under MIT License (Read LICENSE). Use it! :)
+Copyright 2016 DevWurm
+
+##Collaborating
+I really appreciate any kind of collaboration!
+You can use the [GitHub issue tracker](https://github.com/DevWurm/pattern-expander/issues) for bugs and feature requests or [create a pull request](https://github.com/DevWurm/pattern-expander/pulls) to submit
+changes. Forks are welcome, too!
+If you don't want to use these possibilities, you can also write me an email to
+devwurm@devwurm.net.
+
+## Contact
+If you have any questions, ideas, etc. feel free to contact me:
+DevWurm
+Email: devwurm@devwurm.net
+Jabber: devwurm@jabber.ccc.de
+Twitter: @DevWurm
diff --git a/package.json b/package.json
index c1062ff..007b3c8 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "pattern-expander",
- "version": "1.0.0",
+ "version": "1.0.0-beta",
"description": "Library to expand a pattern with permutations of specified values.",
"main": "lib/expander.js",
"directories": {