Use linked directories to share docs between scala and java

Inspired by 1b2b8439ae47957a6357160608956cf3c0e7555f

Partially scripted with the 'link-common-sections.sh' script at
https://github.com/johanandren/akkadocs-sphinx2paradox/pull/3/files

akka-docs/src/main/paradox/experimental/index-java.md

@@ -1,4 +1,4 @@
 # Experimental Modules
 
 The label experimental caused confusion and discomfort and has therefore been replaced with "May Change"
-please see @ref:[Modules marked "May Change"](../common/may-change.md).
+please see @ref:[Modules marked "May Change"](../scala/common/may-change.md).

akka-docs/src/main/paradox/experimental/index.md

@@ -1,4 +1,4 @@
 # Experimental Modules
 
 The label experimental caused confusion and discomfort and has therefore been replaced with "May Change"
-please see @ref:[Modules marked "May Change"](../common/may-change.md).
+please see @ref:[Modules marked "May Change"](../scala/common/may-change.md).

akka-docs/src/main/paradox/index.md

@@ -4,7 +4,6 @@
 
 @@@ index
 
-* [guide](guide/index.md)
 * [java](java.md)
 * [scala](scala.md)
 

akka-docs/src/main/paradox/java.md

@@ -4,9 +4,9 @@
 
 @@@ index
 
-* [security/index](security/index.md)
+* [security/index](java/security/index.md)
-* [intro/index-java](intro/index-java.md)
+* [intro/index-java](java/intro/index-java.md)
-* [general/index](general/index.md)
+* [general/index](java/general/index.md)
 * [java/index-actors](java/index-actors.md)
 * [java/index-futures](java/index-futures.md)
 * [java/index-network](java/index-network.md)
@@ -15,8 +15,8 @@
 * [java/http/index](java/http/index.md)
 * [java/howto](java/howto.md)
 * [java/scala-compat](java/scala-compat.md)
-* [dev/index](dev/index.md)
+* [dev/index](java/dev/index.md)
-* [project/index](project/index.md)
+* [project/index](java/project/index.md)
-* [additional/index](additional/index.md)
+* [additional/index](java/additional/index.md)
 
 @@@

akka-docs/src/main/paradox/java/actors.md

@@ -17,8 +17,8 @@ its syntax from Erlang.
 
 Since Akka enforces parental supervision every actor is supervised and
 (potentially) the supervisor of its children, it is advisable that you
-familiarize yourself with @ref:[Actor Systems](../general/actor-systems.md) and <!-- FIXME: More than one link target with name supervision in path Some(/java/actors.rst) --> supervision and it
+familiarize yourself with @ref:[Actor Systems](../scala/general/actor-systems.md) and <!-- FIXME: More than one link target with name supervision in path Some(/java/actors.rst) --> supervision and it
-may also help to read @ref:[Actor References, Paths and Addresses](../general/addressing.md).
+may also help to read @ref:[Actor References, Paths and Addresses](../scala/general/addressing.md).
 
 @@@
 
@@ -140,7 +140,7 @@ create a child actor.
 
 It is recommended to create a hierarchy of children, grand-children and so on
 such that it fits the logical failure-handling structure of the application,
-see @ref:[Actor Systems](../general/actor-systems.md).
+see @ref:[Actor Systems](../scala/general/actor-systems.md).
 
 The call to `actorOf` returns an instance of `ActorRef`. This is a
 handle to the actor instance and the only way to interact with it. The
@@ -175,7 +175,7 @@ constructor arguments are determined by a dependency injection framework.
 You might be tempted at times to offer an `IndirectActorProducer`
 which always returns the same instance, e.g. by using a static field. This is
 not supported, as it goes against the meaning of an actor restart, which is
-described here: @ref:[What Restarting Means](../general/supervision.md#supervision-restart).
+described here: @ref:[What Restarting Means](../scala/general/supervision.md#supervision-restart).
 
 When using a dependency injection framework, actor beans *MUST NOT* have
 singleton scope.
@@ -374,7 +374,7 @@ usual.
 Be aware that the ordering of failure notifications relative to user messages
 is not deterministic. In particular, a parent might restart its child before
 it has processed the last messages sent by the child before the failure.
-See @ref:[Discussion: Message Ordering](../general/message-delivery-reliability.md#message-ordering) for details.
+See @ref:[Discussion: Message Ordering](../scala/general/message-delivery-reliability.md#message-ordering) for details.
 
 @@@
 
@@ -390,7 +390,7 @@ sent to a stopped actor will be redirected to the `deadLetters` of the
 <a id="actorselection-java"></a>
 ## Identifying Actors via Actor Selection
 
-As described in @ref:[Actor References, Paths and Addresses](../general/addressing.md), each actor has a unique logical path, which
+As described in @ref:[Actor References, Paths and Addresses](../scala/general/addressing.md), each actor has a unique logical path, which
 is obtained by following the chain of actors from child to parent until
 reaching the root of the actor system, and it has a physical path, which may
 differ if the supervision chain includes any remote supervisors. These paths
@@ -573,7 +573,7 @@ on the enclosing actor from within the callback. This would break the actor
 encapsulation and may introduce synchronization bugs and race conditions because
 the callback will be scheduled concurrently to the enclosing actor. Unfortunately
 there is not yet a way to detect these illegal accesses at compile time. See also:
-@ref:[Actors and shared mutable state](../general/jmm.md#jmm-shared-state)
+@ref:[Actors and shared mutable state](../scala/general/jmm.md#jmm-shared-state)
 
 @@@
 
@@ -784,7 +784,7 @@ is only used for debugging/logging.
 Tasks added to the same phase are executed in parallel without any ordering assumptions.
 Next phase will not start until all tasks of previous phase have been completed.
 
-If tasks are not completed within a configured timeout (see @ref:[reference.conf](../general/configuration.md#config-akka-actor))
+If tasks are not completed within a configured timeout (see @ref:[reference.conf](../scala/general/configuration.md#config-akka-actor))
 the next phase will be started anyway. It is possible to configure `recover=off` for a phase
 to abort the rest of the shutdown process if a task fails or is not completed within the timeout.
 
@@ -938,7 +938,7 @@ You can kill an actor by sending a `Kill` message. This will cause the actor
 to throw a `ActorKilledException`, triggering a failure. The actor will
 suspend operation and its supervisor will be asked how to handle the failure,
 which may mean resuming the actor, restarting it or terminating it completely.
-See @ref:[What Supervision Means](../general/supervision.md#supervision-directives) for more information.
+See @ref:[What Supervision Means](../scala/general/supervision.md#supervision-directives) for more information.
 
 Use `Kill` like this:
 
@@ -1008,7 +1008,7 @@ Please note, that the child actors are *still restarted*, but no new `ActorRef`
 the same principles for the children, ensuring that their `preStart()` method is called only at the creation of their
 refs.
 
-For more information see @ref:[What Restarting Means](../general/supervision.md#supervision-restart).
+For more information see @ref:[What Restarting Means](../scala/general/supervision.md#supervision-restart).
 
 ### Initialization via message passing
 

akka-docs/src/main/paradox/java/additional

@@ -0,0 +1 @@
+../scala/additional

akka-docs/src/main/paradox/java/agents.md

@@ -81,7 +81,7 @@ See @ref:[Futures](futures.md) for more information on `Futures`.
 ## Configuration
 
 There are several configuration properties for the agents module, please refer
-to the @ref:[reference configuration](../general/configuration.md#config-akka-agent).
+to the @ref:[reference configuration](../scala/general/configuration.md#config-akka-agent).
 
 ## Deprecated Transactional Agents
 

akka-docs/src/main/paradox/java/camel.md

@@ -414,7 +414,7 @@ using the Camel Quartz component
 ## Configuration
 
 There are several configuration properties for the Camel module, please refer
-to the @ref:[reference configuration](../general/configuration.md#config-akka-camel).
+to the @ref:[reference configuration](../scala/general/configuration.md#config-akka-camel).
 
 ## Additional Resources
 

akka-docs/src/main/paradox/java/cluster-usage.md

@@ -775,7 +775,7 @@ Make sure you understand the security implications of enabling remote monitoring
 ## Configuration
 
 There are several configuration properties for the cluster. We refer to the
-@ref:[reference configuration](../general/configuration.md#config-akka-cluster) for more information.
+@ref:[reference configuration](../scala/general/configuration.md#config-akka-cluster) for more information.
 
 ### Cluster Info Logging
 

akka-docs/src/main/paradox/java/common

@@ -0,0 +1 @@
+../scala/common

akka-docs/src/main/paradox/java/dev

@@ -0,0 +1 @@
+../scala/dev

akka-docs/src/main/paradox/java/distributed-pub-sub.md

@@ -174,7 +174,7 @@ akka.extensions = ["akka.cluster.pubsub.DistributedPubSub"]
 
 ## Delivery Guarantee
 
-As in @ref:[Message Delivery Reliability](../general/message-delivery-reliability.md) of Akka, message delivery guarantee in distributed pub sub modes is **at-most-once delivery**.
+As in @ref:[Message Delivery Reliability](../scala/general/message-delivery-reliability.md) of Akka, message delivery guarantee in distributed pub sub modes is **at-most-once delivery**.
 In other words, messages can be lost over the wire.
 
 If you are looking for at-least-once delivery guarantee, we recommend [Kafka Akka Streams integration](https://github.com/akka/reactive-kafka).

akka-docs/src/main/paradox/java/fault-tolerance.md

@@ -1,6 +1,6 @@
 # Fault Tolerance
 
-As explained in @ref:[Actor Systems](../general/actor-systems.md) each actor is the supervisor of its
+As explained in @ref:[Actor Systems](../scala/general/actor-systems.md) each actor is the supervisor of its
 children, and as such each actor defines fault handling supervisor strategy.
 This strategy cannot be changed afterwards as it is an integral part of the
 actor system’s structure.
@@ -96,7 +96,7 @@ by overriding the `logFailure` method.
 ## Supervision of Top-Level Actors
 
 Toplevel actors means those which are created using `system.actorOf()`, and
-they are children of the @ref:[User Guardian](../general/supervision.md#user-guardian). There are no
+they are children of the @ref:[User Guardian](../scala/general/supervision.md#user-guardian). There are no
 special rules applied in this case, the guardian simply applies the configured
 strategy.
 

akka-docs/src/main/paradox/java/general

@@ -0,0 +1 @@
+../scala/general

akka-docs/src/main/paradox/java/guide

@@ -0,0 +1 @@
+../scala/guide

akka-docs/src/main/paradox/java/index-network.md

@@ -4,7 +4,7 @@
 
 @@@ index
 
-* [../common/cluster](../common/cluster.md)
+* [../scala/common/cluster](../scala/common/cluster.md)
 * [cluster-usage](cluster-usage.md)
 * [cluster-singleton](cluster-singleton.md)
 * [distributed-pub-sub](distributed-pub-sub.md)

akka-docs/src/main/paradox/java/index-utilities.md

@@ -7,9 +7,9 @@
 * [event-bus](event-bus.md)
 * [logging](logging.md)
 * [scheduler](scheduler.md)
-* [../common/duration](../common/duration.md)
+* [../scala/common/duration](../scala/common/duration.md)
-* [../common/circuitbreaker](../common/circuitbreaker.md)
+* [../scala/common/circuitbreaker](../scala/common/circuitbreaker.md)
 * [extending-akka](extending-akka.md)
-* [../intro/deployment-scenarios](../intro/deployment-scenarios.md)
+* [../scala/intro/deployment-scenarios](../scala/intro/deployment-scenarios.md)
 
 @@@

akka-docs/src/main/paradox/java/intro

@@ -0,0 +1 @@
+../scala/intro

akka-docs/src/main/paradox/java/io.md

@@ -101,4 +101,4 @@ A `ByteStringBuilder` can be wrapped in a `java.io.OutputStream` via the `asOutp
 
 ## Architecture in-depth
 
-For further details on the design and internal architecture see @ref:[I/O Layer Design](../dev/io-layer.md).
+For further details on the design and internal architecture see @ref:[I/O Layer Design](../scala/dev/io-layer.md).

akka-docs/src/main/paradox/java/persistence.md

@@ -1098,7 +1098,7 @@ When testing Persistence based projects always rely on @ref:[asynchronous messag
 ## Configuration
 
 There are several configuration properties for the persistence module, please refer
-to the @ref:[reference configuration](../general/configuration.md#config-akka-persistence).
+to the @ref:[reference configuration](../scala/general/configuration.md#config-akka-persistence).
 
 ## Multiple persistence plugin configurations
 

akka-docs/src/main/paradox/java/project

@@ -0,0 +1 @@
+../scala/project

akka-docs/src/main/paradox/java/remoting-artery.md

@@ -2,7 +2,7 @@
 
 @@@ note
 
-This page describes the @ref:[may change](../common/may-change.md) remoting subsystem, codenamed *Artery* that will eventually
+This page describes the @ref:[may change](../scala/common/may-change.md) remoting subsystem, codenamed *Artery* that will eventually
 replace the old remoting implementation. For the current stable remoting system please refer to @ref:[Remoting](remoting.md).
 
 @@@
@@ -170,7 +170,7 @@ and automatically reply to with a `ActorIdentity` message containing the
 the `ActorSelection`, which returns a `Future` of the matching
 `ActorRef`.
 
-For more details on how actor addresses and paths are formed and used, please refer to @ref:[Actor References, Paths and Addresses](../general/addressing.md).
+For more details on how actor addresses and paths are formed and used, please refer to @ref:[Actor References, Paths and Addresses](../scala/general/addressing.md).
 
 @@@ note
 
@@ -354,7 +354,7 @@ marking them `PossiblyHarmful` so that a client cannot forge them.
 
 Akka remoting is using Aeron as underlying message transport. Aeron is using UDP and adds
 among other things reliable delivery and session semantics, very similar to TCP. This means that
-the order of the messages are preserved, which is needed for the @ref:[Actor message ordering guarantees](../general/message-delivery-reliability.md#message-ordering).
+the order of the messages are preserved, which is needed for the @ref:[Actor message ordering guarantees](../scala/general/message-delivery-reliability.md#message-ordering).
 Under normal circumstances all messages will be delivered but there are cases when messages
 may not be delivered to the destination:
 
@@ -363,7 +363,7 @@ may not be delivered to the destination:
  * if serialization or deserialization of a message fails (only that message will be dropped)
  * if an unexpected exception occurs in the remoting infrastructure
 
-In short, Actor message delivery is “at-most-once” as described in @ref:[Message Delivery Reliability](../general/message-delivery-reliability.md)
+In short, Actor message delivery is “at-most-once” as described in @ref:[Message Delivery Reliability](../scala/general/message-delivery-reliability.md)
 
 Some messages in Akka are called system messages and those cannot be dropped because that would result
 in an inconsistent state between the systems. Such messages are used for essentially two features; remote death
@@ -748,7 +748,7 @@ crashes unexpectedly.
 for production systems.
 
 The location of the file can be controlled via the *akka.remote.artery.advanced.flight-recoder.destination* setting (see
-@ref:[akka-remote (artery)](../general/configuration.md#config-akka-remote-artery) for details). By default, a file with the *.afr* extension is produced in the temporary
+@ref:[akka-remote (artery)](../scala/general/configuration.md#config-akka-remote-artery) for details). By default, a file with the *.afr* extension is produced in the temporary
 directory of the operating system. In cases where the flight recorder casuses issues, it can be disabled by adding the
 setting *akka.remote.artery.advanced.flight-recorder.enabled=off*, although this is not recommended.
 
@@ -756,7 +756,7 @@ setting *akka.remote.artery.advanced.flight-recorder.enabled=off*, although this
 ## Remote Configuration
 
 There are lots of configuration properties that are related to remoting in Akka. We refer to the
-@ref:[reference configuration](../general/configuration.md#config-akka-remote-artery) for more information.
+@ref:[reference configuration](../scala/general/configuration.md#config-akka-remote-artery) for more information.
 
 @@@ note
 

akka-docs/src/main/paradox/java/remoting.md

@@ -9,7 +9,7 @@ peer-to-peer fashion and it has limitations for client-server setups. In
 particular Akka Remoting does not work transparently with Network Address Translation,
 Load Balancers, or in Docker containers. For symmetric communication in these situations
 network and/or Akka configuration will have to be changed as described in
-@ref:[Peer-to-Peer vs. Client-Server](../general/remoting.md#symmetric-communication).
+@ref:[Peer-to-Peer vs. Client-Server](../scala/general/remoting.md#symmetric-communication).
 
 @@@
 
@@ -95,7 +95,7 @@ the `ActorSelection`, which returns a `CompletionStage` of the matching
 
 @@@ note
 
-For more details on how actor addresses and paths are formed and used, please refer to @ref:[Actor References, Paths and Addresses](../general/addressing.md).
+For more details on how actor addresses and paths are formed and used, please refer to @ref:[Actor References, Paths and Addresses](../scala/general/addressing.md).
 
 @@@
 
@@ -495,7 +495,7 @@ Creating and working with keystores and certificates is well documented in the
 [Generating X.509 Certificates](http://typesafehub.github.io/ssl-config/CertificateGeneration.html#using-keytool)
 section of Lightbend's SSL-Config library.
 
-Since an Akka remoting is inherently @ref:[peer-to-peer](../general/remoting.md#symmetric-communication) both the key-store as well as trust-store
+Since an Akka remoting is inherently @ref:[peer-to-peer](../scala/general/remoting.md#symmetric-communication) both the key-store as well as trust-store
 need to be configured on each remoting node participating in the cluster.
 
 The official [Java Secure Socket Extension documentation](http://docs.oracle.com/javase/7/jdocs/technotes/guides/security/jsse/JSSERefGuide.html)
@@ -592,7 +592,7 @@ marking them `PossiblyHarmful` so that a client cannot forge them.
 ## Remote Configuration
 
 There are lots of configuration properties that are related to remoting in Akka. We refer to the
-@ref:[reference configuration](../general/configuration.md#config-akka-remote) for more information.
+@ref:[reference configuration](../scala/general/configuration.md#config-akka-remote) for more information.
 
 @@@ note
 

akka-docs/src/main/paradox/java/security

@@ -0,0 +1 @@
+../scala/security

akka-docs/src/main/paradox/java/stream/index.md

@@ -6,7 +6,7 @@
 
 * [stream-introduction](stream-introduction.md)
 * [stream-quickstart](stream-quickstart.md)
-* [../../general/stream/stream-design](../../general/stream/stream-design.md)
+* [../../scala/general/stream/stream-design](../../scala/general/stream/stream-design.md)
 * [stream-flows-and-basics](stream-flows-and-basics.md)
 * [stream-graphs](stream-graphs.md)
 * [stream-composition](stream-composition.md)
@@ -20,6 +20,6 @@
 * [stream-testkit](stream-testkit.md)
 * [stages-overview](stages-overview.md)
 * [stream-cookbook](stream-cookbook.md)
-* [../../general/stream/stream-configuration](../../general/stream/stream-configuration.md)
+* [../../scala/general/stream/stream-configuration](../../scala/general/stream/stream-configuration.md)
 
 @@@

akka-docs/src/main/paradox/java/stream/stream-introduction.md

@@ -65,7 +65,7 @@ and for best results we recommend the following approach:
 
  * Read the @ref:[Quick Start Guide](stream-quickstart.md#stream-quickstart-java) to get a feel for how streams
 look like and what they can do.
- * The top-down learners may want to peruse the @ref:[Design Principles behind Akka Streams](../../general/stream/stream-design.md) at this
+ * The top-down learners may want to peruse the @ref:[Design Principles behind Akka Streams](../../scala/general/stream/stream-design.md) at this
 point.
  * The bottom-up learners may feel more at home rummaging through the
 @ref:[Streams Cookbook](stream-cookbook.md).

akka-docs/src/main/paradox/java/stream/stream-quickstart.md

@@ -3,7 +3,7 @@
 # Quick Start Guide
 
 Create a project and add the akka-streams dependency to the build tool of your
-choice as described in @ref:[Using a build tool](../../intro/getting-started.md#build-tool).
+choice as described in @ref:[Using a build tool](../../scala/intro/getting-started.md#build-tool).
 
 A stream usually begins at a source, so this is also how we start an Akka
 Stream. Before we create one, we import the full complement of streaming tools:

akka-docs/src/main/paradox/java/testing.md

@@ -316,7 +316,7 @@ for managing time constraints:
 
 @@snip [TestKitDocTest.java](code/jdocs/testkit/TestKitDocTest.java) { #test-within }
 
-The block in `within` must complete after a @ref:[Duration](../common/duration.md) which
+The block in `within` must complete after a @ref:[Duration](../scala/common/duration.md) which
 is between `min` and `max`, where the former defaults to zero. The
 deadline calculated by adding the `max` parameter to the block's start
 time is implicitly available within the block to all examination methods, if
@@ -679,4 +679,4 @@ akka {
 ## Configuration
 
 There are several configuration properties for the TestKit module, please refer
-to the @ref:[reference configuration](../general/configuration.md#config-akka-testkit).
+to the @ref:[reference configuration](../scala/general/configuration.md#config-akka-testkit).

akka-docs/src/main/paradox/scala.md

@@ -4,9 +4,10 @@
 
 @@@ index
 
-* [security/index](security/index.md)
+* [scala/guide](scala/guide/index.md)
-* [intro/index-scala](intro/index-scala.md)
+* [security/index](scala/security/index.md)
-* [general/index](general/index.md)
+* [intro/index-scala](scala/intro/index-scala.md)
+* [general/index](scala/general/index.md)
 * [scala/index-actors](scala/index-actors.md)
 * [scala/index-futures](scala/index-futures.md)
 * [scala/index-network](scala/index-network.md)
@@ -14,8 +15,8 @@
 * [scala/stream/index](scala/stream/index.md)
 * [scala/http/index](scala/http/index.md)
 * [scala/howto](scala/howto.md)
-* [dev/index](dev/index.md)
+* [dev/index](scala/dev/index.md)
-* [project/index](project/index.md)
+* [project/index](scala/project/index.md)
-* [additional/index](additional/index.md)
+* [additional/index](scala/additional/index.md)
 
-@@@
+@@@

akka-docs/src/main/paradox/scala/actors.md

@@ -17,8 +17,8 @@ its syntax from Erlang.
 
 Since Akka enforces parental supervision every actor is supervised and
 (potentially) the supervisor of its children, it is advisable that you
-familiarize yourself with @ref:[Actor Systems](../general/actor-systems.md) and <!-- FIXME: More than one link target with name supervision in path Some(/scala/actors.rst) --> supervision and it
+familiarize yourself with @ref:[Actor Systems](../scala/general/actor-systems.md) and <!-- FIXME: More than one link target with name supervision in path Some(/scala/actors.rst) --> supervision and it
-may also help to read @ref:[Actor References, Paths and Addresses](../general/addressing.md).
+may also help to read @ref:[Actor References, Paths and Addresses](../scala/general/addressing.md).
 
 @@@
 
@@ -157,7 +157,7 @@ create a child actor.
 
 It is recommended to create a hierarchy of children, grand-children and so on
 such that it fits the logical failure-handling structure of the application,
-see @ref:[Actor Systems](../general/actor-systems.md).
+see @ref:[Actor Systems](../scala/general/actor-systems.md).
 
 The call to `actorOf` returns an instance of `ActorRef`. This is a
 handle to the actor instance and the only way to interact with it. The
@@ -200,7 +200,7 @@ constructor arguments are determined by a dependency injection framework.
 You might be tempted at times to offer an `IndirectActorProducer`
 which always returns the same instance, e.g. by using a `lazy val`. This is
 not supported, as it goes against the meaning of an actor restart, which is
-described here: @ref:[What Restarting Means](../general/supervision.md#supervision-restart).
+described here: @ref:[What Restarting Means](../scala/general/supervision.md#supervision-restart).
 
 When using a dependency injection framework, actor beans *MUST NOT* have
 singleton scope.
@@ -404,7 +404,7 @@ usual.
 Be aware that the ordering of failure notifications relative to user messages
 is not deterministic. In particular, a parent might restart its child before
 it has processed the last messages sent by the child before the failure.
-See @ref:[Discussion: Message Ordering](../general/message-delivery-reliability.md#message-ordering) for details.
+See @ref:[Discussion: Message Ordering](../scala/general/message-delivery-reliability.md#message-ordering) for details.
 
 @@@
 
@@ -420,7 +420,7 @@ sent to a stopped actor will be redirected to the `deadLetters` of the
 <a id="actorselection-scala"></a>
 ## Identifying Actors via Actor Selection
 
-As described in @ref:[Actor References, Paths and Addresses](../general/addressing.md), each actor has a unique logical path, which
+As described in @ref:[Actor References, Paths and Addresses](../scala/general/addressing.md), each actor has a unique logical path, which
 is obtained by following the chain of actors from child to parent until
 reaching the root of the actor system, and it has a physical path, which may
 differ if the supervision chain includes any remote supervisors. These paths
@@ -603,7 +603,7 @@ on the enclosing actor from within the callback. This would break the actor
 encapsulation and may introduce synchronization bugs and race conditions because
 the callback will be scheduled concurrently to the enclosing actor. Unfortunately
 there is not yet a way to detect these illegal accesses at compile time.
-See also: @ref:[Actors and shared mutable state](../general/jmm.md#jmm-shared-state)
+See also: @ref:[Actors and shared mutable state](../scala/general/jmm.md#jmm-shared-state)
 
 @@@
 
@@ -777,7 +777,7 @@ is only used for debugging/logging.
 Tasks added to the same phase are executed in parallel without any ordering assumptions.
 Next phase will not start until all tasks of previous phase have been completed.
 
-If tasks are not completed within a configured timeout (see @ref:[reference.conf](../general/configuration.md#config-akka-actor))
+If tasks are not completed within a configured timeout (see @ref:[reference.conf](../scala/general/configuration.md#config-akka-actor))
 the next phase will be started anyway. It is possible to configure `recover=off` for a phase
 to abort the rest of the shutdown process if a task fails or is not completed within the timeout.
 
@@ -945,7 +945,7 @@ You can kill an actor by sending a `Kill` message. This will cause the actor
 to throw a `ActorKilledException`, triggering a failure. The actor will
 suspend operation and its supervisor will be asked how to handle the failure,
 which may mean resuming the actor, restarting it or terminating it completely.
-See @ref:[What Supervision Means](../general/supervision.md#supervision-directives) for more information.
+See @ref:[What Supervision Means](../scala/general/supervision.md#supervision-directives) for more information.
 
 Use `Kill` like this:
 
@@ -1033,7 +1033,7 @@ Please note, that the child actors are *still restarted*, but no new `ActorRef`
 the same principles for the children, ensuring that their `preStart()` method is called only at the creation of their
 refs.
 
-For more information see @ref:[What Restarting Means](../general/supervision.md#supervision-restart).
+For more information see @ref:[What Restarting Means](../scala/general/supervision.md#supervision-restart).
 
 ### Initialization via message passing
 

akka-docs/src/main/paradox/scala/additional/faq.md

@@ -93,12 +93,12 @@ be different
 
 If you still do not see anything, look at what the logging of remote
 life-cycle events tells you (normally logged at INFO level) or switch on 
-@ref:[Auxiliary remote logging options](../java/logging.md#logging-remote-java)
+@ref:[Auxiliary remote logging options](../../java/logging.md#logging-remote-java)
 to see all sent and received messages (logged at DEBUG level).
 
 ### Which options shall I enable when debugging remoting issues?
 
-Have a look at the @ref:[Remote Configuration](../java/remoting.md#remote-configuration-java), the typical candidates are:
+Have a look at the @ref:[Remote Configuration](../../java/remoting.md#remote-configuration-java), the typical candidates are:
 
  * *akka.remote.log-sent-messages*
  * *akka.remote.log-received-messages*
@@ -170,4 +170,4 @@ To enable different types of debug logging add the following to your configurati
  * `akka.actor.debug.autoreceive` will log all *special* messages like `Kill`, `PoisonPill` e.t.c. sent to all actors
  * `akka.actor.debug.lifecycle` will log all actor lifecycle events of all actors
 
-Read more about it in the docs for @ref:[Logging](../java/logging.md) and @ref:[actor.logging-scala](../scala/testing.md#actor-logging-scala).
+Read more about it in the docs for @ref:[Logging](../../java/logging.md) and @ref:[actor.logging-scala](../../scala/testing.md#actor-logging-scala).

akka-docs/src/main/paradox/scala/additional/index.md

@@ -10,4 +10,4 @@
 * [books](books.md)
 * [osgi](osgi.md)
 
-@@@
+@@@

akka-docs/src/main/paradox/scala/agents.md

@@ -109,7 +109,7 @@ Example of monadic usage:
 ## Configuration
 
 There are several configuration properties for the agents module, please refer
-to the @ref:[reference configuration](../general/configuration.md#config-akka-agent).
+to the @ref:[reference configuration](../scala/general/configuration.md#config-akka-agent).
 
 ## Deprecated Transactional Agents
 

akka-docs/src/main/paradox/scala/camel.md

@@ -403,7 +403,7 @@ using the Camel Quartz component
 ## Configuration
 
 There are several configuration properties for the Camel module, please refer
-to the @ref:[reference configuration](../general/configuration.md#config-akka-camel).
+to the @ref:[reference configuration](../scala/general/configuration.md#config-akka-camel).
 
 ## Additional Resources
 

akka-docs/src/main/paradox/scala/cluster-usage.md

@@ -717,12 +717,12 @@ and to the registered subscribers on the system event bus with the help of `clus
 
 ## How to Test
 
-@ref:[Multi Node Testing](../dev/multi-node-testing.md) is useful for testing cluster applications.
+@ref:[Multi Node Testing](../scala/dev/multi-node-testing.md) is useful for testing cluster applications.
 
-Set up your project according to the instructions in @ref:[Multi Node Testing](../dev/multi-node-testing.md) and @ref:[Multi JVM Testing](../dev/multi-jvm-testing.md), i.e.
+Set up your project according to the instructions in @ref:[Multi Node Testing](../scala/dev/multi-node-testing.md) and @ref:[Multi JVM Testing](../scala/dev/multi-jvm-testing.md), i.e.
 add the `sbt-multi-jvm` plugin and the dependency to `akka-multi-node-testkit`.
 
-First, as described in @ref:[Multi Node Testing](../dev/multi-node-testing.md), we need some scaffolding to configure the `MultiNodeSpec`.
+First, as described in @ref:[Multi Node Testing](../scala/dev/multi-node-testing.md), we need some scaffolding to configure the `MultiNodeSpec`.
 Define the participating roles and their [cluster_configuration_scala](#cluster-configuration-scala) in an object extending `MultiNodeConfig`:
 
 @@snip [StatsSampleSpec.scala]../../../../../akka-cluster-metrics/src/multi-jvm/scala/akka/cluster/metrics/sample/StatsSampleSpec.scala) { #MultiNodeConfig }
@@ -839,7 +839,7 @@ Make sure you understand the security implications of enabling remote monitoring
 ## Configuration
 
 There are several configuration properties for the cluster. We refer to the
-@ref:[reference configuration](../general/configuration.md#config-akka-cluster) for more information.
+@ref:[reference configuration](../scala/general/configuration.md#config-akka-cluster) for more information.
 
 ### Cluster Info Logging
 

akka-docs/src/main/paradox/scala/common/may-change.md

@@ -33,7 +33,7 @@ These are the current complete modules marked as **may change**:
 @@@ index
 
 * [../dev/multi-node-testing](../dev/multi-node-testing.md)
-* [../scala/typed](../scala/typed.md)
+* [../../scala/typed](../../scala/typed.md)
 
 @@@
 

akka-docs/src/main/paradox/scala/dev/multi-jvm-testing.md

@@ -9,7 +9,7 @@ The multi-JVM testing is an sbt plugin that you can find at [http://github.com/s
 
 You can add it as a plugin by adding the following to your project/plugins.sbt:
 
-@@snip [plugins.sbt]../../../../../project/plugins.sbt) { #sbt-multi-jvm }
+@@snip [plugins.sbt]../project/plugins.sbt) { #sbt-multi-jvm }
 
 You can then add multi-JVM testing to `build.sbt` or `project/Build.scala` by including the `MultiJvm`
 settings and config. Please note that MultiJvm test sources are located in `src/multi-jvm/...`,
@@ -197,4 +197,4 @@ the sbt prompt.
 
 There has also been some additions made to the `SbtMultiJvm` plugin to accommodate the
 @ref:[may change](../common/may-change.md) module @ref:[multi node testing](multi-node-testing.md),
-described in that section.
+described in that section.

akka-docs/src/main/paradox/scala/distributed-pub-sub.md

@@ -177,7 +177,7 @@ akka.extensions = ["akka.cluster.pubsub.DistributedPubSub"]
 
 ## Delivery Guarantee
 
-As in @ref:[Message Delivery Reliability](../general/message-delivery-reliability.md) of Akka, message delivery guarantee in distributed pub sub modes is **at-most-once delivery**.
+As in @ref:[Message Delivery Reliability](../scala/general/message-delivery-reliability.md) of Akka, message delivery guarantee in distributed pub sub modes is **at-most-once delivery**.
 In other words, messages can be lost over the wire.
 
 If you are looking for at-least-once delivery guarantee, we recommend [Kafka Akka Streams integration](https://github.com/akka/reactive-kafka).

akka-docs/src/main/paradox/scala/fault-tolerance.md

@@ -1,6 +1,6 @@
 # Fault Tolerance
 
-As explained in @ref:[Actor Systems](../general/actor-systems.md) each actor is the supervisor of its
+As explained in @ref:[Actor Systems](../scala/general/actor-systems.md) each actor is the supervisor of its
 children, and as such each actor defines fault handling supervisor strategy.
 This strategy cannot be changed afterwards as it is an integral part of the
 actor system’s structure.
@@ -104,7 +104,7 @@ by overriding the `logFailure` method.
 ## Supervision of Top-Level Actors
 
 Toplevel actors means those which are created using `system.actorOf()`, and
-they are children of the @ref:[User Guardian](../general/supervision.md#user-guardian). There are no
+they are children of the @ref:[User Guardian](../scala/general/supervision.md#user-guardian). There are no
 special rules applied in this case, the guardian simply applies the configured
 strategy.
 

akka-docs/src/main/paradox/scala/general/actor-systems.md

@@ -119,7 +119,7 @@ includes the following suggestions:
 
 >
  * Do the blocking call within an actor (or a set of actors managed by a router
-[@ref:[Java](../java/routing.md), @ref:[Scala](../scala/routing.md)]), making sure to
+[@ref:[Java](../../java/routing.md), @ref:[Scala](../../scala/routing.md)]), making sure to
 configure a thread pool which is either dedicated for this purpose or
 sufficiently sized.
  * Do the blocking call within a `Future`, ensuring an upper bound on
@@ -144,8 +144,8 @@ on which DBMS is deployed on what hardware.
 
 Configuring thread pools is a task best delegated to Akka, simply configure
 in the `application.conf` and instantiate through an `ActorSystem`
-[@ref:[Java](../java/dispatchers.md#dispatcher-lookup-java), @ref:[Scala
+[@ref:[Java](../../java/dispatchers.md#dispatcher-lookup-java), @ref:[Scala
-](../scala/dispatchers.md#dispatcher-lookup-scala)]
+](../../scala/dispatchers.md#dispatcher-lookup-scala)]
 
 @@@
 
@@ -167,4 +167,4 @@ actor, which in turn will recursively stop all its child actors, the system
 guardian.
 
 If you want to execute some operations while terminating `ActorSystem`,
-look at `CoordinatedShutdown` [@ref:[Java](../java/actors.md#coordinated-shutdown-java), @ref:[Scala](../scala/actors.md#coordinated-shutdown-scala)]
+look at `CoordinatedShutdown` [@ref:[Java](../../java/actors.md#coordinated-shutdown-java), @ref:[Scala](../../scala/actors.md#coordinated-shutdown-scala)]

akka-docs/src/main/paradox/scala/general/actors.md

@@ -5,7 +5,7 @@ hierarchies and are the smallest unit when building an application. This
 section looks at one such actor in isolation, explaining the concepts you
 encounter while implementing it. For a more in depth reference with all the
 details please refer to
-@ref:[Actors (Scala)](../scala/actors.md) and @ref:[Actors (Java)](../java/actors.md).
+@ref:[Actors (Scala)](../../scala/actors.md) and @ref:[Actors (Java)](../../java/actors.md).
 
 An actor is a container for [State](#state), [Behavior](#behavior), a [Mailbox](#mailbox), [Child Actors](#child-actors)
 and a [Supervisor Strategy](#supervisor-strategy). All of this is encapsulated behind an [Actor
@@ -32,7 +32,7 @@ publishes this information itself.
 
 Actor objects will typically contain some variables which reflect possible
 states the actor may be in. This can be an explicit state machine (e.g. using
-the @ref:[FSM](../scala/fsm.md) module), or it could be a counter, set of listeners,
+the @ref:[FSM](../../scala/fsm.md) module), or it could be a counter, set of listeners,
 pending requests, etc. These data are what make an actor valuable, and they
 must be protected from corruption by other actors. The good news is that Akka
 actors conceptually each have their own light-weight thread, which is
@@ -53,7 +53,7 @@ the actor. This is to enable the ability of self-healing of the system.
 
 Optionally, an actor's state can be automatically recovered to the state
 before a restart by persisting received messages and replaying them after
-restart (see @ref:[Persistence](../scala/persistence.md)).
+restart (see @ref:[Persistence](../../scala/persistence.md)).
 
 ## Behavior
 

akka-docs/src/main/paradox/scala/general/configuration.md

@@ -244,8 +244,8 @@ The configuration can also be used for application specific settings.
 A good practice is to place those settings in an Extension, as described in:
 
 >
- * Scala API: @ref:[extending-akka-scala.settings](../scala/extending-akka.md#extending-akka-scala-settings)
+ * Scala API: @ref:[extending-akka-scala.settings](../../scala/extending-akka.md#extending-akka-scala-settings)
- * Java API: @ref:[extending-akka-java.settings](../java/extending-akka.md#extending-akka-java-settings)
+ * Java API: @ref:[extending-akka-java.settings](../../java/extending-akka.md#extending-akka-java-settings)
 
 ## Configuring multiple ActorSystem
 

akka-docs/src/main/paradox/scala/general/jmm.md

@@ -67,6 +67,6 @@ Since Akka runs on the JVM there are still some rules to be followed.
 
  * Closing over internal Actor state and exposing it to other threads
 
-@@snip [SharedMutableStateDocSpec.scala](../scala/code/docs/actor/SharedMutableStateDocSpec.scala) { #mutable-state }
+@@snip [SharedMutableStateDocSpec.scala](../../scala/code/docs/actor/SharedMutableStateDocSpec.scala) { #mutable-state }
 
  * Messages **should** be immutable, this is to avoid the shared mutable state trap.

akka-docs/src/main/paradox/scala/general/message-delivery-reliability.md

@@ -280,13 +280,13 @@ acknowledgement
 
 The third becomes necessary by virtue of the acknowledgements not being guaranteed
 to arrive either. An ACK-RETRY protocol with business-level acknowledgements is
-supported by @ref:[At-Least-Once Delivery](../scala/persistence.md#at-least-once-delivery-scala) of the Akka Persistence module. Duplicates can be
+supported by @ref:[At-Least-Once Delivery](../../scala/persistence.md#at-least-once-delivery-scala) of the Akka Persistence module. Duplicates can be
-detected by tracking the identifiers of messages sent via @ref:[At-Least-Once Delivery](../scala/persistence.md#at-least-once-delivery-scala).
+detected by tracking the identifiers of messages sent via @ref:[At-Least-Once Delivery](../../scala/persistence.md#at-least-once-delivery-scala).
 Another way of implementing the third part would be to make processing the messages
 idempotent on the level of the business logic.
 
 Another example of implementing all three requirements is shown at
-<!-- FIXME: unresolved link reference: reliable-proxy --> reliable-proxy (which is now superseded by @ref:[At-Least-Once Delivery](../scala/persistence.md#at-least-once-delivery-scala)).
+<!-- FIXME: unresolved link reference: reliable-proxy --> reliable-proxy (which is now superseded by @ref:[At-Least-Once Delivery](../../scala/persistence.md#at-least-once-delivery-scala)).
 
 ### Event Sourcing
 
@@ -301,7 +301,7 @@ components may consume the event stream as a means to replicate the component’
 state on a different continent or to react to changes). If the component’s
 state is lost—due to a machine failure or by being pushed out of a cache—it can
 easily be reconstructed by replaying the event stream (usually employing
-snapshots to speed up the process). @ref:[Event sourcing](../scala/persistence.md#event-sourcing-scala) is supported by
+snapshots to speed up the process). @ref:[Event sourcing](../../scala/persistence.md#event-sourcing-scala) is supported by
 Akka Persistence.
 
 ### Mailbox with Explicit Acknowledgement
@@ -344,7 +344,7 @@ guaranteed delivery.
 ### How do I Receive Dead Letters?
 
 An actor can subscribe to class `akka.actor.DeadLetter` on the event
-stream, see @ref:[Event Stream](../java/event-bus.md#event-stream-java) (Java) or @ref:[Event Stream](../scala/event-bus.md#event-stream-scala)
+stream, see @ref:[Event Stream](../../java/event-bus.md#event-stream-java) (Java) or @ref:[Event Stream](../../scala/event-bus.md#event-stream-scala)
 (Scala) for how to do that. The subscribed actor will then receive all dead
 letters published in the (local) system from that point onwards. Dead letters
 are not propagated over the network, if you want to collect them in one place

akka-docs/src/main/paradox/scala/general/remoting.md

@@ -66,7 +66,7 @@ containers violates assumption 1, unless additional steps are taken in the
 network configuration to allow symmetric communication between involved systems.
 In such situations Akka can be configured to bind to a different network
 address than the one used for establishing connections between Akka nodes.
-See @ref:[Akka behind NAT or in a Docker container](../scala/remoting.md#remote-configuration-nat).
+See @ref:[Akka behind NAT or in a Docker container](../../scala/remoting.md#remote-configuration-nat).
 
 ## Marking Points for Scaling Up with Routers
 
@@ -81,4 +81,4 @@ up a configurable number of children of the desired type and route to them in
 the configured fashion. Once such a router has been declared, its configuration
 can be freely overridden from the configuration file, including mixing it with
 the remote deployment of (some of) the children. Read more about
-this in @ref:[Routing (Scala)](../scala/routing.md) and @ref:[Routing (Java)](../java/routing.md).
+this in @ref:[Routing (Scala)](../../scala/routing.md) and @ref:[Routing (Java)](../../java/routing.md).

akka-docs/src/main/paradox/scala/general/supervision.md

@@ -195,7 +195,7 @@ Provided as a built-in pattern the `akka.pattern.BackoffSupervisor` implements t
 
 This pattern is useful when the started actor fails <a id="^1" href="#1">[1]</a> because some external resource is not available,
 and we need to give it some time to start-up again. One of the prime examples when this is useful is
-when a @ref:[PersistentActor](../scala/persistence.md) fails (by stopping) with a persistence failure - which indicates that
+when a @ref:[PersistentActor](../../scala/persistence.md) fails (by stopping) with a persistence failure - which indicates that
 the database may be down or overloaded, in such situations it makes most sense to give it a little bit of time
 to recover before the peristent actor is started.
 
@@ -204,13 +204,13 @@ to recover before the peristent actor is started.
 The following Scala snippet shows how to create a backoff supervisor which will start the given echo actor after it has stopped
 because of a failure, in increasing intervals of 3, 6, 12, 24 and finally 30 seconds:
 
-@@snip [BackoffSupervisorDocSpec.scala](../scala/code/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-stop }
+@@snip [BackoffSupervisorDocSpec.scala](../../scala/code/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-stop }
 
 The above is equivalent to this Java code:
 
-@@snip [BackoffSupervisorDocTest.java](../java/code/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-imports }
+@@snip [BackoffSupervisorDocTest.java](../../java/code/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-imports }
 
-@@snip [BackoffSupervisorDocTest.java](../java/code/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-stop }
+@@snip [BackoffSupervisorDocTest.java](../../java/code/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-stop }
 
 Using a `randomFactor` to add a little bit of additional variance to the backoff intervals
 is highly recommended, in order to avoid multiple actors re-start at the exact same point in time,
@@ -225,23 +225,23 @@ crashes and the supervision strategy decides that it should restart.
 The following Scala snippet shows how to create a backoff supervisor which will start the given echo actor after it has crashed
 because of some exception, in increasing intervals of 3, 6, 12, 24 and finally 30 seconds:
 
-@@snip [BackoffSupervisorDocSpec.scala](../scala/code/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-fail }
+@@snip [BackoffSupervisorDocSpec.scala](../../scala/code/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-fail }
 
 The above is equivalent to this Java code:
 
-@@snip [BackoffSupervisorDocTest.java](../java/code/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-imports }
+@@snip [BackoffSupervisorDocTest.java](../../java/code/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-imports }
 
-@@snip [BackoffSupervisorDocTest.java](../java/code/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-fail }
+@@snip [BackoffSupervisorDocTest.java](../../java/code/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-fail }
 
 The `akka.pattern.BackoffOptions` can be used to customize the behavior of the back-off supervisor actor, below are some examples:
 
-@@snip [BackoffSupervisorDocSpec.scala](../scala/code/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-custom-stop }
+@@snip [BackoffSupervisorDocSpec.scala](../../scala/code/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-custom-stop }
 
 The above code sets up a back-off supervisor that requires the child actor to send a `akka.pattern.BackoffSupervisor.Reset` message
 to its parent when a message is successfully processed, resetting the back-off. It also uses a default stopping strategy, any exception
 will cause the child to stop.
 
-@@snip [BackoffSupervisorDocSpec.scala](../scala/code/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-custom-fail }
+@@snip [BackoffSupervisorDocSpec.scala](../../scala/code/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-custom-fail }
 
 The above code sets up a back-off supervisor that restarts the child after back-off if MyException is thrown, any other exception will be
 escalated. The back-off is automatically reset if the child does not throw any errors within 10 seconds.
@@ -279,4 +279,4 @@ Please note that creating one-off actors from an all-for-one supervisor entails
 that failures escalated by the temporary actor will affect all the permanent
 ones. If this is not desired, install an intermediate supervisor; this can very
 easily be done by declaring a router of size 1 for the worker, see
-@ref:[Routing](../scala/routing.md) or @ref:[Routing](../java/routing.md).
+@ref:[Routing](../../scala/routing.md) or @ref:[Routing](../../java/routing.md).