diff --git a/README.md b/README.rst
rename from README.md
rename to README.rst
--- a/README.md
+++ b/README.rst
@@ -1,7 +1,12 @@
-swh-core
-========
+.. _swh-core:
+
+Software Heritage - Core foundations
+====================================
+
+Low-level utilities and helpers used by almost all other modules in the stack.
 
 core library for swh's modules:
+
 - config parser
 - hash computations
 - serialization
diff --git a/docs/README.rst b/docs/README.rst
new file mode 120000
--- /dev/null
+++ b/docs/README.rst
@@ -0,0 +1 @@
+../README.rst
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,10 +1,4 @@
-.. _swh-core:
-
-Software Heritage - Core foundations
-====================================
-
-Low-level utilities and helpers used by almost all other modules in the stack.
-
+.. include:: README.rst
 
 Reference Documentation
 -----------------------
diff --git a/setup.py b/setup.py
--- a/setup.py
+++ b/setup.py
@@ -13,7 +13,7 @@
 here = path.abspath(path.dirname(__file__))
 
 # Get the long description from the README file
-with open(path.join(here, "README.md"), encoding="utf-8") as f:
+with open(path.join(here, "README.rst"), encoding="utf-8") as f:
     long_description = f.read()
 
 
@@ -41,7 +41,7 @@
     name="swh.core",
     description="Software Heritage core utilities",
     long_description=long_description,
-    long_description_content_type="text/markdown",
+    long_description_content_type="text/x-rst",
     python_requires=">=3.7",
     author="Software Heritage developers",
     author_email="swh-devel@inria.fr",