diff --git a/akka-docs/intro/what-is-akka.rst b/akka-docs/intro/what-is-akka.rst
index c9f4e6bd18..17e20bade7 100644
--- a/akka-docs/intro/what-is-akka.rst
+++ b/akka-docs/intro/what-is-akka.rst
@@ -1,8 +1,8 @@
 What is Akka?
-====
+=============
 
 **Akka**
-^^^^^^
+--------
 
 **Simpler Scalability, Fault-Tolerance, Concurrency & Remoting through Actors**
 
@@ -11,23 +11,25 @@ We believe that writing correct concurrent, fault-tolerant and scalable applicat
 
 Download from `<http://akka.io/downloads/>`_
 
-**Akka implements a unique hybrid of:**
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Akka implements a unique hybrid of:
+-----------------------------------
 
-* `Actors <untyped-actors-java>`_, which gives you:
-  * Simple and high-level abstractions for concurrency and parallelism.
-  * Asynchronous, non-blocking and highly performant event-driven programming model.
-  * Very lightweight event-driven processes (create ~6.5 million actors on 4GB RAM).
-* `Failure management <fault-tolerance-java>`_ through supervisor hierarchies with `let-it-crash <http://letitcrash.com>`_ semantics. Excellent for writing highly fault-tolerant systems that never stop, systems that self-heal.
-* `Software Transactional Memory <stm-java>`_ (STM). (Distributed transactions coming soon).
-* `Transactors <transactors-java>`_: combine actors and STM into transactional actors. Allows you to compose atomic message flows with automatic retry and rollback.
-* `Remote actors <remote-actors-java>`_: highly performant distributed actors with remote supervision and error management.
-* Java and Scala API.
+- :ref:`untyped-actors-java`, which gives you:
 
-**Akka can be used in two different ways:**
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  - Simple and high-level abstractions for concurrency and parallelism.
+  - Asynchronous, non-blocking and highly performant event-driven programming model.
+  - Very lightweight event-driven processes (create ~6.5 million actors on 4GB RAM).
 
-* As a library: used by a web app, to be put into ‘WEB-INF/lib’ or as a regular JAR on your classpath.
-* As a microkernel: stand-alone kernel, embedding a servlet container and all the other modules.
+- :ref:`fault-tolerance-java` through supervisor hierarchies with `let-it-crash <http://letitcrash.com>`_ semantics. Excellent for writing highly fault-tolerant systems that never stop, systems that self-heal.
+- :ref:`stm-java` (STM). (Distributed transactions coming soon).
+- :ref:`transactors-java`: combine actors and STM into transactional actors. Allows you to compose atomic message flows with automatic retry and rollback.
+- :ref:`remote-actors-java`: highly performant distributed actors with remote supervision and error management.
+- Java and Scala API.
 
-See the `Use-case and Deployment Scenarios <deployment-scenarios>`_ for details.
+Akka can be used in two different ways:
+---------------------------------------
+
+- As a library: used by a web app, to be put into ‘WEB-INF/lib’ or as a regular JAR on your classpath.
+- As a microkernel: stand-alone kernel, embedding a servlet container and all the other modules.
+
+See the ref:`deployment-scenarios` for details.
diff --git a/akka-docs/java/fault-tolerance.rst b/akka-docs/java/fault-tolerance.rst
index 9aacecad44..b89b3978b4 100644
--- a/akka-docs/java/fault-tolerance.rst
+++ b/akka-docs/java/fault-tolerance.rst
@@ -1,3 +1,5 @@
+.. _fault-tolerance-java:
+
 Fault Tolerance Through Supervisor Hierarchies (Java)
 =====================================================
 
diff --git a/akka-docs/java/remote-actors.rst b/akka-docs/java/remote-actors.rst
index 3894f2dacc..8eb5573e16 100644
--- a/akka-docs/java/remote-actors.rst
+++ b/akka-docs/java/remote-actors.rst
@@ -1,3 +1,5 @@
+.. _remote-actors-java:
+
 Remote Actors (Java)
 ====================
 
diff --git a/akka-docs/java/stm.rst b/akka-docs/java/stm.rst
index ed44218804..df6761b52a 100644
--- a/akka-docs/java/stm.rst
+++ b/akka-docs/java/stm.rst
@@ -1,3 +1,5 @@
+.. _stm-java:
+
 Software Transactional Memory (Java)
 ====================================
 
diff --git a/akka-docs/java/untyped-actors.rst b/akka-docs/java/untyped-actors.rst
index 5a29d13ae5..1b73988aca 100644
--- a/akka-docs/java/untyped-actors.rst
+++ b/akka-docs/java/untyped-actors.rst
@@ -1,3 +1,5 @@
+.. _untyped-actors-java:
+
 Actors (Java)
 =============
 
diff --git a/akka-docs/scala/stm.rst b/akka-docs/scala/stm.rst
index 42cd67ce2c..c5bb99bcb4 100644
--- a/akka-docs/scala/stm.rst
+++ b/akka-docs/scala/stm.rst
@@ -1,3 +1,5 @@
+.. _stm-scala:
+
 Software Transactional Memory (Scala)
 =====================================