diff --git a/.travis.yml b/.travis.yml
index 65a18fc73b266..f1c8890a7327c 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -68,11 +68,6 @@ matrix:
         cat > CMakeLists.txt <<\EOF
         add_subdirectory(doc)
         EOF
-        # This is required because of differences between doxygen and github
-        # markdown syntax for code blocks. The committed code should use
-        # the github flavour and we generate the doxygen one on the fly.
-        git grep -l '^```[a-zA-Z]' | xargs sed -i .old -e 's|```\([a-zA-Z][a-zA-Z]*\)|\n```{.\1}\n|g;s|[.]bash|.sh|g;s|```|~~~~~~~|g'
-        find . -name "*.old" -delete
         cmake .
         make doc
       deploy:
diff --git a/Algorithm/README.md b/Algorithm/README.md
index faaf1f0dbf13f..3db89127b63d7 100644
--- a/Algorithm/README.md
+++ b/Algorithm/README.md
@@ -1,3 +1,7 @@
+<!-- doxy
 \page refAlgorithm Module 'Algorithm'
+/doxy -->
+
+# Algorithm
 
 A description of this module is not yet available.
diff --git a/CCDB/README.md b/CCDB/README.md
index 37697bb7443c6..79098d2aee7b0 100644
--- a/CCDB/README.md
+++ b/CCDB/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refCCDB Module 'CCDB'
+/doxy -->
 
 # CCDB
 
diff --git a/Common/Field/macro/README.md b/Common/Field/macro/README.md
index aa22541298541..b6e9870d7f925 100644
--- a/Common/Field/macro/README.md
+++ b/Common/Field/macro/README.md
@@ -1,3 +1,7 @@
+<!-- doxy
+\page refCommonFieldMacros Field Macros
+/doxy -->
+
 ## Macros for magnetic field manipulations
 
 ```o2::field::MagneticWrapperChebyshev``` class allows to dump the field data to text file and recreate it back as a ROOT object from this file. This is useful if one needs to change the name or the namespace of this class or persistent classes it usese internally (e.g. ``MathUtils/Chebyshev3D.h``, ``MathUtils/Chebyshev3DCalc.h``)
diff --git a/Common/README.md b/Common/README.md
index ec60c8f7e275e..cb7223fef0c51 100644
--- a/Common/README.md
+++ b/Common/README.md
@@ -1,12 +1,20 @@
+<!-- doxy
 \page refCommon Module 'Common'
+/doxy -->
 
+# Common
+
+There is no module description yet.
+
+<!-- doxy
 This module contains the following submodules:
 
-- \subpage refCommonConstants
-- \subpage refCommonField
-- \subpage refCommonMathUtils
-- \subpage refCommonSimConfig
-- \subpage refCommonTopologies
-- \subpage refCommonTypes
-- \subpage refCommonUtils
-- \subpage refCommonmaps
+* \subpage refCommonConstants
+* \subpage refCommonFieldMacros
+* \subpage refCommonMathUtils
+* \subpage refCommonSimConfig
+* \subpage refCommonTopologies
+* \subpage refCommonTypes
+* \subpage refCommonUtils
+* \subpage refCommonmaps
+/doxy -->
diff --git a/Common/SimConfig/doc/ConfigurableParam.md b/Common/SimConfig/doc/ConfigurableParam.md
index b0ff47c720f11..85ccc4b136a98 100644
--- a/Common/SimConfig/doc/ConfigurableParam.md
+++ b/Common/SimConfig/doc/ConfigurableParam.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refCommonSimConfig SimConfig
+/doxy -->
 
 # Configurable Parameters
 
diff --git a/DataFormats/README.md b/DataFormats/README.md
index 762457ee7d65d..86c27947518d9 100644
--- a/DataFormats/README.md
+++ b/DataFormats/README.md
@@ -1,13 +1,21 @@
+<!-- doxy
 \page refDataFormats Module 'DataFormats'
+/doxy -->
 
+# Data Formats
+
+There is no module description yet.
+
+<!-- doxy
 This module contains the following submodules:
 
-- \subpage refDataFormatsDetectors
-- \subpage refDataFormatsHeaders
-- \subpage refDataFormatsLegacy
-- \subpage refDataFormatsMemoryResources
-- \subpage refDataFormatsParameters
-- \subpage refDataFormatsReconstruction
-- \subpage refDataFormatsTimeFrame
-- \subpage refDataFormatscommon
-- \subpage refDataFormatssimulation
+* \subpage refDataFormatsDetectors
+* \subpage refDataFormatsHeaders
+* \subpage refDataFormatsLegacy
+* \subpage refDataFormatsMemoryResources
+* \subpage refDataFormatsParameters
+* \subpage refDataFormatsReconstruction
+* \subpage refDataFormatsTimeFrame
+* \subpage refDataFormatscommon
+* \subpage refDataFormatssimulation
+/doxy -->
diff --git a/Detectors/Base/test/README.md b/Detectors/Base/test/README.md
index 73f87a7f28194..41ab3f30c693b 100644
--- a/Detectors/Base/test/README.md
+++ b/Detectors/Base/test/README.md
@@ -1,3 +1,7 @@
+<!-- doxy
+\page refDetectorsBasetest Detectors Base test
+/doxy -->
+
 # WORK IN PROGRESS: Mat.Budget LUT classes
 
 
diff --git a/Detectors/ITSMFT/MFT/README.md b/Detectors/ITSMFT/MFT/README.md
index 47e7b05e036ee..69400cf2516b9 100644
--- a/Detectors/ITSMFT/MFT/README.md
+++ b/Detectors/ITSMFT/MFT/README.md
@@ -1,7 +1,8 @@
+<!-- doxy
 \page refMFT MFT
+/doxy -->
 
-The Muon Forward Tracker
-========================
+# The Muon Forward Tracker
 
 #### When? 
 * After the second LHC Long Shutdown.
diff --git a/Detectors/ITSMFT/MFT/base/README.md b/Detectors/ITSMFT/MFT/base/README.md
index 9e95a2ee782f5..e3dcb351f3efb 100644
--- a/Detectors/ITSMFT/MFT/base/README.md
+++ b/Detectors/ITSMFT/MFT/base/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refMFTbase MFT base
+/doxy -->
 
 # MFT base classes 
 
diff --git a/Detectors/ITSMFT/MFT/reconstruction/README.md b/Detectors/ITSMFT/MFT/reconstruction/README.md
index ea32bd5a1cbf2..b018627e8c6bb 100644
--- a/Detectors/ITSMFT/MFT/reconstruction/README.md
+++ b/Detectors/ITSMFT/MFT/reconstruction/README.md
@@ -1,7 +1,8 @@
+<!-- doxy
 \page refMFTreconstruction MFT reconstruction
+/doxy -->
 
-MFT track reconstruction
-========================
+# MFT track reconstruction
 
 (for the moment see macros/README)
 
diff --git a/Detectors/ITSMFT/README.md b/Detectors/ITSMFT/README.md
index c95b574320129..1a18671972ef2 100644
--- a/Detectors/ITSMFT/README.md
+++ b/Detectors/ITSMFT/README.md
@@ -1,7 +1,13 @@
+<!-- doxy
 \page refDetectorsITSMFT ITSMFT
+/doxy -->
+
+# ITSMFT
 
 This is a top page for the ITSMFT detector documentation.
 
-- \subpage refMFT
-- \subpage refMFTbase
-- \subpage refMFTreconstruction
+<!-- doxy
+* \subpage refMFT
+* \subpage refMFTbase
+* \subpage refMFTreconstruction
+/doxy -->
diff --git a/Detectors/MUON/MCH/Contour/README.md b/Detectors/MUON/MCH/Contour/README.md
index f0d0642babbf5..20555bce2e2a1 100644
--- a/Detectors/MUON/MCH/Contour/README.md
+++ b/Detectors/MUON/MCH/Contour/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refMUONMCHContour MCH Contour
+/doxy -->
 
 # MCH Contour library
 
diff --git a/Detectors/MUON/MCH/Mapping/Impl3/README.md b/Detectors/MUON/MCH/Mapping/Impl3/README.md
index c5c858d4390e3..806d1ab8ce24f 100644
--- a/Detectors/MUON/MCH/Mapping/Impl3/README.md
+++ b/Detectors/MUON/MCH/Mapping/Impl3/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refMUONMCHMappingImpl3 MCH Mapping Impl3
+/doxy -->
 
 # MCH Mapping Implementation
 
diff --git a/Detectors/MUON/MCH/Mapping/README.md b/Detectors/MUON/MCH/Mapping/README.md
index 4953d339ff033..0b329c4489ae3 100644
--- a/Detectors/MUON/MCH/Mapping/README.md
+++ b/Detectors/MUON/MCH/Mapping/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refMUONMCHMapping MCH Mapping
+/doxy -->
 
 # MCH Mapping
 
diff --git a/Detectors/MUON/MCH/Mapping/SegContour/README.md b/Detectors/MUON/MCH/Mapping/SegContour/README.md
index 9b2e9a99def50..4de623f9239ac 100644
--- a/Detectors/MUON/MCH/Mapping/SegContour/README.md
+++ b/Detectors/MUON/MCH/Mapping/SegContour/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refMUONMCHMappingSegContour MCH Mapping SegContour
+/doxy -->
 
 # Segmentation contours
 
diff --git a/Detectors/MUON/MCH/Mapping/test/src/README.md b/Detectors/MUON/MCH/Mapping/test/src/README.md
index 94175760b7e86..cf4b9dafaa2b7 100644
--- a/Detectors/MUON/MCH/Mapping/test/src/README.md
+++ b/Detectors/MUON/MCH/Mapping/test/src/README.md
@@ -1,4 +1,6 @@
-\page refMUONMCHMappingtest  MCH Mapping test
+<!-- doxy
+\page refMUONMCHMappingtest MCH Mapping test
+/doxy -->
 
 By default the tests are running without any input.
 
diff --git a/Detectors/MUON/MID/Clustering/README.md b/Detectors/MUON/MID/Clustering/README.md
index e14ffc2d1f9d3..676a4e37b0b9f 100644
--- a/Detectors/MUON/MID/Clustering/README.md
+++ b/Detectors/MUON/MID/Clustering/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refMUONMIDClustering MID Clustering
+/doxy -->
 
 # Running MID clustering
 
diff --git a/Detectors/MUON/MID/Tracking/README.md b/Detectors/MUON/MID/Tracking/README.md
index 4d0aa92f3c03f..7849f8d0731c5 100644
--- a/Detectors/MUON/MID/Tracking/README.md
+++ b/Detectors/MUON/MID/Tracking/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refMUONMIDTracking MID Tracking
+/doxy -->
 
 # Running MID Tracking
 
diff --git a/Detectors/MUON/MID/Workflow/README.md b/Detectors/MUON/MID/Workflow/README.md
index 7d54a0d01aeb4..af93cf01b31dd 100644
--- a/Detectors/MUON/MID/Workflow/README.md
+++ b/Detectors/MUON/MID/Workflow/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refMUONMIDWorkflow MID Workflow
+/doxy -->
 
 # Running MID workflow
 
diff --git a/Detectors/MUON/README.md b/Detectors/MUON/README.md
index 0ddd66e75b6aa..71d20bc09061d 100644
--- a/Detectors/MUON/README.md
+++ b/Detectors/MUON/README.md
@@ -1,11 +1,18 @@
+<!-- doxy
 \page refDetectorsMUON MUON
+/doxy -->
+
+# MUON
 
 This is a top page for the MUON detector documentation.
 
-- \subpage refMUONMIDClustering
-- \subpage refMUONMIDTracking
-- \subpage refMUONMCHMappingSegContour
-- \subpage refMUONMCHMapping
-- \subpage refMUONMCHMappingtest
-- \subpage refMUONMCHMappingImpl3
-- \subpage refMUONMCHContour
+<!-- doxy
+* \subpage refMUONMIDClustering
+* \subpage refMUONMIDTracking
+* \subpage refMUONMIDWorkflow
+* \subpage refMUONMCHMappingSegContour
+* \subpage refMUONMCHMapping
+* \subpage refMUONMCHMappingtest
+* \subpage refMUONMCHMappingImpl3
+* \subpage refMUONMCHContour
+/doxy -->
diff --git a/Detectors/README.md b/Detectors/README.md
index 01d8b556d00fc..204cd68794e3d 100644
--- a/Detectors/README.md
+++ b/Detectors/README.md
@@ -1,18 +1,26 @@
+<!-- doxy
 \page refDetectors Module 'Detectors'
+/doxy -->
 
+# Detectors
+
+There is no module description yet.
+
+<!-- doxy
 This module contains the following submodules:
 
-- \subpage refDetectorsBase
-- \subpage refDetectorsEMCAL
-- \subpage refDetectorsFIT
-- \subpage refDetectorsGeometry
-- \subpage refDetectorsGlobalTracking
-- \subpage refDetectorsHMPID
-- \subpage refDetectorsITSMFT
-- \subpage refDetectorsMUON
-- \subpage refDetectorsPHOS
-- \subpage refDetectorsPassive
-- \subpage refDetectorsTOF
-- \subpage refDetectorsTPC
-- \subpage refDetectorsTRD
-- \subpage refDetectorsZDC
+* \subpage refDetectorsBasetest
+* \subpage refDetectorsEMCAL
+* \subpage refDetectorsFIT
+* \subpage refDetectorsGeometry
+* \subpage refDetectorsGlobalTracking
+* \subpage refDetectorsHMPID
+* \subpage refDetectorsITSMFT
+* \subpage refDetectorsMUON
+* \subpage refDetectorsPHOS
+* \subpage refDetectorsPassive
+* \subpage refDetectorsTOF
+* \subpage refDetectorsTPC
+* \subpage refDetectorsTRD
+* \subpage refDetectorsZDC
+/doxy -->
diff --git a/Detectors/TPC/README.md b/Detectors/TPC/README.md
index 5dea3b99c4d43..bbef804c01a3b 100644
--- a/Detectors/TPC/README.md
+++ b/Detectors/TPC/README.md
@@ -1,5 +1,11 @@
+<!-- doxy
 \page refDetectorsTPC TPC
+/doxy -->
+
+# TPC
 
 This is a top page for the TPC detector documentation.
 
-- \subpage refTPCworkflow
+<!-- doxy
+* \subpage refTPCworkflow
+/doxy -->
diff --git a/Detectors/TPC/workflow/README.md b/Detectors/TPC/workflow/README.md
index b2c1d893ecb2f..a7210e008e46c 100644
--- a/Detectors/TPC/workflow/README.md
+++ b/Detectors/TPC/workflow/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refTPCworkflow TPC workflow
+/doxy -->
 
 # DPL workflows for the TPC
 
diff --git a/Detectors/TRD/README.md b/Detectors/TRD/README.md
index e3bc6f7f4af7f..6f4bae1f3b4f8 100644
--- a/Detectors/TRD/README.md
+++ b/Detectors/TRD/README.md
@@ -1,5 +1,11 @@
+<!-- doxy
 \page refDetectorsTRD TRD
+/doxy -->
+
+# TRD
 
 This is a top page for the TRD detector documentation.
 
-- \subpage refTRDbase
+<!-- doxy
+* \subpage refTRDbase
+/doxy -->
diff --git a/EventVisualisation/Base/README.md b/EventVisualisation/Base/README.md
index 37735c58fae19..a5ebf48cdc860 100644
--- a/EventVisualisation/Base/README.md
+++ b/EventVisualisation/Base/README.md
@@ -1,3 +1,7 @@
+<!-- doxy
 \page refEventVisualisationBase EventVisualisation Base
+/doxy -->
+
+# Event Visualisation Base
 
 A description of this module is not yet available.
diff --git a/EventVisualisation/README.md b/EventVisualisation/README.md
index e8bbf78bea9e7..6024acf34791e 100644
--- a/EventVisualisation/README.md
+++ b/EventVisualisation/README.md
@@ -1,6 +1,14 @@
+<!-- doxy
 \page refEventVisualisation Module 'EventVisualisation'
+/doxy -->
 
+# Event Visualisation
+
+There is no module description yet.
+
+<!-- doxy
 This module contains the following submodules:
 
-- \subpage refEventVisualisationBase
+* \subpage refEventVisualisationBase
+/doxy -->
 
diff --git a/Examples/Ex1/README.md b/Examples/Ex1/README.md
index 1d93edcd7aeba..c42b9451d79d8 100644
--- a/Examples/Ex1/README.md
+++ b/Examples/Ex1/README.md
@@ -1,3 +1,7 @@
-\page refEx1 Ex1 A basic example with one library
+<!-- doxy
+\page refExamplesEx1 Ex1 A basic example with one library
+/doxy -->
+
+## Ex1 A basic example with one library
 
 See [CMakeInstructions](../doc/CMakeInstructions.md) for an explanation about this directory.
diff --git a/Examples/Ex2/README.md b/Examples/Ex2/README.md
index 458f19ff4a3cf..3c96cc3e7193e 100644
--- a/Examples/Ex2/README.md
+++ b/Examples/Ex2/README.md
@@ -1,3 +1,7 @@
-\page refEx2 Ex2 A basic library with a Root dictionary
+<!-- doxy
+\page refExamplesEx2 Ex2 A basic library with a Root dictionary
+/doxy -->
+
+## Ex2 A basic library with a Root dictionary
 
 See [CMakeInstructions](../doc/CMakeInstructions.md) for an explanation about this directory.
diff --git a/Examples/Ex3/README.md b/Examples/Ex3/README.md
index 38790baf9dc7d..879ff48227de8 100644
--- a/Examples/Ex3/README.md
+++ b/Examples/Ex3/README.md
@@ -1,3 +1,7 @@
-\page refEx3 Ex3 Adding an executable
+<!-- doxy
+\page refExamplesEx3 Ex3 Adding an executable
+/doxy -->
+
+## Ex3 Adding an executable
 
 See [CMakeInstructions](../doc/CMakeInstructions.md) for an explanation about this directory.
diff --git a/Examples/Ex4/README.md b/Examples/Ex4/README.md
index 0abb3f7178bc5..9e526d06a4636 100644
--- a/Examples/Ex4/README.md
+++ b/Examples/Ex4/README.md
@@ -1,3 +1,7 @@
-\page refEx4 Ex4 Adding tests
+<!-- doxy
+\page refExamplesEx4 Ex4 Adding tests
+/doxy -->
+
+## Ex4 Adding tests
 
 See [CMakeInstructions](../doc/CMakeInstructions.md) for an explanation about this directory.
diff --git a/Examples/Ex5/README.md b/Examples/Ex5/README.md
index 54d68cbc797aa..ebc693bb0c68a 100644
--- a/Examples/Ex5/README.md
+++ b/Examples/Ex5/README.md
@@ -1,3 +1,7 @@
-\page refEx5 Ex5 Adding a man page
+<!-- doxy
+\page refExamplesEx5 Ex5 Adding a man page
+/doxy -->
+
+## Ex5 Adding a man page
 
 See [CMakeInstructions](../doc/CMakeInstructions.md) for an explanation about this directory.
diff --git a/Examples/README.md b/Examples/README.md
index c3bd3a90f8c09..4db2235f7f0d9 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -1,13 +1,17 @@
-\\page refExamples Module 'Examples'
+<!-- doxy
+\page refExamples Module 'Examples'
+/doxy -->
 
-This module contains the following submodules:
-
--   \\subpage refExamplesflp2epn
--   \\subpage refExamplesflp2epn-distributed
--   \\subpage refEx1
--   \\subpage refEx2
--   \\subpage refEx3
--   \\subpage refEx4
--   \\subpage refEx5
+# Examples
 
 The various `Ex` directories are incremental illustrations of [how to write](../doc/CMakeInstructions.md) `CMakeLists.txt` files within AliceO2 repository.
+
+<!-- doxy
+* \subpage refExamplesflp2epn
+* \subpage refExamplesflp2epn-distributed
+* \subpage refExamplesEx1
+* \subpage refExamplesEx2
+* \subpage refExamplesEx3
+* \subpage refExamplesEx4
+* \subpage refExamplesEx5
+/doxy -->
diff --git a/Examples/flp2epn-distributed/README.md b/Examples/flp2epn-distributed/README.md
index 346c847ff4131..bc3badfe1023b 100644
--- a/Examples/flp2epn-distributed/README.md
+++ b/Examples/flp2epn-distributed/README.md
@@ -1,4 +1,8 @@
+<!-- doxy
 \page refExamplesflp2epn-distributed Example flp2epn-distributed
+/doxy -->
+
+## Example flp2epn-distributed
 
 #### Prototype Devices for the transport between FLPs and EPNs
 --------------------------------------------------------------
diff --git a/Examples/flp2epn/README.md b/Examples/flp2epn/README.md
index b0fbc5d5c38f3..5cd832167980c 100644
--- a/Examples/flp2epn/README.md
+++ b/Examples/flp2epn/README.md
@@ -1,4 +1,8 @@
+<!-- doxy
 \page refExamplesflp2epn Example flp2epn
+/doxy -->
+
+## Example flp2epn
 
 #### Example devices - testFLP and testEPN
 
diff --git a/Framework/Core/ANALYSIS.md b/Framework/Core/ANALYSIS.md
index 297758ec40d97..cdcc3c72a19fd 100644
--- a/Framework/Core/ANALYSIS.md
+++ b/Framework/Core/ANALYSIS.md
@@ -1,3 +1,9 @@
+<!-- doxy
+\page refFrameworkCoreANALYSIS Core ANALYSIS
+/doxy -->
+
+##  Core ANALYSIS
+
 This document is WIP and provides an idea of what kind of API to expect from the DPL enabled analysis framework. APIs are neither final nor fully implemented in O2.
 
 # Analysis Task infrastructure on top of DPL
diff --git a/Framework/Core/COOKBOOK.md b/Framework/Core/COOKBOOK.md
index e2c4d112dfdab..7c8ca4e8a1fdf 100644
--- a/Framework/Core/COOKBOOK.md
+++ b/Framework/Core/COOKBOOK.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refFrameworkCoreCOOKBOOK Core COOKBOOK
+/doxy -->
 
 # Data Processing Layer Cookbook
 
diff --git a/Framework/Core/README.md b/Framework/Core/README.md
index 41ce8c3f3c2c8..52034947e7588 100644
--- a/Framework/Core/README.md
+++ b/Framework/Core/README.md
@@ -1,5 +1,8 @@
+<!-- doxy
 \page refFrameworkCore Core
 \subpage refFrameworkCoreCOOKBOOK Core COOKBOOK
+\subpage refFrameworkCoreANALYSIS Core ANALYSIS
+/doxy -->
 
 # Data Processing Layer in O2 Framework
 
diff --git a/Framework/Foundation/README.md b/Framework/Foundation/README.md
index f4f5c4edb08f7..bdabb40784b6e 100644
--- a/Framework/Foundation/README.md
+++ b/Framework/Foundation/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refFrameworkFoundation Foundation
+/doxy -->
 
 ## O2 Framework Foundation
 
diff --git a/Framework/Logger/README.md b/Framework/Logger/README.md
index 8ad056276bb09..9fc6ecb135d1f 100644
--- a/Framework/Logger/README.md
+++ b/Framework/Logger/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refFrameworkLogger Logger
+/doxy -->
 
 ## O2 Framework Logger
 
diff --git a/Framework/README.md b/Framework/README.md
index 557b58e16c314..9b0971efe1377 100644
--- a/Framework/README.md
+++ b/Framework/README.md
@@ -1,10 +1,19 @@
+<!-- doxy
 \page refFramework Module 'Framework'
+/doxy -->
 
+# Framework
+
+There is no module description yet.
+
+<!-- doxy
 This module contains the following submodules:
 
-- \subpage refFrameworkArrowTests
-- \subpage refFrameworkCore
-- \subpage refFrameworkDebugGUI
-- \subpage refFrameworkFoundation
-- \subpage refFrameworkTestWorkflows
-- \subpage refFrameworkUtils
+* \subpage refFrameworkArrowTests
+* \subpage refFrameworkCore
+* \subpage refFrameworkDebugGUI
+* \subpage refFrameworkFoundation
+* \subpage refFrameworkLogger
+* \subpage refFrameworkTestWorkflows
+* \subpage refFrameworkUtils
+/doxy -->
diff --git a/Framework/Utils/Readme.md b/Framework/Utils/Readme.md
index 24ac951713507..e3e39bdd1ca77 100644
--- a/Framework/Utils/Readme.md
+++ b/Framework/Utils/Readme.md
@@ -1,3 +1,7 @@
+<!-- doxy
+\page refFrameworkUtils Utils
+/doxy -->
+
 ## DPL Utilities
 
 ### Raw proxy
diff --git a/Generators/README.md b/Generators/README.md
index c8a7a142897fc..e72383c43f190 100644
--- a/Generators/README.md
+++ b/Generators/README.md
@@ -1,3 +1,13 @@
+<!-- doxy
 \page refGenerators Module 'Generators'
+/doxy -->
+
+# Generators
 
 A description of this module is not yet available.
+
+<!-- doxy
+This module contains the following submodules:
+
+* \subpage refGeneratorsshareexternal
+/doxy -->
diff --git a/Generators/share/external/README.md b/Generators/share/external/README.md
index fdd83f70265ab..da3d956209bbb 100644
--- a/Generators/share/external/README.md
+++ b/Generators/share/external/README.md
@@ -1,3 +1,7 @@
+<!-- doxy
+\page refGeneratorsshareexternal External Generators
+/doxy -->
+
 # External generators
 
 
diff --git a/README.md b/README.md
index 58970f1b6678f..4213ebabcaa0d 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # ALICE O2 software {#mainpage}
 
-<!--  \cond EXCLUDE_FOR_DOXYGEN -->
+<!--  /// \cond EXCLUDE_FOR_DOXYGEN -->
 
 [![codecov](https://codecov.io/gh/AliceO2Group/AliceO2/branch/dev/graph/badge.svg)](https://codecov.io/gh/AliceO2Group/AliceO2/branches/dev)
 [![JIRA](https://img.shields.io/badge/JIRA-Report%20issue-blue.svg)](https://alice.its.cern.ch/jira/secure/CreateIssue.jspa?pid=11201&issuetype=1)
@@ -11,7 +11,7 @@
 [![](http://ali-ci.cern.ch/repo/buildstatus/AliceO2Group/AliceO2/dev/build_o2checkcode_o2.svg)](https://ali-ci.cern.ch/repo/logs/AliceO2Group/AliceO2/dev/latest/build_o2checkcode_o2/fullLog.txt)
 [![](http://ali-ci.cern.ch/repo/buildstatus/AliceO2Group/AliceO2/dev/build_O2_o2-dev-fairroot.svg)](https://ali-ci.cern.ch/repo/logs/AliceO2Group/AliceO2/dev/latest/build_O2_o2-dev-fairroot/fullLog.txt)
 
-<!--  \endcond  -->
+<!--  /// \endcond  -->
 
 ### Scope
 
@@ -20,7 +20,7 @@ Other repositories in AliceO2Group contain a number of large common modules, for
 
 ### Website
 
-The main entry point for O2 information is [here](http://alice-o2.web.cern.ch/).
+The main entry point for O2 information is [here](https://alice-o2-project.web.cern.ch).
 A quickstart page can be found under [https://aliceo2group.github.io/](https://aliceo2group.github.io/).
 
 ### Building / Installation
@@ -46,12 +46,12 @@ To access the resulting documentation, open doc/html/index.html in your
 build directory. To install the documentation when calling `cmake --build . -- install` (or `cmake --install` for CMake >= 3.15)
 turn on the variable `DOC_INSTALL`.
 
-The instruction how to add the documentation pages (README.md) are available [here](doc/DoxygenInstructions.md).
+The instruction how to add the documentation pages (README.md) are available [here](https://aliceo2group.github.io/AliceO2/refdocDoxygenInstructions.html).
 
 ### Build system (cmake) and directory structure
 
-The code organisation is described [here](doc/CodeOrganization.md).
-The build system (cmake) is described [here](doc/CMakeInstructions.md).
+The code organisation is described [here](https://aliceo2group.github.io/AliceO2/refdocCodeOrganization.html).
+The build system (cmake) is described [here](https://aliceo2group.github.io/AliceO2/refdocCMakeInstructions.html).
 
 ### Formatting
 
diff --git a/Steer/DigitizerWorkflow/README.md b/Steer/DigitizerWorkflow/README.md
index d7a6755b4bb2c..a33c217681155 100644
--- a/Steer/DigitizerWorkflow/README.md
+++ b/Steer/DigitizerWorkflow/README.md
@@ -1,4 +1,8 @@
+<!-- doxy
 \page refSteerDigitizerWorkflow Digitizer Workflow
+/doxy -->
+
+# Digitizer Workflow
 
 This is a short documention for the DPL-DigitizerWorkflow example
 
diff --git a/Steer/README.md b/Steer/README.md
index e6d003cbf789a..05eb659fdcea8 100644
--- a/Steer/README.md
+++ b/Steer/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refSteer Module 'Steer'
+/doxy -->
 
 # ALICEO2 Steer
 
@@ -11,6 +13,8 @@ a) quick prototyping of ideas without having to require immediate changes in Fai
 b) adaptations to classes because some things are done differently than in FairRoot
    (MC truth handling, parameter handling etc)
 
+<!-- doxy
 This module contains the following submodules:
 
-\subpage refSteerDigitizerWorkflow
+* \subpage refSteerDigitizerWorkflow
+/doxy -->
diff --git a/Testing/README.md b/Testing/README.md
index 57bfae60ff879..a744a3fcb228b 100644
--- a/Testing/README.md
+++ b/Testing/README.md
@@ -1,3 +1,7 @@
+<!-- doxy
 \page refTesting Module 'Testing'
+/doxy -->
+
+# Testing
 
 A description of this module is not yet available.
diff --git a/Utilities/MCStepLogger/README.md b/Utilities/MCStepLogger/README.md
index d2adf3ce83422..720709548c472 100644
--- a/Utilities/MCStepLogger/README.md
+++ b/Utilities/MCStepLogger/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refUtilitiesMCStepLogger MCStepLogger
+/doxy -->
 
 ### NOTE: The MCStepLogger has moved to https://github.com/AliceO2Group/VMCStepLogger.git
 
diff --git a/Utilities/Mergers/README.md b/Utilities/Mergers/README.md
index a5cfc0713e242..e87e0bc3d59bc 100644
--- a/Utilities/Mergers/README.md
+++ b/Utilities/Mergers/README.md
@@ -1,3 +1,7 @@
+<!-- doxy
+\page refUtilitiesMergers Mergers
+/doxy -->
+
 # O2 Mergers (experimental)
 
 Mergers are DPL devices able to merge ROOT objects produced in parallel. Topologies of mergers can be created using the
diff --git a/Utilities/O2Device/README.md b/Utilities/O2Device/README.md
index ae2e3c1bfa8f7..79ba57eabb003 100644
--- a/Utilities/O2Device/README.md
+++ b/Utilities/O2Device/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refUtilitiesO2Device O2Device
+/doxy -->
 
 # O2Device
 
diff --git a/Utilities/PCG/README.md b/Utilities/PCG/README.md
index cef5ab2192627..603ffded7d3de 100644
--- a/Utilities/PCG/README.md
+++ b/Utilities/PCG/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refUtilitiesPCG PCG
+/doxy -->
 
 # PCG Random Number Generation, C++ Edition
 
diff --git a/Utilities/README.md b/Utilities/README.md
index 2537a3460238c..1189ef24b8e6e 100644
--- a/Utilities/README.md
+++ b/Utilities/README.md
@@ -2,22 +2,22 @@
 \page refUtilities Module 'Utilities'
 /doxy -->
 
-Module 'Utilities'
-===================
+# Utilities
 
 There is no module description yet.
 
 <!-- doxy
 This module contains the following submodules:
 
-- \subpage refUtilitiesDataCompression
-- \subpage refUtilitiesDataFlow
-- \subpage refUtilitiesMCStepLogger
-- \subpage refUtilitiesO2Device
-- \subpage refUtilitiesO2MessageMonitor
-- \subpage refUtilitiesPCG
-- \subpage refUtilitiesPublishers
-- \subpage refUtilitiesTools
-- \subpage refUtilitiesaliceHLTwrapper
-- \subpage refUtilitieshough
+* \subpage refUtilitiesDataCompression
+* \subpage refUtilitiesDataFlow
+* \subpage refUtilitiesMCStepLogger
+* \subpage refUtilitiesMergers
+* \subpage refUtilitiesO2Device
+* \subpage refUtilitiesO2MessageMonitor
+* \subpage refUtilitiesPCG
+* \subpage refUtilitiesPublishers
+* \subpage refUtilitiesTools
+* \subpage refUtilitiesaliceHLTwrapper
+* \subpage refUtilitieshough
 /doxy -->
diff --git a/Utilities/Tools/README.md b/Utilities/Tools/README.md
index 30eb1cdb7fa2e..2b170207597c4 100644
--- a/Utilities/Tools/README.md
+++ b/Utilities/Tools/README.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refUtilitiesTools Tools
+/doxy -->
 
 # Using the Code checker / fixer
 
diff --git a/Utilities/hough/README.md b/Utilities/hough/README.md
index c001c904842d5..3d8f44e8ccb43 100644
--- a/Utilities/hough/README.md
+++ b/Utilities/hough/README.md
@@ -1,7 +1,8 @@
+<!-- doxy
 \page refUtilitieshough Hough Transform
+/doxy -->
 
-Hough Transform
-===============
+# Hough Transform
 
 This is the groundwork for the Hough Transform algorithm implementation. The runHough executable takes as an argument an event number (i.e. runHough 032) and for the given event it loads all clusters from the corresponding data files.
 
diff --git a/doc/CLion.md b/doc/CLion.md
index 6b9d254b6a94e..b4519e57e1bca 100644
--- a/doc/CLion.md
+++ b/doc/CLion.md
@@ -1,4 +1,8 @@
+<!-- doxy
 \page refdocCLion CLion
+/doxy -->
+
+# CLion
 
 Here are a number of instructions and tips on how to use at best the IDE called [CLion from Jetbrains](https://www.jetbrains.com/clion/).
 
diff --git a/doc/CMakeInstructions.md b/doc/CMakeInstructions.md
index ff544f5740af5..4d79a7e38abd3 100644
--- a/doc/CMakeInstructions.md
+++ b/doc/CMakeInstructions.md
@@ -1,4 +1,8 @@
-\\page refdocCMakeInstructions CMake Instructions
+<!-- doxy
+\page refdocCMakeInstructions CMake Instructions
+
+\cond DOXYGEN_IGNORE
+/doxy -->
 
 <!-- vim-markdown-toc GFM -->
 
@@ -19,6 +23,10 @@
 
 <!-- vim-markdown-toc -->
 
+<!-- doxy
+\endcond
+/doxy -->
+
 # CMake and CTest tips for AliceO2
 
 ## CMake
diff --git a/doc/CMakeMigration.md b/doc/CMakeMigration.md
index c0e5702d99161..14b4ed93ca85e 100644
--- a/doc/CMakeMigration.md
+++ b/doc/CMakeMigration.md
@@ -1,3 +1,7 @@
+<!-- doxy
+\page refdocModernCMakeMigration Modern CMake Migration
+/doxy -->
+
 # Migration to "Modern" CMake
 
 ## Big picture
diff --git a/doc/CodeOrganization.md b/doc/CodeOrganization.md
index 980565db35168..c57f8cc581c5a 100644
--- a/doc/CodeOrganization.md
+++ b/doc/CodeOrganization.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refdocCodeOrganization Code Organization
+/doxy -->
 
 # Code organisation
 
diff --git a/doc/DetectorSimulation.md b/doc/DetectorSimulation.md
index f39d67f2d5946..301f43c88ef0a 100644
--- a/doc/DetectorSimulation.md
+++ b/doc/DetectorSimulation.md
@@ -1,4 +1,6 @@
+<!-- doxy
 \page refdocDetectorSimulation Detector Simulation
+/doxy -->
 
 # Detector simulation documentation
 
diff --git a/doc/DoxygenInstructions.md b/doc/DoxygenInstructions.md
index dee037f30fb4f..7bfa2383749a6 100644
--- a/doc/DoxygenInstructions.md
+++ b/doc/DoxygenInstructions.md
@@ -1,36 +1,44 @@
+<!-- doxy
 \page refdocDoxygenInstructions Doxygen Instructions
+/doxy -->
 
-Doxygen
-=======
+# Doxygen 
 
 ## Instructions for the contributors
 
 The Doxygen documentation pages are generated from the `README.md` files placed in the O2 directories. 
 
-The references between the Doxygen pages and subpages are achieved using a Doxygen `page` and `subpage` keywords. All `README.md` files must contain the Doxygen `page` tag on the top, and if the module contains other documentation pages (usually in its sub-directories), it must be linked using the Doxygen `subpage` tag.
+The references between the Doxygen pages and subpages are achieved using a Doxygen `page` and `subpage` keywords. All `README.md` files must contain the Doxygen `page` tag on the top, and if the module contains other documentation pages (usually in its sub-directories), it must be linked using the Doxygen `subpage` tag. Special markdown comments are used to disable rendering of Doxygen keywords on GitHub.
+
+*When adding a new documentation page you must always add a `\subpage` declaration in an upper category page otherwise your page will pollute the "global" references in the left tab menu.*
+
 
 #### An example of a `README` file in the O2 directories at the top level.
 
+    <!-- doxy
     \page refModulename Module 'Modulename'
+    /doxy -->
 
-    The module title
-    ================
+    # The module title
 
     The paragraph(s) with the module description.
 
+    <!-- doxy
     This module contains the following submodules:
     
-    - \subpage refModulenameSubmodulename1
-    - \subpage refModulenameSubmodulename2
-    - \subpage refModulenameSubmodulename3
+    * \subpage refModulenameSubmodulename1
+    * \subpage refModulenameSubmodulename2
+    * \subpage refModulenameSubmodulename3
+    /doxy -->
 
 
 #### An example of a `README` file at a submodule level:
 
+    <!-- doxy
     \page refModulenameSubmodulename1 Submodulename1
+    /doxy -->
 
-    The submodule1 title
-    ====================
+    # The submodule1 title
 
     The paragraph(s) with the submodule description.
 
diff --git a/doc/ManPages.md b/doc/ManPages.md
index a0b86fb46dfe5..8fb7b48b07beb 100644
--- a/doc/ManPages.md
+++ b/doc/ManPages.md
@@ -1,4 +1,8 @@
+<!-- doxy
 \page refdocManPages Man Pages
+/doxy -->
+
+# Man Pages
 
 You can create man pages in nroff format under:
 
diff --git a/doc/README.md b/doc/README.md
index 11cc22e74563e..4c8224a712850 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -1,10 +1,17 @@
+<!-- doxy
 \page refdoc Documentation pages
+/doxy -->
 
-This module contains the following documentation pages
+# Documentation pages
 
-- \subpage refdocCLion
-- \subpage refdocCMakeInstructions
-- \subpage refdocCodeOrganization
-- \subpage refdocDetectorSimulation
-- \subpage refdocDoxygenInstructions
-- \subpage refdocManPages
+This module contains the documentation pages.
+
+<!-- doxy
+* \subpage refdocCLion
+* \subpage refdocCMakeInstructions
+* \subpage refdocModernCMakeMigration
+* \subpage refdocCodeOrganization
+* \subpage refdocDetectorSimulation
+* \subpage refdocDoxygenInstructions
+* \subpage refdocManPages
+/doxy -->
diff --git a/doc/scripts/filter_for_doxygen.sh b/doc/scripts/filter_for_doxygen.sh
index f84d86008dd0a..3027a54cdba31 100755
--- a/doc/scripts/filter_for_doxygen.sh
+++ b/doc/scripts/filter_for_doxygen.sh
@@ -1,4 +1,8 @@
 # Filtering out the HTML comments hiding doxygen keywords from Markdown
 # I. Hrivnacova 25/03/2019
 #
-sed -e '/<!-- doxy/d' -e '/\/doxy -->/d' "$1"
+sed -e '/<!-- doxy/d' -e '/\/doxy -->/d' -e 's/```c++/~~~{.cpp}/g; s/```bash/~~~{.sh}/g; s/```/~~~/g;' "$1"
+
+# Previous instructions applied in .travis.yml
+# git grep -l '^```[a-zA-Z]' | xargs sed -i .old -e 's|```\([a-zA-Z][a-zA-Z]*\)|\n```{.\1}\n|g;s|[.]bash|.sh|g;s|```|~~~~~~~|g'
+# find . -name "*.old" -delete