diff --git a/README.md b/README.md
index 70839ae1e12e9c540bb25299b675c2ac08d9030b..771a2a58bfb879d2e7ab4a64610c9ad3d938a50c 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,11 @@
-'''reference-repository''' is Grid'5000's ''single source of truth'' about sites, clusters, nodes, and network topology.
+reference-repository
+====================
+
+**reference-repository** is Grid'5000's *single source of truth* about sites, clusters, nodes, and network topology.
 
 There are several important parts:
 
-* data/ is the set of JSON files that describe Grid'5000. They are exposed by the ''reference API'' (for example: `curl -k https://api.grid5000.fr/sid/sites/nancy/clusters/graoully/nodes/graoully-1.json?pretty`
+* data/ is the set of JSON files that describe Grid'5000. They are exposed by the **reference API** (for example: `curl -k https://api.grid5000.fr/sid/sites/nancy/clusters/graoully/nodes/graoully-1.json?pretty` )
 * input/ is the set of YAML files used to generate data/. The files in input/ are either:
     + manually created and edited by admins
     + generated by g5k-checks (this is the case of the nodes descriptions, in the nodes/ directory of each cluster)
@@ -10,13 +13,13 @@ There are several important parts:
     + to check input/ data for consistency
     + to generate the configuration of various services (and the list of OAR properties)
 
-All tasks are executed using '''rake'''. To see the list of tasks, use '''rake -T'''.
+All tasks are executed using **rake**. To see the list of tasks, use `rake -T`.
 
 See also:
 
 * https://www.grid5000.fr/mediawiki/index.php/Reference_Repository
 * .gitlab-ci.yml, that automates various checks and the deployment of data files after each commit
-* README.generators.md
+* doc/README.generators.md
 
 # Credentials
 
diff --git a/README.generators.md b/doc/README.generators.md
similarity index 100%
rename from README.generators.md
rename to doc/README.generators.md