diff --git a/docs/Markdown.md b/docs/Markdown.md
new file mode 100644
index 000000000..5584b1d57
--- /dev/null
+++ b/docs/Markdown.md
@@ -0,0 +1,27 @@
+## What is Markdown
+
+The [wikipedia markdown entry](https://en.wikipedia.org/wiki/Markdown) introduced markdown as : 
+
+> Markdown is a lightweight markup language with plain text formatting syntax. It is designed so that it can be converted to HTML and many other formats using a tool by the same name. Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor. As the initial description of Markdown contained ambiguities and unanswered questions, many implementations and extensions of Markdown appeared over the years to answer these issues.
+
+## Markdown in Deck
+The Deck application plugin uses the [markdown-it](https://github.com/markdown-it/markdown-it) script to offer support for markdown in the cards description field.
+
+## Supported Markdown
+
+Markdown comes in may flavors. The best way to learn markdown and understand how to use it, is simply to [try it](https://markdown-it.github.io) on the original script official playground.
+That same link offers also a comprehensive list of what is supported, and what is not - rendering it unnecessary to duplicate that content in here.  
+
+[CommonMark Markdown Reference](http://commonmark.org/help/)
+
+## Known Issues
+
+As per [issue #127](https://github.com/nextcloud/deck/issues/127) Due to a known limitation of the current script to support markdown, Links that contain the `")"` character will not display well, or will break. 
+The recommended solution is to use `"<"` and `">"` to wrap those links. It should assure their integrity.
+If you come by another case of broken link, or broken display of links, please report it by opening a new issue.
+
+
+
+
+
+
diff --git a/docs/extra.css b/docs/extra.css
new file mode 100644
index 000000000..b3b4d28e1
--- /dev/null
+++ b/docs/extra.css
@@ -0,0 +1,3 @@
+.subnav ul {
+    padding-left: 20px;
+}
diff --git a/docs/index.md b/docs/index.md
deleted file mode 100644
index d3880397a..000000000
--- a/docs/index.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Welcome to MkDocs
-
-For full documentation visit [mkdocs.org](https://mkdocs.org).
-
-## Commands
-
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs help` - Print this help message.
-
-## Project layout
-
-    mkdocs.yml    # The configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.
diff --git a/docs/index.md b/docs/index.md
new file mode 120000
index 000000000..32d46ee88
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1 @@
+../README.md
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index e103af839..2038a396b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,5 +1,12 @@
 site_name: Nextcloud Deck
-theme: readthedocs
-markdown_extensions:
-    - toc:
-        permalink: True
+theme:
+    name: readthedocs
+extra_css: [extra.css]
+nav:
+    - Home: index.md
+    - User documentation:
+        - Markdown composing: Markdown.md
+    - API documentation:
+        - REST API: API.md
+        - Nextcloud API: API-Nextcloud.md
+