diff --git a/docs/analysis_tab.md b/docs/analysis_tab.md
index 83f066dd39..8c82d0e5f1 100644
--- a/docs/analysis_tab.md
+++ b/docs/analysis_tab.md
@@ -11,24 +11,23 @@ can help you avoid code mistakes and to enforce best practices.
 
 Here is the list of analyzers:
 
-> -   Security:
->     :   -   Transaction origin: Warns if tx.origin is used
->         -   Check effects: Avoid potential reentrancy bugs
->         -   Inline assembly: Use of Inline Assembly
->         -   Block timestamp: Semantics maybe unclear
->         -   Low level calls: Semantics maybe unclear
->         -   Block.blockhash usage: Semantics maybe unclear
->
-> -   Gas & Economy:
->     :   -   Gas costs: Warns if the gas requirements of the functions
->             are too high
->         -   This on local calls: Invocation of local functions via
->             this
->
-> -   Miscellaneous:
->     :   -   Constant functions: Checks for potentially constant
->             functions
->         -   Similar variable names: Checks if variable names are too
->             similar
->
+Security:
+-   Transaction origin: Warns if tx.origin is used
+-   Check effects: Avoid potential reentrancy bugs
+-   Inline assembly: Use of Inline Assembly
+-   Block timestamp: Semantics maybe unclear
+-   Low level calls: Semantics maybe unclear
+-   Block.blockhash usage: Semantics maybe unclear
 
+
+Gas & Economy:
+-   Gas costs: Warns if the gas requirements of the functions
+    are too high
+-   This on local calls: Invocation of local functions via
+    this
+
+Miscellaneous:
+-   Constant functions: Checks for potentially constant
+    functions
+-   Similar variable names: Checks if variable names are too
+    similar
diff --git a/docs/conf.py b/docs/conf.py
index 4e5b322071..d0fc17d69f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -303,3 +303,5 @@ source_parsers = {'.md': CommonMarkParser}
 #         'enable_auto_doc_ref': True,
 #     }, True)
 #     app.add_transform(AutoStructify)
+
+http://
diff --git a/docs/debugger_tab.md b/docs/debugger_tab.md
index c689ff1ceb..004941baf1 100644
--- a/docs/debugger_tab.md
+++ b/docs/debugger_tab.md
@@ -8,8 +8,5 @@ features).
 
 ![image](images/remix_debuggertab.png)
 
-For more information about debugging, click on the following link:
-.. toctree::
-   :maxdepth: 2
-
-tutorial_debug.md
+For more information about debugging, see the [Tutorial on debugging transactions with Remix
+](http://remix.readthedocs.io/en/latest/tutorial_debug.html)
diff --git a/docs/file_explorer.md b/docs/file_explorer.md
index 30170793cd..50bf145fc0 100644
--- a/docs/file_explorer.md
+++ b/docs/file_explorer.md
@@ -20,7 +20,7 @@ the right:
 Create new File
 ---------------
 
-Creates a new file in the browser explorer.
+Creates a new `untitled.sol` file in Remix.
 
 Add Local File
 --------------
@@ -31,16 +31,22 @@ the Remix browser storage.
 Publish to Gist
 ---------------
 
-Publishes files from the browser storage to an anonymous public gist.
+Publishes all files from the browser folder to a gist.
+Gist API has changed in 2018 and it unfortunately requires users to be authenticated to be able to publish a gist.
 
-Copy to another instance
+Under https://github.com/settings/tokens select Generate new token.
+Then check only Create gists checkbox and generate a new token.
+
+Then paste it in Remix (right panel/Settings tab) and click Save. Now you should be able to use the feature.
+
+Copy to another Remix instance
 ------------------------
 
 Enables you to copy files from the browser storage to another instance
 (URL) of Remix.
 
-Connect to Localhost
+Connect your filesystem to Remix
 --------------------
 
-Allows to use file located in your file system (see
-../tutorial\_remixd\_filesystem).
+Allows to sync between Remix and your local file system (see
+[more about RemixD][http://remix.readthedocs.io/en/latest/tutorial_connect_remix_with_your_filesystem.html]).
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000000..f7b9a743e5
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,66 @@
+Welcome to Remix documentation!
+===============================
+
+Remix is a powerful, open source tool that helps you write Solidity contracts straight from the browser.
+Written in Javascript, Remix supports both usage in the browser or locally.
+
+Remix also supports testing, debugging and deploying of smart contracts and much more.
+
+Our Remix project with all its features is available
+at [remix.ethereum.org](http://remix.ethereum.org). More information about how to use it can be found in this
+documentation and the source code of the project is available at [our GitHub repository]
+(https://github.com/ethereum/remix-id).
+
+This set of documents covers instructions on how to use Remix and some tutorials to help you get started.
+
+.. quick-start:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Quick start
+
+   solidity_editor
+   compile_tab
+   quickstart_javascript_vm
+
+
+.. deploy and test:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Deploy and test
+
+   run_tab
+   udapp
+
+.. _other-remix-features:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Other Remix features
+
+   file_explorer
+   debugger_tab
+   analysis_tab
+   terminal
+
+.. _tutorials and workshops:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials and workshops
+
+   workshop_Building_smart_contracts_with_Remix
+   tutorial_connect_remix_with_your_filesystem
+   tutorial_debug
+   tutorial_import
+   tutorial_mist
+
+.. _code-contribution-guide:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Code contribution guide
+
+   code_contribution_guide
+   support
diff --git a/docs/quickstart_javascript_vm.md b/docs/quickstart_javascript_vm.md
index f67c1e6df2..d9fdc356f2 100644
--- a/docs/quickstart_javascript_vm.md
+++ b/docs/quickstart_javascript_vm.md
@@ -2,8 +2,7 @@ Quick Start using the JavaScript VM
 ===================================
 
 There are 3 type of environments Remix can be plugged to:
-`Javascript VM`, `Injected provider`, or `Web3 provider`. (see
-../run\_tab)
+`Javascript VM`, `Injected provider`, or `Web3 provider`. (for details see [Running transactions](http://remix.readthedocs.io/en/latest/run_tab.html))
 
 Both `Web3 provider` and `Injected provider` require the use of an
 external tool.
@@ -26,8 +25,7 @@ should have 100 ether.
 
 Sample contract
 ---------------
-::
-
+``` {.sourceCode .none}
 pragma solidity ^0.4.16;
 
 contract testContract {
@@ -49,6 +47,7 @@ contract testContract {
         return value;
     }
 }
+```
 
 This contract is very basic. The goal is to quickly start to create and
 to interact with a sample contract.
diff --git a/docs/run_tab.md b/docs/run_tab.md
index 718f0c29dc..045aaa3de3 100644
--- a/docs/run_tab.md
+++ b/docs/run_tab.md
@@ -49,7 +49,7 @@ This section contains the list of compiled contracts and 2 actions:
     deployed contract. There's no check at this point, so be careful
     when using this feature, and be sure you trust the contract at that
     address.
-    
+
 -   `Create` send a transaction that deploys the selected contract. When
     the transaction is mined, the newly created instance will be added
     (this might take several seconds). Note that if the `constructor`
@@ -120,8 +120,7 @@ Input parameters are `1` and
 all these transactions are created using the value of the accounts
 `account{0}`.
 
-::
-
+``` {.sourceCode .none}
 {
 "accounts": {
     "account{0}": "0xca35b7d915458ef540ade6068dfe2f44e8fa733c"
@@ -276,3 +275,4 @@ all these transactions are created using the value of the accounts
     ]
 }
 }
+```
diff --git a/docs/support.md b/docs/support.md
index 785229e9db..6bdd96968a 100644
--- a/docs/support.md
+++ b/docs/support.md
@@ -3,7 +3,7 @@ Support chat
 
 We know that blockchain ecosystem is very new and that lots of information is scattered around the web.
 That is why we created a community support chat where we and other users try to answer your questions if
-you get stuck using Remix. Please, join [the chat](https://gitter.im/ethereum/remix) and ask community for help.
+you get stuck using Remix. Please, join [the Remix channel](https://gitter.im/ethereum/remix) and ask community for help.
 
 For anyone who is interested in developing a custom plugin for Remix or who wants to contribute to the codebase,
 we opened [another channel](https://gitter.im/ethereum/remix-dev) specially for developers working on Remix tool.
diff --git a/docs/support_tab.md b/docs/support_tab.md
index 8eb2714aa1..90ed7a47b2 100644
--- a/docs/support_tab.md
+++ b/docs/support_tab.md
@@ -1,9 +1,9 @@
-Support
-=======
+Support tab in Remix
+======================
 
 This section provides a link to Remix Issues where users can report a
 bug or suggest a feature, as well as providing other useful links. It
-also displays a [Remix developers'
+also displays a [Remix support
 channel](http://gitter.im/ethereum/remix)
 
 ![image](images/remix_supporttab.png)
diff --git a/docs/tutorial_connect_remix_with_your_filesystem.md b/docs/tutorial_connect_remix_with_your_filesystem.md
index 48a217296c..7c27f208be 100644
--- a/docs/tutorial_connect_remix_with_your_filesystem.md
+++ b/docs/tutorial_connect_remix_with_your_filesystem.md
@@ -19,10 +19,10 @@ and `Remixd`.
 Be sure the user executing Remix has read/write permission on the
 folder.
 
-> **warning**
+**Warning!**
 
-> Remixd provides full read and write access to the given folder for any
-> application that can access the TCP port 65520 on your local host.
+`Remixd provides full read and write access to the given folder for any
+application that can access the TCP port 65520 on your local host.`
 
 From `Remix IDE`, you will need to activate the connection.
 
diff --git a/docs/tutorial_debug.md b/docs/tutorial_debug.md
index 7091317c23..31b33fa96e 100644
--- a/docs/tutorial_debug.md
+++ b/docs/tutorial_debug.md
@@ -1,5 +1,5 @@
-Debugging a Transaction
-=======================
+Tutorial on debugging transactions with Remix
+===============================================
 
 The goal of this tutorial is to explain how to debug transaction using
 Remix.
diff --git a/docs/tutorial_import.md b/docs/tutorial_import.md
index c3d86073ee..18fc416030 100644
--- a/docs/tutorial_import.md
+++ b/docs/tutorial_import.md
@@ -6,8 +6,8 @@ This tutorial will show you how to import local and external files.
 The compilation result will also contain contracts implemented in the
 imported files.
 
-For a detailed explanation of the `import` keyword see the `Solidity`
-[documentation](https://solidity.readthedocs.io/en/develop/layout-of-source-files.html?highlight=import#importing-other-source-files)
+For a detailed explanation of the `import` keyword see the
+[Solidity documentation](https://solidity.readthedocs.io/en/develop/layout-of-source-files.html?highlight=import#importing-other-source-files)
 
 Importing a local file
 ----------------------
diff --git a/docs/tutorial_mist.md b/docs/tutorial_mist.md
index afc3d260c1..568cf34b46 100644
--- a/docs/tutorial_mist.md
+++ b/docs/tutorial_mist.md
@@ -186,7 +186,7 @@ and here is the front end:
 function donate () {
     var donation = contractspec.at(document.getElementById('contractaddress').value)
     donation.donate({
-        from: document.getElementById('fromGive').value, 
+        from: document.getElementById('fromGive').value,
         value: document.getElementById('valueGive').value
     }, function (error, txHash) {       
         tryTillResponse(txHash, function (error, receipt) {
diff --git a/docs/udapp.md b/docs/udapp.md
index 2260783b0b..1ef2261153 100644
--- a/docs/udapp.md
+++ b/docs/udapp.md
@@ -4,18 +4,22 @@ Deployed contracts
 This section in the Run tab contains a list of deployed contracts to interact with through autogenerated UI of the deployed contract (also called udapp).
 
 Several cases apply:
-:   -   The called function is declared as `constant` or `pure` in
+
+   -   The called function is declared as `constant` or `pure` in
         Solidity. The action has a blue background, clicking it does not
         create a new transaction. Clicking it is not necessary because
         there are not state changes - but it will update the return
         value of the function.
+
     -   The called function has no special keywords. The action has a
         light red background, clicking on does create a new transaction.
         But this transaction cannot accept any amount of Ether.
+
     -   The called function is declared as `payable` in Solidity. The
         action has a red background, clicking it does create a new
         transaction and this transaction can accept value.
 
+
 For more information about Solidity modifier, see [Solidity
 modifier](http://solidity.readthedocs.io/en/develop/miscellaneous.html?highlight=pure#modifiers)
 .