diff --git a/doc/doxygen/DoxygenDumuxLayout.xml b/doc/doxygen/DoxygenDumuxLayout.xml
index 2c9cf52997b0158a946f1b70b1e24da63b9b0fcf..800fe8815c81dc0b8bec660c0e2a4e3e8b96dde1 100644
--- a/doc/doxygen/DoxygenDumuxLayout.xml
+++ b/doc/doxygen/DoxygenDumuxLayout.xml
@@ -3,6 +3,7 @@
<!-- Navigation index tabs for HTML output -->
<navindex>
<tab type="mainpage" visible="yes" title=""/>
+ <tab type="pages" visible="yes" title="" intro=""/>
<tab type="modules" visible="yes" title="Models and main components" intro=""/>
<tab type="namespaces" visible="yes" title="">
<tab type="namespacelist" visible="yes" title="" intro=""/>
@@ -16,7 +17,6 @@
</tab>
<tab type="files" visible="yes" title=""/>
<tab type="examples" visible="yes" title="" intro=""/>
- <tab type="pages" visible="yes" title="" intro=""/>
</navindex>
<!-- Layout definition for a class page -->
diff --git a/doc/doxygen/Doxylocal b/doc/doxygen/Doxylocal
index ae96345c726be163b0d306fd2825742ae87eda4b..e8d9af03d9471beb67d6355d0b35fed2e14bb9bf 100644
--- a/doc/doxygen/Doxylocal
+++ b/doc/doxygen/Doxylocal
@@ -7,11 +7,14 @@ PROJECT_LOGO = @top_srcdir@/doc/logo/dumux_logo_small.png
PROJECT_NUMBER = @DUNE_MOD_VERSION@
INPUT += @srcdir@/main.md \
+ @srcdir@/installation.md \
+ @srcdir@/getting-started.md \
@srcdir@/modules.txt \
@top_srcdir@/dumux \
@srcdir@/extradoc/parameterlist.txt
USE_MDFILE_AS_MAINPAGE = @srcdir@/main.md
+TOC_INCLUDE_HEADINGS = 4
# Input filters run over content before it is parsed by Doxygen.
# - Format markdown math for Doxygen. See the documentation in
@@ -71,8 +74,8 @@ SHORT_NAMES = NO
# Settings required for doxygen-awesome theme
GENERATE_TREEVIEW = YES
TREEVIEW_WIDTH = 420
-DISABLE_INDEX = NO
-FULL_SIDEBAR = NO
+DISABLE_INDEX = NO
+FULL_SIDEBAR = NO
HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5
# Do no repeat in the description
diff --git a/doc/doxygen/getting-started.md b/doc/doxygen/getting-started.md
new file mode 100644
index 0000000000000000000000000000000000000000..bbc9c6902ac943cb7eb8ec3a64baca6d4742b9f6
--- /dev/null
+++ b/doc/doxygen/getting-started.md
@@ -0,0 +1,161 @@
+# Getting started
+
+## Installation
+
+Please follow the [installation instructions](installation.md) to install DuMux.
+
+## Running an example
+
+For this example it is assumed that you followed the installation instructions and have a folder with a similar structure:
+
+ installation folder
+ |- dune-common
+ |- build-cmake
+ |- dune/common
+ |...
+ |- dune-geometry
+ |- build-cmake
+ |- dune/geometry
+ |...
+ |- dune-grid
+ |- dune-istl
+ |- dune-localfunctions
+ |- dumux
+ |- build-cmake
+ |- test
+ |- examples
+ |- dumux
+ |...
+ |- dumux
+ |...
+
+We want to run an example, in which we first compute a single phase fluid flow field with heterogeneous permeability field, and then run a tracer transport simulation with the computed velocity field. A detailed example description can be found [here](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/tree/master/examples).
+First, we change to the example's directory:
+
+```bash
+cd build-cmake/examples/1ptracer
+```
+
+We compile the example using GNU Make (this can take one minute):
+
+```bash
+make example_1ptracer
+```
+
+And finally we run the simulation:
+
+```bash
+./example_1ptracer
+```
+
+Besides console output, DuMux produces VTK output files that can be visualised with the open source visualisation tool [Paraview](http://www.paraview.org).
+This output is shown in the figure below:
+
+
+
+## Changing runtime parameters
+
+In the config file `params.input`, we can configure runtime parameters. Let us increase the end time `TEnd` of the simulation from 5000 to 7500 seconds.
+
+```ini
+[TimeLoop]
+DtInitial = 10 # [s]
+MaxTimeStepSize = 10
+TEnd = 7500 # [s]
+```
+
+This results in the tracer travelling slightly further towards the upper end of the domain.
+
+
+`[TimeLoop]` is a parameter group containing parameters configuring the time loop. The computational grid is configured in the `[Grid]` parameter group.
+`UpperRight` defines the size (x-, y-direction) of the area and `Cells` the number of cells in x- and y-direction, for a structured cube grid.
+If the parameter `Grid.File` is specified, the grid will be read from a grid file instead (we currently support Gmsh `.msh`, DUNE grid format `.dgf` and VTK files)
+In the parameter group `[SpatialParams]`, we can define some spatially varying parameters.
+In this example, the parameter file is configured such that we can set the extent of a box-shaped lens (`LensLowerLeft`, `LensUpperRight`) with different permeability than the surrounding porous media. For example, we can decrease the size of the lens and observe how the resulting concentration field is influenced by the local permeability contrast.
+
+```ini
+[SpatialParams]
+LensLowerLeft = 0.4 0.4
+LensUpperRight = 0.6 0.6
+```
+
+We can see that this results in the tracer spreading more homogeneously in the domain.
+
+
+
+## Create your own module
+
+For the purpose of developing your own application with DuMux, we recommend creating a separate DUNE module that lists DuMux as its dependency.
+DUNE provides a script, that creates such a new module. In your installation folder run:
+
+```bash
+./dune-common/bin/duneproject
+```
+
+Follow the instructions popping up, and enter:
+
+* the name of your module (e.g. `dumux-yourmodule`)
+* the module dependencies (enter `dumux`)
+* version of your module (e.g. `0.1`)
+* your email address as maintainer of the new module
+
+To configure your new module run `dunecontrol`:
+
+```bash
+./dune-common/bin/dunecontrol --opts=dumux/cmake.opts --only=dumux-yourmodule all
+```
+
+Now you can create your own test case. Enter the `dumux-yourmodule` folder and create a new folder (e.g. `appl`), that will contain your first test case.
+
+```bash
+mkdir appl
+```
+
+An easy and fast way to get the files for your test case is to copy an existing test from DuMux.
+We copy the following files from an incompressible single fluid phase flow model test application in `dumux/test/porousmediumflow/1p/implicit/compressible/stationary`:
+
+* `main.cc`
+* `problem.hh`
+* `spatialparams.hh`
+* `params.input`
+
+To be able to configure and build your application with CMake, you need to first add the new `appl` subdirectory to the `CMakeLists.txt` file in `dumux-yourmodule`:
+
+```cmake
+add_subdirectory(appl)
+```
+
+ Inside the `appl` folder, create a new `CMakeLists.txt` and add the test case to it:
+
+```cmake
+# add a new finite volume 1p test
+dumux_add_test(NAME test_1p_compressible_stationary_tpfa
+ SOURCES main.cc
+ COMPILE_DEFINITIONS TYPETAG=OnePCompressibleTpfa)
+
+# add a symlink for the input file in the build folder
+dune_symlink_to_source_files(FILES "params.input")
+```
+
+Now you need to reconfigure the module by typing (inside the folder `dumux-yourmodule`):
+
+```bash
+cmake build-cmake
+```
+
+As the last step, build and execute your new test case:
+
+```bash
+cd build-cmake
+make build_tests
+cd appl
+./test_1p_compressible_stationary_tpfa params.input
+```
+
+This result visualized in with ParaView should look something like this:
+
+
+## Next steps
+
+To learn more about DuMux, we highly recommend the [DuMux course](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course). During the [exercises](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/tree/master/exercises) you get a deeper insight into the structure of DuMux and its different applications.
+Furthermore, DuMux contains several [documented example applications](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/examples/README.md).
diff --git a/doc/doxygen/installation.md b/doc/doxygen/installation.md
new file mode 100644
index 0000000000000000000000000000000000000000..9f8fb0b20b24ea5636fc955f0c94c8bdf624244f
--- /dev/null
+++ b/doc/doxygen/installation.md
@@ -0,0 +1,156 @@
+# Installation
+
+## Prerequisites
+
+DuMu<sup>x</sup> builds and runs on **Linux** and **Mac** operating systems.
+Installation on Windows is possible but it is definitely not something to try if you are a beginner.
+If you use Windows, we recommend the [Ubuntu bash on Windows](https://msdn.microsoft.com/commandline/wsl/).
+Alternatively, you can try to employ MinGW, Cygwin or a Linux Virtual Machine.
+
+In order to build DuMu<sup>x</sup> you need at least the following software:
+
+* C++17 compiler (GCC 9.3 or newer, Clang 10 or newer)
+* CMake (CMake 3.13 or newer)
+* pkg-config
+
+Detailed information on supported compiler and CMake versions can be found in the [DuMux handbook](/docs/#handbook).
+The following software is recommended but optional:
+
+* MPI (either OpenMPI, lam, or mpich)
+* ParaView (to visualize the results)
+* a browser (to access the GitLab instance and README files)
+* python3 with numpy (to execute a number of different scripts used for installation, testing, post-processing, etc.)
+
+
+## 1. Installation via script
+
+We provide you with a Python script that facilitates setting up a Dune/DuMux directory
+tree and configures all modules using CMake. Download [installdumux.py](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/bin/installdumux.py) and place it in a directory where you want to install Dune/DuMux. The script will create a folder "DUMUX" in which all dependencies will be downloaded and built. Note that this installation method requires Python 3.X, `wget` (for automatically downloading dependencies) and `git` (for cloning the code repositories) to be installed on your system.
+
+Run the script by typing:
+
+ python3 installdumux.py
+
+Follow the instructions printed after the script has completed successfully to verify everything works as expected.
+
+For more detailed explanation on installation and building of DuMux, please have a look below or at the [handbook](/docs/#handbook) of the latest release.
+
+
+## 2. Manual installation from source
+
+DuMux depends on [Dune](https://dune-project.org/).
+You can obtain the required Dune modules in form of binary packages for Debian, Ubuntu and openSUSE, see the [Dune binary packages](http://www.dune-project.org/binary/). The Dune releases can also be obtained as [tarballs](https://www.dune-project.org/releases/). Alternatively, you can use [Git](https://www.dune-project.org/dev/downloadgit/) and download the modules (recommended and described here). To clone the Dune core modules (minimum requirement), you can run:
+
+ for module in common geometry grid localfunctions istl; do
+ git clone -b releases/2.8 https://gitlab.dune-project.org/core/dune-$module.git
+ done
+
+Our Git repository (just like Dune's) offers anonymous read access. To clone the 3.6 release version, you can type:
+
+ git clone -b releases/3.6 https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
+
+You can clone the master branch (developer version) by typing:
+
+ git clone https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
+
+Alternatively, it is also possible to download release tarballs from [Zenodo](https://doi.org/10.5281/zenodo.2479594) or from [GitLab](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/releases).
+
+After obtaining all modules (at least the Dune core modules `dune-common`,`dune-geometry`,`dune-grid`,`dune-istl`,`dune-localfunctions` and `dumux`), DuMux is built together with other Dune modules. Assuming that the Dune core modules and DuMux are folders in the same directory
+
+ installation folder
+ |- dune-common
+ |- dune-geometry
+ |- dune-grid
+ |- dune-istl
+ |- dune-localfunctions
+ |- dumux
+
+you can configure and build the module stack with the `dunecontrol` helper script:
+
+ ./dune-common/bin/dunecontrol --opts=dumux/cmake.opts all
+
+This will create a separate build folder called `build-cmake` individually in each module. In case you want to build the module stack in a separate build folder use
+
+ ./dune-common/bin/dunecontrol --opts=dumux/cmake.opts --builddir=$(pwd)/build all
+
+More details on the Dune build system can be found in the [Dune installation notes](http://www.dune-project.org/doc/installation/). Dune and DuMux rely heavily on compiler optimization. The speed difference between running a compiler-optimized versus a non-optimized DuMux executable can easily exceed a factor of 10.
+The default `cmake.opts` in `dumux/cmake.opts` already enable compiler optimisations.
+To use debug options use `-DCMAKE_BUILD_TYPE=Debug` instead of `-DCMAKE_BUILD_TYPE=Release` in the `cmake.opts`, or
+add `set(CMAKE_BUILD_TYPE Debug)` to any `CMakeLists.txt` containing a test that you want to compile non-optimised and with debug symbols enabled.
+
+
+## 3. Install external dependencies via script
+
+There are various external libraries and modules that provide additional functionality but are
+not generally required to run DuMux. A list of external libraries and modules can be found in the [DuMux handbook](/docs/#handbook).
+DuMux contains the script `installexternal.py` which allows you to install extension from your DuMux installation directory.
+
+If you run the script with the option \-\-help
+
+ python3 dumux/bin/installexternal.py --help
+
+it will show a list of installable packages. Dune modules can be installed by adding the name of the package.
+For example, running the script by typing:
+
+ python3 dumux/bin/installexternal.py alugrid
+
+downloads the ALUGrid module `dune-alugrid` in a separate folder in your installation directory. After the download
+you can run following command to clean the CMake cache:
+
+ ./dune-common/bin/dunecontrol bexec rm -r CMakeFiles CMakeCache.txt
+
+Afterwards you can reconfigure and build DuMux with the `dunecontrol` script:
+
+ ./dune-common/bin/dunecontrol --opts=./dumux/cmake.opts all
+
+If you install an external library which is not a Dune module, the script will
+install the library in the directory `external`. If you install external libraries in an non-standard location you
+must usually either set the root path of the package (e.g. `CGAL_ROOT=<path/to/folder>`) or add the path to the `CMAKE_PREFIX_PATH`
+variable. These variables can be added in the option file `cmake.opts` before running `dunecontrol`. Compiler definitions are
+passed to CMake with the `-D` prefix, e.g. `-DCGAL_ROOT=<path/to/folder>`, so variables passed via `cmake.opts` need `-D` at the beginning.
+After you have installed an external library you should also clean the CMake cache and
+reconfigure and build DuMux as mentioned above.
+
+
+## Compatible versions of Dune and DuMux
+
+Only the following Dune and DuMux versions are compatible:
+
+<table class="table table-hover">
+<tr>
+ <th>DuMux version</th>
+ <th>Dune version</th>
+</tr>
+<tr align="center">
+ <td align="left">3.5, 3.6, 3.7-git</td>
+ <td align="left">2.8, 2.9-git<sup>**</sup></td>
+</tr>
+<tr align="center">
+ <td align="left">3.3, 3.4</td>
+ <td align="left">2.7, 2.8</td>
+</tr>
+<tr align="center">
+ <td align="left">3.1, 3.2</td>
+ <td align="left">2.6<sup>*</sup>, 2.7</td>
+</tr>
+<tr align="center">
+ <td align="left">3.0</td>
+ <td align="left">2.6<sup>*</sup>, 2.7</td>
+</tr>
+<tr align="center">
+ <td align="left">2.9, 2.10, 2.11, 2.12</td>
+ <td align="left">2.4, 2.5, 2.6<sup>*</sup></td>
+</tr>
+<tr align="center">
+ <td align="left">2.6, 2.7, 2.8</td>
+ <td align="left">2.3, 2.4</td>
+</tr>
+<tr align="center">
+ <td align="left">2.5</td>
+ <td align="left">2.2, 2.3</td>
+</tr>
+</table>
+
+<sup>*</sup> Please use the most recent corresponding Git branches `releases/2.6` instead of the `2.6.0` tarballs.
+
+<sup>**</sup> Compatibility with Dune `2.9-git` is tested automatically only for DuMux `3.7-git`.