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
 -----------------------