diff --git a/README.md b/README.md
index c2118bd1..7b6bcefa 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,48 @@
-# gxmods
-Documentation for Opera GX mods
+# What are Opera GX Mods?
+
+![GXMods](images/gxmods.jpg)
+
+GX Mods are a collection of customizations that allow users to create unique browsing experiences within Opera GX. With GX Mods, users can modify the browser's appearance, sounds, music, theme, wallpaper and even web content using web modding and shaders.
+
+Users can install multiple mods and choose which elements to enable, giving them full control over the desired final effect.
+
+
+## What can be done with mods?
+
+With mod customization, authors have complete control over what is included and how deep the modifications go. Mods can range in modifications from small keyboard sound packs to *Mega Mods* that incorporate all possible changes.
+
+The following areas provide ample opportunities to unleash creativity:
+
+1. Background music - dynamic music that fits browsing
+2. Keyboard sounds - mechanical keyboard, typewriter, or sci-fi terminal sounds
+3. Browser sounds - opening and closing tabs, clicking, flipping switches, etc.
+4. Wallpaper - light and dark versions (static and animated)
+5. Theme - color theme for light and dark mode
+6. Web modding - tuning web pages to create unique appearances
+7. Shaders - applying visual effects to the whole screen while browsing.
+
+## How to load sample mods?
+
+As a quick start you can try some of the [sample mods](mods) provided.
+
+1. Open Extensions view (opera:extensions)
+2. Enable Developer mode in top right corner
+3. Click Load unpacked and point to directory with manifest.json
+4. Loaded mod will shown in Mods view (opera:mods)
+
+## How to create mods?
+
+[Documentation](documentation/mods.md)
+
+## How to build and share mod?
+
+1. Open extensions view (opera:extensions)
+2. Enable Developer mode in top right corner
+3. Click Pack extension and point to directory with manifest.json
+
+This will produce .CRX file that you can share with friends. Drag and drop it into Opera GX to install that mod.
+
+## Will there be a store?
+
+Yes.
+
diff --git a/documentation/images/loaded_mod_template.jpg b/documentation/images/loaded_mod_template.jpg
new file mode 100644
index 00000000..47f9937a
Binary files /dev/null and b/documentation/images/loaded_mod_template.jpg differ
diff --git a/documentation/mods.md b/documentation/mods.md
new file mode 100644
index 00000000..bb0a76e2
--- /dev/null
+++ b/documentation/mods.md
@@ -0,0 +1,59 @@
+# Disclaimer
+
+Both Opera GX Mods and documentation are still actively developed. 
+
+# Quick start
+
+[Mod_Template](Mod_Template) is created to give you a quick start into creating mods. It showcases all capabilities and is a convenient starting point to create own mods. Load it in Opera GX, look around, modify things and have fun.
+
+![Loaded Mod Template](images/loaded_mod_template.jpg)
+
+# Anatomy of GX Mod
+
+Each mod consists of
+
+1. manifest.json - defines what's included in mod as well as name, author, version etc.
+2. resources - sounds, images, videos, css, shaders etc. 
+
+## manifest.json 
+
+See [manifest.json](Mod_Template/manifest.json) from Mod_Template. It should be self explanatory. In case you make a mistake, Opera GX will show you an error when trying to load such a mod.
+
+### Background music
+
+Opera GX uses [vertical remixing](https://gamemaker.io/en/blog/compose-video-game-music) to achive dynamic music in browser. However it doesn't mean you need to provide multiple music files. If only one is provided it will work as well. In such a case you can do a little trick and list the same file more than once. This will result in an increased volume when users is active in browser.
+
+### Keyboard sounds
+
+You can provide a single sound for a key or a list of sounds that will be played in provided order. You can keep keys empty which means that no sound will be played or remove key and in that case default sound will be played.
+
+### Browser sounds
+
+The same rules apply as in keyboard sounds.
+
+### Wallpaper
+
+Provide light and dark version. Mods can't block users from switching between light and dark mode.
+
+### Theme
+
+Provide both light and dark version. Mods can't block users from switching between light and dark mode.
+
+### Shaders
+
+More than one shader can be provided in single mod. [Read more about shaders](shaders.md).
+
+### Web modding
+
+Those are basically CSSes that can be applied to web pages. Multiple pages can be modified with a single mod. Opera GX exposes primary and secondary color if you want to make web pages follow UI colors (see [opera.css](Mod_Template/webmodding/opera.css))
+
+# Best practices
+
+Random order.
+
+1. Limit size of resouces.
+2. Music and sounds should follow volume from Mod_Template otherwise it won't be a good experience for users.
+3. Keep resources in dedicated subdirectores.
+4. Use 512x512 good looking image for icon. 
+
+
diff --git a/images/gxmods.jpg b/images/gxmods.jpg
new file mode 100644
index 00000000..4f1a5324
Binary files /dev/null and b/images/gxmods.jpg differ