diff --git a/README.md b/README.md
new file mode 100644
index 0000000..398ead4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,144 @@
+CONTENTS OF THIS FILE
+---------------------
+
+ * Introduction
+ * Requirements
+ * Installation
+ * Recommended Modules
+ * Configuration
+ * Maintainers
+
+
+INTRODUCTION
+------------
+
+The Google Analytics Referrer is a lightweight system for gathering referrers
+detected by Google Analytics.
+
+ * For a full description of the module, visit the project page:
+   https://www.drupal.org/project/google_analytics_referrer
+   or
+   http://www.vacilando.org/article/google-analytics-referrer
+
+ * To submit bug reports and feature suggestions, or to track changes:
+   https://www.drupal.org/project/issues/google_analytics_referrer
+
+
+REQUIREMENTS
+------------
+
+This module requires no modules outside of Drupal core.
+
+
+RECOMMENDED MODULES
+-------------------
+
+To have the site tracked by Google Analytics. You may use the Drupal module
+Google Analytics or other method.
+
+ * Google Analytics - https://www.drupal.org/project/google_analytics
+
+INSTALLATION
+------------
+
+ * Install the Google Analytics Referrer module as you would normally install a
+   contributed Drupal module. Visit https://www.drupal.org/node/895232 for
+   further information.
+
+
+CONFIGURATION
+--------------
+
+You will need Client ID and Client Secret.
+
+    1. Visit the Google Developers Console, create a new project, enable
+       "Analytics API", under "APIs & auth -> Credentials" create an Oauth 2.0
+       Client ID with application type "Web application" (configure consent
+       screen as you wish).
+    2. Configure Client ID settings: Redirect URIs
+       (http://example.com/admin/config/system/google_analytics_referrer/authentication)
+       and JavaScript origins (http://example.com)
+    3. Copy the Client ID and Client Secret.
+
+Authenticate a Google Analytics profile for your website (there will be a Status
+page warning until you do that)
+    1. Navigate to Administration > Modules and enable the module.
+    2. Navigate to Configuration > System > Google Analytics Referrer > GA
+       authentication.
+    3. Enter Client ID and Client Secret. Save.
+
+You can configure this module at Configuration -> System -> Google Analytics
+Referrer (but defaults will work fine for a start)
+
+You can check the stats retrieval progress and other relevant information at
+Configuration -> System -> Google Analytics Referrer -> Dashboard
+
+Set access permissions for Google Analytics Referrer at Configuration ->
+System -> Google Analytics Referrer -> Permissions
+
+Make sure your usual Drupal cron is functioning well (for testing, you can also
+run it manually directly from the provided Dashboard page)
+
+Set access permissions for Google Analytics Referrer at Configuration -> Google
+Analytics Referrer -> Permissions
+Usage
+
+Go to Configuration -> Content authoring -> Text formats and enable the Google
+Analytics Referrer filter for the input type you will be using
+
+Either enable block Google Analytics Referrer, or place [gar] in any page or
+custom block. If you need to show referrers for a page other than the current
+one, use: [gar|path/without/wrapping/slashes] (e.g. [gar|node/1])
+
+To show all referrers of a website, use the following special tag: [gar|all]
+
+If you wish to load the referrers using PHP, e.g. if you are integrating it in
+your template, use the output of function
+
+```
+google_analytics_referrer_display(($path = '', $number = '', $removevague = '', $removeprecise = '').
+```
+
+Again, to show referrer for the actual page, use echo
+
+```
+google_analytics_referrer_display();,
+```
+
+for some other page use e.g.
+
+```
+echo google_analytics_referrer_display('node/145');,
+```
+
+and to show the total count for the whole site use echo
+
+```
+google_analytics_referrer_display('all');.
+```
+
+In [gar] token or if calling the function
+
+```
+google_analytics_referrer_get_sum_per_path()
+
+```
+
+directly, you may specify a node in any way -- either by its node/nid path, or
+by its alias my/alias or even with its language prefix nl/node/nid or
+nl/my/alias. Even old aliases are counted in (requires the Redirect module)!
+All these are summed together when retrieving page views from Google Analytics
+(it's always the same node). However, this is not true about non-node paths --
+counts for e.g. nl/custom/path and custom/path are always counted separately
+because they may be completely different pages (it would be rather difficult
+to tell).
+
+
+MAINTAINERS
+-----------
+
+ * Tomas Fulopp (Vacilando) - https://www.drupal.org/u/vacilando
+
+Supporting organization:
+
+ * Vacilando - https://www.drupal.org/node/2367917
diff --git a/README.txt b/README.txt
deleted file mode 100644
index 57e81fc..0000000
--- a/README.txt
+++ /dev/null
@@ -1,9 +0,0 @@
-Google Analytics Referrer is a scalable, lightweight system for gathering referrers detected by Google Analytics.
-
-Installation, demo and tips are at https://vacilando.org/gar
-Drupal project page is at https://drupal.org/project/issues/google_analytics_referrer
-If you encounter a problem or need support, see https://drupal.org/project/issues/google_analytics_referrer
-
-Author: Tomas Fulopp (Vacilando)
-The author can be contacted at https://vacilando.org/contact for paid customizations of this and other Drupal modules.
-Development of this module is sponsored by Vacilando ( https://vacilando.org/ )