diff --git a/akka-docs/src/main/paradox/images/outport_transitions.png b/akka-docs/src/main/paradox/images/outport_transitions.png
index 7eb407a464..455e793351 100644
Binary files a/akka-docs/src/main/paradox/images/outport_transitions.png and b/akka-docs/src/main/paradox/images/outport_transitions.png differ
diff --git a/akka-docs/src/main/paradox/images/port_transitions.svg b/akka-docs/src/main/paradox/images/port_transitions.svg
index 9ffbc0c011..22c24f942c 100644
--- a/akka-docs/src/main/paradox/images/port_transitions.svg
+++ b/akka-docs/src/main/paradox/images/port_transitions.svg
@@ -687,7 +687,7 @@
        id="g6720"
        transform="translate(54,0)">
       <rect
-         style="fill:none;stroke:#4e9a06;stroke-width:4;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+         style="fill:none;stroke:#000000;stroke-width:4;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
          id="rect6674"
          width="133.937"
          height="62.001453"
@@ -750,7 +750,7 @@
       <g
          id="g6729">
         <rect
-           style="fill:none;stroke:#000000;stroke-width:4;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+           style="fill:none;stroke:#4e9a06;stroke-width:4;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
            id="rect6692"
            width="133.937"
            height="62.001453"
diff --git a/akka-docs/src/main/paradox/stream/stream-customize.md b/akka-docs/src/main/paradox/stream/stream-customize.md
index 475701f7f5..f808dca956 100644
--- a/akka-docs/src/main/paradox/stream/stream-customize.md
+++ b/akka-docs/src/main/paradox/stream/stream-customize.md
@@ -96,8 +96,11 @@ Java
 ### Port states, @scala[InHandler] @java[AbstractInHandler] and @scala[OutHandler] @java[AbstractOutHandler]
 
 In order to interact with a port (`Inlet` or `Outlet`) of the operator we need to be able to receive events
-and generate new events belonging to the port. From the `GraphStageLogic` the following operations are available
-on an output port:
+and generate new events belonging to the port.
+
+#### Output port
+
+From the `GraphStageLogic` the following operations are available on an output port:
 
  * `push(out,elem)` pushes an element to the output port. Only possible after the port has been pulled by downstream.
  * `complete(out)` closes the output port normally.
@@ -123,6 +126,8 @@ in that state.
 
 ![outport_transitions.png](../images/outport_transitions.png)
 
+#### Input port
+
 The following operations are available for *input* ports:
 
  * `pull(in)` requests a new element from an input port. This is only possible after the port has been pushed by upstream.
@@ -154,11 +159,15 @@ in that state.
 
 ![inport_transitions.png](../images/inport_transitions.png)
 
+#### Complete and fail
+
 Finally, there are two methods available for convenience to complete the operator and all of its ports:
 
  * `completeStage()` is equivalent to closing all output ports and cancelling all input ports.
  * `failStage(exception)` is equivalent to failing all output ports and cancelling all input ports.
 
+#### Emit
+
 In some cases it is inconvenient and error prone to react on the regular state machine events with the
 signal based API described above. For those cases there is an API which allows for a more declarative sequencing
 of actions which will greatly simplify some use cases at the cost of some extra allocations. The difference