diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..397a6bbf8e1e69ab35715bad4e9556ae5547257c
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,4 @@
+```{include} ../README.md
+:relative-docs: docs/
+:relative-images:
+```
\ No newline at end of file
diff --git a/docs/README.rst b/docs/README.rst
deleted file mode 100644
index d51cf8301a8feabeac3cff8e39ed0e6c12d06e08..0000000000000000000000000000000000000000
--- a/docs/README.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-README
-======
-
-.. literalinclude:: ../README.md
- :lines: 9-
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 5521c98d3b347e2a4f21c444ff0fab91a5c635d2..93d12794edb29edcc899ebf5a5b915b62f01db73 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -9,11 +9,11 @@ Welcome to eossr's documentation!
.. toctree::
:maxdepth: 2
:glob:
- :caption: Contents:
README
license
docstring
+ metadata
examples
snippets
diff --git a/docs/metadata.md b/docs/metadata.md
new file mode 100644
index 0000000000000000000000000000000000000000..652f08f313d943fec9011df9e6b44dedcc040ed7
--- /dev/null
+++ b/docs/metadata.md
@@ -0,0 +1,5 @@
+
+```{include} ../eossr/metadata/README.md
+:relative-docs: docs/
+:relative-images:
+```
\ No newline at end of file
diff --git a/eossr/metadata/README.md b/eossr/metadata/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..765b2c15a8ae8c3191a9d19553b3da4a51279022
--- /dev/null
+++ b/eossr/metadata/README.md
@@ -0,0 +1,131 @@
+# ESCAPE metadata template
+
+Among the [OSSR guidelines and rules of participation](
+https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/contribute_ossr/) - agreed between the ESCAPE WP3 participants -,
+we **strongly recommend** to include a metadata descriptive file into the entry to be uploaded to the ESCAPE repository.
+
+In the ESCAPE context, the use of the [CodeMeta schema](https://codemeta.github.io/) is strongly advised for uploads containing software.
+However, we support and encourage the use of any other metadata standard. If this is the case, please contact us
+(see just below). However, please note that the GitLab-Zenodo connection only supports - at the moment - codemeta metadata
+ descriptive files.
+
+Any comments are more than welcome. Open an issue or contact us [via email](mailto:vuillaume@lapp.in2p3.fr;garcia@lapp.in2p3.fr).
+
+## Quickstart - How to incorporate a CodeMeta metadata file into your project.
+
+ 1. Go to the [CodeMeta generator](https://codemeta.github.io/codemeta-generator/). Generate a `codemeta.json` file based on your project.
+ - Check - in the same web application - that the generated file is valid !
+ 2. Copy the generated metadata into a `codemeta.json` file and include it in the **root directory** of your project.
+ 3. Please **pay attention to the `keywords` field**. Include **at least one** of the following keywords **per category**;
+ besides all the keywords that you would like to attach to your project.
+
+### Keywords list
+
+In your `codemeta.json` file **add, at least,** one keywords of the following **three** categories:
+
+Multiple keywords must be separated with a comma `,` and between double `"`;
+```json
+ {
+ ...
+ "keywords": ["CTA", "Astroparticle physics", "jupyter-notebook", ...],
+ ...
+}
+```
+
+1. Project category:
+ - CTA
+ - LSST
+ - LOFAR
+ - SKA
+ - EGO-Virgo
+ - KM3NeT
+ - ELT
+ - EST
+ - HL-LHC
+ - FAIR
+ - CERN
+ - ESO
+ - JIVE
+ - IVOA
+ - EOSC
+ - ESO
+2. Domain category (single keywords):
+ - `Astronomy`
+ - `Astroparticle physics`
+ - `Particle physics`
+3. Notebooks category. At the moment only Jupyter notebooks are supported.
+ - Add `jupyter-notebook` as keyword if you project is based on or contains jupyter notebooks
+ - Do not add anything otherwise
+
+
+The reason to add the above keywords is just for classification and findability purposes in the OSSR (the
+ [ESCAPE2020 Zenodo community](https://zenodo.org/communities/escape2020) by other services such as the ESFRI Science Analysis Platform.
+
+## Create a Zenodo metadata file from the a CodeMeta schema file
+
+The zenodo repository does not accept codemeta metadata files yet. Meanwhile, the [eossr library](https://gitlab.in2p3.fr/escape2020/wp3/eossr)
+provides a simple tool to create a native Zenodo metadata file (`.zenodo.json`) from a `codemeta.json` file. To do so;
+
+ 1. Include a `codemeta.json` file to the root directory of your project.
+ 2. Install this package;
+```bash
+ $ git clone https://gitlab.in2p3.fr/escape2020/wp3/eossr.git
+ $ cd eossr
+ $ pip install .
+```
+ 3. And then just run
+ ```bash
+ $ eossr-codemeta2zenodo --help
+ $ eossr-codemeta2zenodo --codemeta_file codemeta.json
+```
+
+Also, you can check and use the [**online codemeta2zenodo**](https://escape2020.pages.in2p3.fr/wp3/codemeta2zenodo/codemeta2zenodo.html)
+converter, based on the same library.
+
+In case of doubts or problems, please [contact us](mailto:vuillaume@lapp.in2p3.fr;garcia@lapp.in2p3.fr).
+
+
+**THIS STAGE IS RECOMMENDED, BUT NOT COMPULSORY FOR THE OSSR ONBOARDING.**
+ - If you have linked your GitLab project with Zenodo using the autonomous procedure that [we propose](
+ https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/publish_in_repository/), this stage will be done automatically.
+ - If you are providing software via GitHub - and/or its [autonomous procedure](https://guides.github.com/activities/citable-code/) -,
+ this stage is not mandatory (but still recommended). GitHub will take care of fetching the metadata from the project directly.
+
+## Metadata schema templates
+
+Inside the `codemeta_utils` directory you will find two template files with **the all the properties (terms) of the corresponding metadata schema context**
+ for both the CodeMeta metadata file and the Zenodo metadata file.
+
+Feel free to create and incorporate the metadata files starting from these templates. However, please note that
+the final filenames **MUST** be either `codemeta.json` or `.zenodo.json` (note the `.` !). In case you do not fill or
+write nothing on any dictionary key field, take it out of the file.
+
+In case of doubts please also check;
+ - The [CodeMeta properties/terms description](https://codemeta.github.io/terms/) or,
+ - the [`metadata representation`](https://developers.zenodo.org/#representation) allowed for the `.zenodo.json` metadata file.
+
+
+### Extending the CodeMeta Context schema
+
+In case you find that CodeMeta context does not describe deep enough your digital resource, you can extend the metadata
+context and combine it with all the terms available at [https://schema.org](https://schema.org/docs/full.html).
+For this purpose, and following the [CodeMeta's developer guide](https://codemeta.github.io/developer-guide/);
+
+ 1. Modify the `"@Context"` key of the `codemeta.json` as;
+
+ "@context": ["https://raw.githubusercontent.com/codemeta/codemeta/2.0-rc/codemeta.jsonld", "http://schema.org/"]
+
+ 2. Include the desired terms / properties following the `schema.org` context.
+ 3. Contact us for a likely implementation into the OSSR environment ;-)
+
+
+-----------------
+-----------------
+
+
+### How to automatise the upload of a GitLab project to Zenodo via the GitLab-CI
+
+ - Add a `codemeta.js` file to your repository.
+ - Link your GitLab project and your Zenodo accounts.
+ - Add the following code snippet (Section 3. of the detailed tutorial) to the `.gitlab-ci.yml` file of your project and let the pipeline work !
+ - Check the [detailed tutorial](https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/publish_tutorial/) for more details.