diff --git a/doc/ChangeLog.md b/doc/ChangeLog.md
index 99deae8e..165c897a 100644
--- a/doc/ChangeLog.md
+++ b/doc/ChangeLog.md
@@ -1,5 +1,9 @@
-Version 3.0.0
-=============
+(changelog)=
+
+# Changelog
+
+## Version 3.0.0
+
 
 app4triqs version 3.0.0 is a compatibility
 release for TRIQS version 3.0.0 that
@@ -8,8 +12,7 @@ release for TRIQS version 3.0.0 that
 * fixes several application issues
 
 
-Version 2.2.0
-=============
+## Version 2.2.0
 
 app4triqs Version 2.2.0 provides a project
 skeleton for TRIQS applications based on
diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
new file mode 100644
index 00000000..a8c2f1bd
--- /dev/null
+++ b/doc/_static/css/custom.css
@@ -0,0 +1,5 @@
+@import url("theme.css");
+
+.wy-nav-content {
+    max-width: 70em;
+}
diff --git a/doc/about.rst b/doc/about.rst
index 69272ffc..c91ecb86 100644
--- a/doc/about.rst
+++ b/doc/about.rst
@@ -1,7 +1,7 @@
 .. _about:
 
 About app4triqs
-===============
+***************
 
 An example application using ``cpp2py`` and TRIQS.
 
diff --git a/doc/changelog.rst b/doc/changelog.rst
deleted file mode 100644
index 7c169e86..00000000
--- a/doc/changelog.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-.. _changelog:
-
-Changelog
-=========
-
-This document describes the main changes in APP4TRIQS.
-
-.. include:: ChangeLog.md
diff --git a/doc/conf.py.in b/doc/conf.py.in
index 280e28ac..31e575f3 100644
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -16,21 +16,44 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.githubpages',
               'sphinx_autorun',
               'nbsphinx',
+              'myst_parser',
               'matplotlib.sphinxext.plot_directive',
               'numpydoc']
 
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "smartquotes",
+    "substitution",
+    "tasklist",
+]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
 source_suffix = '.rst'
 
 project = '@PROJECT_NAME@'
 version = '@PROJECT_VERSION@'
 
-copyright = '2017-2018 N. Wentzell, O. Parcollet 2018-2019 The Simons Foundation, authors: N. Wentzell, D. Simons, H. Strand, O. Parcollet'
+copyright = '2017-2018 N. Wentzell, O. Parcollet 2018-2021 The Simons Foundation, authors: N. Wentzell, D. Simons, H. Strand, O. Parcollet'
 
 mathjax_path = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=default"
 templates_path = ['@CMAKE_CURRENT_SOURCE_DIR@/_templates']
 
 # this requires the sphinx_rtd_theme to be installed via pip
 html_theme = 'sphinx_rtd_theme'
+# this loads the custom css file to change the page width
+html_style = 'css/custom.css'
+
+#html_favicon = '@CMAKE_CURRENT_SOURCE_DIR@/logos/favicon.ico'
+#html_logo = '@CMAKE_CURRENT_SOURCE_DIR@/logos/logo.png'
 
 # options for the the rtd theme
 html_theme_options = {
@@ -39,7 +62,7 @@ html_theme_options = {
     'prev_next_buttons_location': 'bottom',
     'style_external_links': False,
     'vcs_pageview_mode': '',
-    # 'style_nav_header_background': '#7E588A',
+    'style_nav_header_background': '#7E588A',
     # Toc options
     'collapse_navigation': False,
     'sticky_navigation': True,
diff --git a/doc/contents.rst b/doc/contents.rst
deleted file mode 100644
index 4f990b6a..00000000
--- a/doc/contents.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-Table of contents
-=================
-
-.. toctree::
-   :maxdepth: 2
-
-   index
-   install
-   documentation
-   issues
-   changelog
-   about
diff --git a/doc/documentation.rst b/doc/documentation.rst
index e4408d16..d68686ca 100644
--- a/doc/documentation.rst
+++ b/doc/documentation.rst
@@ -1,7 +1,7 @@
 .. _documentation:
 
 Documentation
-=============
+*************
 
 
 .. math::
@@ -9,20 +9,9 @@ Documentation
    (a + b)^2  &=  (a + b)(a + b) \\
               &=  a^2 + 2ab + b^2
 
-Table of Contents
------------------
-
-.. toctree::
-   :maxdepth: 5
-
-   index
-   install
-   issues
-   changelog
-   about
 
 C++ reference manual
---------------------
+====================
 
 .. toctree::
    :maxdepth: 5
@@ -30,7 +19,7 @@ C++ reference manual
    cpp2rst_generated/contents
 
 Python reference manual
------------------------
+=======================
 
 .. automodule:: app4triqs 
    :members:
diff --git a/doc/index.rst b/doc/index.rst
index 16a8278d..8d52d689 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,12 +1,18 @@
 .. _welcome:
 
 app4triqs
-=========
+*********
 
-.. sidebar:: app4triqs 2.2.0
+.. sidebar:: app4triqs 3.0.0
 
-   This is the homepage of app4triqs v2.2.0.
+   This is the homepage of app4triqs v3.0.0.
    For changes see the :ref:`changelog page <changelog>`.
+      
+      .. image:: _static/logo_github.png
+         :width: 75%
+         :align: center
+         :target: https://github.com/triqs/app4triqs
+
 
 An example application using cpp2py and :ref:`TRIQS <triqslibs:welcome>`.
 
@@ -15,5 +21,13 @@ and the comments in the sources and headers.
 
 Learn how to use app4triqs in the :ref:`documentation`.
 
+    
 .. toctree::
    :maxdepth: 2
+   :hidden:
+
+   install
+   documentation
+   issues
+   ChangeLog.md
+   about
diff --git a/doc/install.rst b/doc/install.rst
index 12f1855f..1c7766b7 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -2,9 +2,13 @@
 
 .. _install:
 
+Install app4triqs
+*******************
+
 Compiling app4triqs from source
 ===============================
 
+.. note:: To guarantee reproducibility in scientific calculations we strongly recommend the use of a stable `release <https://github.com/TRIQS/triqs/releases>`_ of both TRIQS and its applications.
 
 Prerequisites
 -------------
diff --git a/doc/issues.rst b/doc/issues.rst
index ea52b95c..bdd0d5c2 100644
--- a/doc/issues.rst
+++ b/doc/issues.rst
@@ -1,7 +1,7 @@
 .. _issues:
 
 Reporting issues
-================
+****************
 
 Please report all problems and bugs directly at the github issue page
 `<https://github.com/TRIQS/app4triqs/issues>`_.  In order to make it easier for us