diff --git a/doc/doxygen/riot.doxyfile b/doc/doxygen/riot.doxyfile
index 13efa260def2e4bb07419f552f552ce31dbb7da8..7acd89e9a2acb985a8c68c25c7ef567c6ab4a802 100644
--- a/doc/doxygen/riot.doxyfile
+++ b/doc/doxygen/riot.doxyfile
@@ -759,7 +759,8 @@ INPUT = ../../doc.txt \
../../boards \
../../drivers \
../../sys \
- src/
+ src/ \
+ src/mainpage.md
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
diff --git a/doc/doxygen/src/mainpage.md b/doc/doxygen/src/mainpage.md
new file mode 100644
index 0000000000000000000000000000000000000000..a0331f2390b10e0d7c4644cc3173a04e7f035232
--- /dev/null
+++ b/doc/doxygen/src/mainpage.md
@@ -0,0 +1,245 @@
+RIOT Documentation {#mainpage}
+==================
+
+[TOC]
+
+RIOT in a nutshell {#riot-in-a-nutshell}
+==================
+RIOT is an open-source microkernel-based operating system, designed to match
+the requirements of Internet of Things (IoT) devices and other embedded
+devices. These requirements include a very low memory footprint (on the order
+of a few kilobytes), high energy efficiency, real-time capabilities,
+communication stacks for both wireless and wired networks, and support for a
+wide range of low-power hardware.
+
+RIOT provides a microkernel, multiple network stacks, and utilities which
+include cryptographic libraries, data structures (bloom filters, hash tables,
+priority queues), a shell and more. RIOT supports a wide range of
+microcontroller architectures, radio drivers, sensors, and configurations for
+entire platforms, e.g. Atmel SAM R21 Xplained Pro, Zolertia Z1, STM32 Discovery
+Boards etc. (see the list of
+[supported hardware](https://github.com/RIOT-OS/RIOT/wiki/RIOT-Platforms).
+Across all supported hardware (32-bit, 16-bit, and 8-bit platforms). RIOT
+provides a consistent API and enables ANSI C and C++ application programming,
+with multithreading, IPC, system timers, mutexes etc.
+
+Contribute to RIOT {#contribute-to-riot}
+==================
+RIOT is developed by an open community that anyone is welcome to join:
+ - Download and contribute your code on
+ [GitHub](https://github.com/RIOT-OS/RIOT). You can read about how to
+ contribute [in our GitHub
+ Wiki](https://github.com/RIOT-OS/RIOT/wiki/Contributing-to-RIOT).
+ - [Subscribe](http://lists.riot-os.org/mailman/listinfo/users) to
+ users@riot-os.org to ask for help using RIOT or writing an application for
+ RIOT (or to just stay in the loop). A searchable archive of this list is
+ available at the
+ [RIOT user Gmane newsgroup](http://news.gmane.org/gmane.os.riot.user)
+ - [Subscribe]((http://lists.riot-os.org/mailman/listinfo/devel) to
+ devel@riot-os.org to follow and discuss kernel and network stack
+ developement, or hardware support. A searchable archive of this list is
+ available at the
+ [RIOT devel Gmane newsgroup](http://news.gmane.org/gmane.os.riot.devel)
+ - Follow us on [Twitter](https://twitter.com/RIOT_OS) for news from the RIOT
+ community.
+ - Contact us on IRC for live support and discussions:
+ [irc.freenode.org #riot-os](irc://irc.freenode.org/riot-os)
+
+
+The quickest start {#the-quickest-start}
+==================
+You can run RIOT on most IoT devices, on open-access testbed hardware (e.g.
+IoT-lab), and also directly as a process on your Linux/FreeBSD/OSX machine (we
+call this the `native` port). Try it right now in your terminal window:
+
+~~~~~~~{.sh}
+git clone git://github.com/RIOT-OS/RIOT.git # assumption: git is pre-installed
+git checkout <LATEST_RELEASE>
+cd RIOT
+./dist/tools//tapsetup/tapsetup # create virtual Ethernet
+ # interfaces to connect to RIOT
+cd examples/default/
+make all
+make term
+~~~~~~~
+
+... and you are in the RIOT shell!
+Type `help` to discover available commands. For further information see the
+[README of the `default` example](https://github.com/RIOT-OS/RIOT/tree/).
+
+To use RIOT directly on your embedded platform, and for more hands-on details
+with RIOT, see [TODO: link to getting started guide].
+
+Before that, skimming through the next section is recommended (but not
+mandatory).
+
+Structure {#structure}
+=========
+
+This section walks you through RIOT's structure. Once you understand this
+structure, you will easily find your way around in RIOT's code base.
+
+RIOT's code base is structured into five groups.
+
+<!-- TODO: add graphic -->
+
+ - The kernel (`core`)
+ - Platform specific code (`cpu`; `boards`)
+ - Device drivers (`drivers`)
+ - Libraries and network code (`sys`; `pkg`)
+ - Applications for demonstrating features and for testing (`examples`;
+ `tests`)
+
+In addition RIOT includes a collection of scripts for various tasks (`dist`) as
+well as a predefined environment for generating this documentation (`doc`).
+
+The structural groups are projected onto the directory structure of RIOT, where
+each of these groups resides in one or two directories in the main RIOT
+directory.
+
+The following list gives a more detailed description of each of RIOT's
+top-level directories:
+
+core
+----
+This directory contains the actual kernel. The kernel consists of the
+scheduler, inter-process-communication (messaging), threading, thread
+synchronization, and supporting data-structures and type definitions.
+
+See @ref core for further information and API documentations.
+
+boards
+------
+The platform dependent code is split into two logic elements: CPUs and boards,
+while maintaining a strict 1-to-n relationship, a board has exactly one CPU,
+while a CPU can be part of n boards. The CPU part contains all generic, CPU
+specific code (see below).
+
+The board part contains the specific configuration for the CPU it contains.
+This configuration mainly includes the peripheral configuration and
+pin-mapping, the configuration of on-board devices, and the CPU's clock
+configuration.
+
+On top of the source and header files needed for each board, this directory
+additionally may include some script and configuration files needed for
+interfacing with the board. These are typically custom flash/debug scripts or
+e.g. OpenOCD configuration files. For most boards, these files are located in a
+`dist` sub-directory of the board.
+
+See here @ref boards for further information.
+
+cpu
+---
+For each supported CPU this directory contains a sub-directory with the name of
+the CPU. These directories then contain all CPU specific configurations, such
+as implementations of power management (LPM), interrupt handling and vectors,
+startup code, clock initialization code and thread handling (e.g. context
+switching) code. For most CPUs you will also find the linker scripts in the
+`ldscripts` sub-directory.
+
+In the `periph` sub-directory of each CPU you can find the implementations of
+the CPU's peripheral drivers like SPI, UART, GPIO, etc. See @ref driver_periph
+for their API documentation.
+
+Many CPUs share a certain amount of their code (e.g. all ARM Cortex-M based
+CPUs share the same code for task switching and interrupt handling). This
+shared code is put in its own directories, following a `xxxxx_common` naming
+scheme. Examples for this is code shared across architectures (e.g.
+`cortexm_common`, `msp430_comon`) or code shared among vendors (e.g.
+`kinetis_common`).
+
+See @ref cpu for more detailed informtation.
+
+drivers
+-------
+This directory contains the drivers for external devices such as network
+interfaces, sensors and actuators. Each device driver is put into its own
+sub-directory with the name of that device.
+
+All of RIOT's device drivers are based on the peripheral driver API (e.g. SPI,
+GPIO, etc.) and other RIOT modules like the `xtimer`. This way the drivers are
+completely platform agnostic and they don't have any dependencies into the CPU
+and board code.
+
+See @ref drivers for more details.
+
+sys
+---
+RIOT follows the micro-kernel design paradigm where everything is supposed to
+be a module. All of these modules that are not part of the hardware abstraction
+nor device drivers can be found in this directory. The libraries include data
+structures (e.g. bloom, color), crypto libraries (e.g. hashes, AES) ,
+high-level APIs (e.g. Posix implementations), memory management (e.g. malloc),
+the RIOT shell and many more.
+
+See @ref sys for a complete list of available libraries
+
+sys/net
+-------
+The `sys/net` sub-directory needs to be explicitly mentioned, as this is where
+all the networking code in RIOT resides. Here you can find the network stack
+implementations (e.g. the GNRC stack) as well as network stack agnostic code as
+header definitions or network types.
+
+See @ref net for more details on networking code.
+
+pkg
+---
+RIOT comes with support for a number of external libraries (e.g.
+[OpenWSN](http://www.openwsn.org/),
+[microcoap](https://github.com/1248/microcoap)). The way they are included is
+that RIOT ships with a custom Makefile for each supported library that
+downloads the library and optionally applies a number of patches to make it
+work with RIOT. These Makefiles and patches can be found in the `pkg`
+directory.
+
+See @ref pkg for a detailed description on how this works.
+
+examples
+--------
+Here you find a number of example applications that demonstrate certain
+features of RIOT. The default example found in this directory is a good
+starting point for anyone who is new to RIOT.
+
+For more information best browse that directory and have a look at the
+`README.md` files that ship with each example.
+
+tests
+-----
+Many features/modules in RIOT come with their own test application, which are
+located in this directory. In contrary to the examples these tests are mostly
+focusing on a single aspect than on a set of features. Despite for testing, you
+might consider these tests also for insights on understanding RIOT.
+
+dist & doc
+----------
+All the tooling around RIOT can be found in these two folders.
+
+`doc` contains the doxygen configuration and also contains the compiled doxygen
+output after running `make doc`.
+
+Lastly, the `dist` directory contains tools to help you with RIOT. These
+include
+the serial terminal application `pyterm`, generic scripts for flashing,
+debugging, reseting (e.g. support for [OpenOCD](http://openocd.org/),
+[Jlink](https://www.segger.com/jlink_base.html)), as well as code enabling easy
+integration to open testbeds such as the [IoT-LAB](https://www.iot-lab.info/).
+Furthermore you can find here scripts to do all kind of code and style checks.
+
+<!--
+Further information {#further-information}
+===================
+*TBD*
+
+Idea for this section: just name each of RIOT's main features/concepts and link
+to an appropriate page with further information:
+ - Create an application
+ - Networking
+ - The `main()` function
+ - Make system
+ - Include modules
+ - Threading
+ - Choose the right stack size
+ - IPC
+ - Auto initialization
+-->
diff --git a/doc/doxygen/src/mainpage.txt b/doc/doxygen/src/mainpage.txt
deleted file mode 100644
index 66505b344badd49fa3abbda093de43cc2a4e989a..0000000000000000000000000000000000000000
--- a/doc/doxygen/src/mainpage.txt
+++ /dev/null
@@ -1,191 +0,0 @@
-/*! \mainpage RIOT Documentation
- *
- * \section overview Overview
- *
- * RIOT is an operating system designed for the particular requirements of Internet
- * of Things (IoT) scenarios. This requirements comprise a low memory footprint,
- * high energy efficiency, real-time capabilities, a modular and configurable
- * communication stack, and support for a wide range of low-power devices. RIOT
- * provides a microkernel, utilities like cryptographic libraries, data structures
- * (bloom filters, hash tables, priority queues), or a shell, different network
- * stacks, and support for various microcontrollers, radio drivers, sensors, and
- * configurations for entire platforms, e.g. Zolertia Z1 or STM32 Discovery
- * Boards.
- *
- * The microkernel itself comprises thread management, a priority-based scheduler,
- * a powerful API for inter-process communication (IPC), a system timer, and
- * mutexes.
- *
- * In order to build an application or library with RIOT, you need first to
- * download the source code ([Getting the source
- * code](https://github.com/RIOT-OS/RIOT/wiki/Introduction#wiki-getting-the-source-code)). This contains - besides the
- * before mentioned features - also some example applications (located in the
- * `examples` subdirectory) and a sample Makefile you may use for your own
- * project. This Makefile template shows you how to compile and link your application
- * against RIOT ([Compiling RIOT](https://github.com/RIOT-OS/RIOT/wiki/Introduction#wiki-compiling-riot)).
- *
- * If you want to use RIOT directly with your embedded platform, you need to
- * install the corresponding toolchain for the deployed microcontroller ([ARM
- * based platforms](https://github.com/RIOT-OS/RIOT/wiki/Introduction#wiki-platforms-based-on-arm), [TI MSP430 based
- * platforms](https://github.com/RIOT-OS/RIOT/wiki/Introduction#wiki-platforms-based-on-ti-msp430)).
- *
- * ###Native RIOT - Run RIOT on your PC!
- *
- * As a special platform, you will find a CPU and board called `native` in the
- * repository. This target allows you to run RIOT as a process on Linux on most
- * supported hardware platforms. Just set CPU and BOARD to `native` in your
- * application's Makefile, call `make`, and execute the resulting elf-file. Further
- * documentation about the native port can be found in `cpu/native/README`.
- *
- * \subsection structure Structure
- *
- * The RIOT repository contains the following ten subdirectories:
- * * boards
- * * core
- * * cpu
- * * dist
- * * doc
- * * drivers
- * * examples
- * * pkg
- * * sys
- * * tests
- *
- * The `boards` directory provides the configurations and initialization code for
- * supported IoT platforms. In `core` you can find the kernel, while `cpu`
- * comprises microcontroller specific implementations like startup and exception
- * handling code. The directory `dist` contains a template for an application's Makefile
- * and external utilities like the terminal program `pyterm` or a script to build
- * your own toolchain for ARM microcontrollers. Not very surprisingly you will find
- * the (doxygen) documentation in `doc` and peripheral driver code in `drivers`.
- * The `examples` directory provides some exemplary applications, `pkg` includes
- * Makefiles to integrate external libraries into RIOT, and `sys` system libraries
- * as well as the implementation of the network stacks which are located in
- * `sys/net`. Finally, the subdirectory `tests` contains test applications,
- * including also a few expect scripts to automatically validate some of them.
- *
- * \section features Special features
- *
- * ####The build system
- *
- * RIOT uses GNU make as build system. The simplest way to compile and link a
- * application (application or library) with RIOT, is to set up a Makefile providing
- * at least the following variables:
- * * APPLICATION
- * * BOARD
- * * RIOTBASE
- *
- * and an instruction to include the `Makefile.include`, located in RIOT's root
- * directory. `APPLICATION` should contain the (unique) name of your application, `BOARD`
- * specifies the platform the application should be built for by default, and
- * `RIOTBASE` specifies the path to your copy of the RIOT repository (note, that
- * you may want to use `$(CURDIR)` here, to give a relative path). You can use Make's
- * `?=` operator in order to allow overwriting variables from the command line. For
- * example, you can easily specify the target platform, using the sample Makefile,
- * by invoking make like this:
- *
- * \code
- * make BOARD=iotlab-m3
- * \endcode
- *
- * Besides typical targets like `clean`, `all`, or `doc`, RIOT provides the special
- * targets `flash` and `term` to invoke the configured flashing and terminal tools
- * for the specified platform. These targets use the variable `PORT` for the serial
- * communication to the device. Neither this variable nor the targets `flash` and
- * `term` are mandatory for the native port.
- *
- * Some RIOT directories contain special Makefiles like `Makefile.base`,
- * `Makefile.include` or `Makefile.dep`. The first one can be included into other
- * Makefiles to define some standard targets. The files called `Makefile.include`
- * are used in `boards` and `cpu` to append target specific information to
- * variables like `INCLUDES`, setting the include paths. `Makefile.dep` serves to
- * define dependencies.
- *
- * Learn more about the build system in the
- * [Wiki](https://github.com/RIOT-OS/RIOT/wiki/The-Make-Build-System)
- *
- * ####Including modules
- *
- * By default a RIOT application comprises only the applications' code itself, the kernel,
- * and platform specific code. In order to use additional modules, such as a
- * particular device driver or a system library, you have to append the modules'
- * names to the USEMODULE variable. For example, to build a application using the SHT11
- * temperature sensor and 6LoWPAN network stack, your Makefile needs to contain
- * these lines:
- * \code
- * USEMODULE += sht11
- * USEMODULE += gnrc_udp
- * \endcode
- * To contribute a new module to RIOT, your module's Makefile needs to set the
- * variable `MODULE` to a unique name. If the module depends on other modules, this
- * information needs to be added to RIOT's `Makefile.dep`.
- *
- * ####The main function
- *
- * After the board is initialized, RIOT starts two threads: the idle thread and the
- * main thread. The idle thread has the lowest priority and will run, whenever no
- * other thread is ready to run. It will automatically use the lowest possible
- * power mode for the device. The main thread - configured with a default priority
- * that is right in the middle between the lowest and the highest available
- * priority - is the first thread that runs and calls the main function. This
- * function needs to be defined by the application.
- *
- * ####Choosing the right stack size
- *
- * Choosing the right stack size for a new thread is not an easy, but a very
- * crucial task. Since memory is usually a scarce resource in IoT scenarios,
- * one most be careful not to assign too much stack to a single thread.
- * However, if you allocate too little memory for a stack, your application
- * will probably crash. The minimum stack size depends also on some RIOT
- * internal structs and is hardware dependent. In order to help developers
- * finding the right stack size, RIOT defines some typical stack sizes in
- * `cpu_conf.` (which should be provided by the implementation for all
- * supported MCUs). The constants for these stack sizes are
- *
- * * `THREAD_STACKSIZE_IDLE`
- * * `THREAD_STACKSIZE_DEFAULT`
- * * `THREAD_EXTRA_STACKSIZE_PRINTF`
- * * `THREAD_STACKSIZE_MAIN`
- *
- * and can be used by including `kernel.h`. ARM based platforms additionally
- * define `THREAD_EXTRA_STACKSIZE_PRINTF_FLOAT`, because newlibs printf
- * implementation uses more memory for printing floating point numbers.
- *
- * `THREAD_STACKSIZE_IDLE` is the stack size for the idle thread and
- * probably the smallest sensible stack size. `THREAD_STACKSIZE_DEFAULT`
- * is a default size for any typical thread, _not_ using printf.
- * `THREAD_EXTRA_STACKSIZE_PRINTF` defines additional stack space needed if the
- * thread needs to call printf (which requires additional memory when using
- * newlib). `THREAD_STACKSIZE_MAIN` is the stack size for the main thread
- * and probably a good size for your application. (Note, that on most
- * non-newlib dependent platforms this will probably equal
- * `THREAD_STACKSIZE_DEFAULT`.
- *
- * ####The IPC
- *
- * Like any microkernel system, RIOT has an IPC API that enables data exchange
- * between modules or a single module and the kernel. This API is documented in
- * the [doxygen documentation](http://riot-os.org/api/). The IPC can be used in
- * several ways, such as synchronous or asynchronous, blocking or non-blocking,
- * with or without a message queue. In the default case, a thread does not have a
- * message queue. Hence, messages sent in a non-blocking manner are lost, when the
- * target thread is not in receive mode. A thread may set up a message queue using
- * the [corresponding function](http://riot-os.org/api/group__kernel__msg.html),
- * but has to provide the memory for this queue itself.
- *
- * ####Auto-init
- *
- * Most modules require initialization before they can be used. In some cases the
- * initialization function does not require a parameter. For these modules you
- * might use the auto-init feature by adding a line like
- * ```
- * USEMODULE += auto_init
- * ```
- * to your Makefile. Auto-init calls all module initialization functions with a
- * `void` parameter just before the main thread gets executed.
- *
- * \section info_sec Community
- *
- * Whether you are looking for help with writing an application for RIOT, want to learn more about it, or just stay in the loop you are invited to join the RIOT-users mailing list. For developers who want to participate and contribute to the kernel development or integrate new MCU and platform support the [RIOT-devel mailing list](http://lists.riot-os.org/mailman/listinfo/devel) is the right place.
- *
- */