diff --git a/Mainpage.dox b/Mainpage.dox
deleted file mode 100644
index d0d238ec5..000000000
--- a/Mainpage.dox
+++ /dev/null
@@ -1,33 +0,0 @@
-/** @mainpage Plasma Runtime
-
-Plasma Runtime components.
-The classes documented here are not C++ public libraries: they are intended to be used from QML, with the following imports:
-
-
org.kde.draganddrop
-Bindings for the Qt drag and drop system, see draganddrop
-
-org.kde.plasma.components
-Graphical components for common items such as buttons, lineedits, tabbars and so on. Compatible subset of the MeeGo components used on the N9, see plasmacomponents
-
-org.kde.plasma.core
-Bindings for libplasma functionality, such as DataEngines and FrameSvgs, see core
-
-org.kde.plasma.extras
-Extra graphical components that extend org.kde.plasma.components but are not in the standard api, see extras
-
-org.kde.qtextracomponents
-Bindings for some functionality in Qt not included in the primitive QML components set, sich as support for QImages, QPixmaps, QIcons and mouse and wheel events with screen coordinates, see qtextracomponents
-
-
-@authors
-- Marco Martin \
-- Aaron Seigo \
-
-@maintainers
-
-@licenses
-@gpl
-
-*/
-
-// DOXYGEN_SET_PROJECT_NAME = Plasma Runtime
diff --git a/README.md b/README.md
index 6c46940ac..80c80d597 100644
--- a/README.md
+++ b/README.md
@@ -2,21 +2,41 @@
The plasma framework provides the foundations that can be used to build a primary user interface, from graphical to logical components.
## Introduction
-The plasma framework is made by a library component and a runtime component:
-* libplasma: this is a library for the business logic, it manages:
-** rendering of SVG themes
-** loading of files from a certain filesystem structure: packages
-** data access: dataengines
-** loading of the plugin structure of the workspace: containments and applets
+The plasma framework provides the following:
+- A C++ library: libplasma
+- Script engines
+- QML components
+- The `plasma-shell` executable
-* QML script engine: given the data provided by an Applet or a Containment, it maps to loading of an actual QML representation of it
-* QML components: sets of QML components to provide a widget set, and to access to libplasma components, such as SVG themes and dataengines.
-* Runtime environment: the plasma-shell executable. The runtime that will load the actual workspace, it's completely controlled by QML, by itself doesn't have any UI.
+## libplasma
+This C++ library provides:
+- rendering of SVG themes
+- loading of files from a certain filesystem structure: packages
+- data access through data engines
+- loading of the plugin structure of the workspace: containments and applets
+See @ref libplasma.
+
+## Script engines
+Provides support to create applets or containments in various scripting languages.
+
+## QML components
+### org.kde.plasma.core
+
+Bindings for libplasma functionality, such as DataEngine and FrameSvg, see @ref core.
+
+### org.kde.plasma.components
+Graphical components for common items such as buttons, lineedits, tabbars and so on. Compatible subset of the MeeGo components used on the N9, see @ref plasmacomponents.
+
+### org.kde.plasma.extras
+Extra graphical components that extend org.kde.plasma.components but are not in the standard api, see @ref plasmaextracomponents.
+
+## plasma-shell
+The `plasma-shell` executable loads the actual workspace. It is completely controlled by QML and does not itself provide any user interface.
## Links
- Wiki:
- Mailing list:
-- IRC channel: #kde-devel on Freenode
+- IRC channel: #plasma on Freenode
- Git repository:
diff --git a/src/declarativeimports/core/Mainpage.dox b/src/declarativeimports/core/Mainpage.dox
index 0a7bcf4c4..567844830 100644
--- a/src/declarativeimports/core/Mainpage.dox
+++ b/src/declarativeimports/core/Mainpage.dox
@@ -1,4 +1,4 @@
-/** @mainpage Plasma Core
+/** @page core Plasma Core
import org.kde.plasma.core
diff --git a/src/declarativeimports/plasmacomponents/Mainpage.dox b/src/declarativeimports/plasmacomponents/Mainpage.dox
index 12d031bcc..926f49ba7 100644
--- a/src/declarativeimports/plasmacomponents/Mainpage.dox
+++ b/src/declarativeimports/plasmacomponents/Mainpage.dox
@@ -1,4 +1,4 @@
-/** @mainpage Plasma Components
+/** @page plasmacomponents Plasma Components
import org.kde.plasma.components
diff --git a/src/declarativeimports/plasmaextracomponents/Mainpage.dox b/src/declarativeimports/plasmaextracomponents/Mainpage.dox
index ed96489ac..566afb128 100644
--- a/src/declarativeimports/plasmaextracomponents/Mainpage.dox
+++ b/src/declarativeimports/plasmaextracomponents/Mainpage.dox
@@ -1,4 +1,4 @@
-/** @mainpage Plasma Extra Components
+/** @page plasmaextracomponents Plasma Extra Components
import org.kde.plasma.extras
diff --git a/src/plasma/Mainpage.dox b/src/plasma/Mainpage.dox
index 8cda36fcf..8e11833ec 100644
--- a/src/plasma/Mainpage.dox
+++ b/src/plasma/Mainpage.dox
@@ -1,4 +1,4 @@
-/** @mainpage Plasma libraries
+/** @page libplasma libplasma
libplasma is the core of the Plasma desktop. It provides a framework of graphical
widgets (Plasma::Applet) that can be organised into managed groupings