Docs improvements.

doczrc.js

@@ -73,8 +73,14 @@ export default {
         'How to change graphics or texts'
       ]
     },
-
-    'Reference',
+    {
+      name: 'Reference',
+      menu: [
+        'Stream state properties',
+        'Settable properties',
+        'Replay component reference'
+      ]
+    },
     'Controls reference',
     'Containers/helpers reference',
     'Generic controls reference'

src/replay/docs/advanced-playback/adaptive-streaming.mdx

@@ -72,7 +72,7 @@ const render = () => (
 
 ### MPEG-DASH with Shaka Player
 
-The Shaka Player video streamer component can be imported with the import statement added at the end:
+The Shaka Player video streamer component can be inserted after adding this import statement at the end:
 
 ```javascript
 import { Replay } from 'vimond-replay';
@@ -122,7 +122,9 @@ const render = () => (
 
 The helper component `<CompoundVideoStreamer/>`'s task is to select a compatible video streamer for Replay based on the stream type, and in a special case, also taking the browser into consideration. 
 
-For HLS, it inserts `<HlsjsVideoStreamer/>`, for MPEG-DASH `<ShakaVideoStreamer/>`. A progressive video source resolves to `<HtmlVideoStreamer/>`. The mentioned special case is the combination of Safari and HLS streams. Safari and the Apple operating systems support HLS natively, and the HTML video element play these streams optimally without any third party library. For this combination, the compound video streamer then selects `<HtmlVideoStreamer/>`. It includes support for FairPlay DRM.
+For HLS, it inserts `<HlsjsVideoStreamer/>`, for MPEG-DASH `<ShakaVideoStreamer/>`. A progressive video source resolves to `<HtmlVideoStreamer/>`. 
+
+The mentioned special case is the combination of Safari and HLS streams. Safari and the Apple operating systems support HLS natively, and the HTML video element play these streams optimally without any third party library. For this combination, the compound video streamer then selects `<HtmlVideoStreamer/>`. It includes support for FairPlay DRM.
 
 The mentioned third party player libraries are quite big, and adds several hundred kilobytes to the script bundle. Because of this, `<CompoundVideoStreamer/>` uses [React.lazy](https://reactjs.org/docs/code-splitting.html#reactlazy) and [dynamic imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Dynamic_Imports). It loads only one video streamer and its integrated third party library when needed.
 
@@ -141,7 +143,7 @@ The recognised mime types are as follows:
 * HLS: `application/x-mpegurl`, alternatively `vnd.apple.mpegurl`
 * Progressive MP4 or WebM: `video/mp4`, `video/webm`
 
-If the source is only specified as a string containing the URL to the manifest, playlist, or video file, the compound video streamer attempts detecting the stream type based on URL content.
+If the source is only specified as a string containing the URL to the manifest, playlist, or video file, the compound video streamer attempts detecting the stream type based on URL content. If the stream doesn't play as expected, try adding the correct `contentType` to the `Replay` source in order to eliminate incorrect stream type detections from the URL.
 
 ```javascript
 import React from 'react';

src/replay/docs/advanced-playback/bitrates.mdx

@@ -4,6 +4,6 @@ route: /advanced-playback/bitrates
 menu: 'Advanced playback'
 ---
 
-## Bitrates and adaptive quality selection
+# Bitrates and adaptive quality selection
 
 This chapter is not written yet, but will discuss how an underlying adaptive streaming library's quality management is exposed in Replay.

src/replay/docs/custom-player/add-controls-components.mdx

@@ -14,10 +14,14 @@ This chapter describes how to customise the player UI by bringing in new control
 
 ## The player composer
 
-The easiest approach to building a custom player, is to use the composePlayer method. It produces a React component from what's typically being subject to customisation. 
+The easiest approach to building a custom player, is to use the `composePlayer()` method. It produces a React component from some parts that typically are being subject to customisation requirements.
 
 ## Adding a title overlay - step by step
 
+In this example, the goal is to bring in a small overlay bar aligned at the top of the video area, presenting a video title with duration. This feature should be able for reuse every time the player is inserted, which is achieved by including the overlay as part of a custom Replay player component.
+
+The code blocks underneath are excerpts, while the full demo files are [available on GitHub](https://github.com/vimond/replay/tree/master/src/replay/docs/custom-player/example).
+
 ### The overlay component
 
 A simple video title overlay can be created this way:
@@ -135,7 +139,7 @@ The `TitleOverlay` component takes an `isUserActive` prop. This aligns good with
 
 `interactionState` and `isUserActive` comes from the [InteractionDetector](https://github.com/vimond/replay/blob/master/src/replay/components/player/containment-helpers/InteractionDetector.js) containment helper component.
 
-If using CSS rules, passing this prop would have been unnecessary. Instead a style rule for the TitleOverlay with `.replay-is-user-active` as a parent selector, could have been used to make the overlay visible, with invisible as default. 
+A side note: If using CSS rules, passing this prop would have been unnecessary. Instead a style rule for the TitleOverlay with `.replay-is-user-active` as a parent selector, could have been used to make the overlay visible, with invisible as default. 
 
 ### Connecting the control
 
@@ -148,7 +152,7 @@ import UnconnectedTitleOverlay from './TitleOverlay';
 const TitleOverlay = connectControl(UnconnectedTitleOverlay, ['duration', 'isPaused']);
 ```
 
-The array passed as the second parameter specifies from which [video state properties][/reference/observable-stream-state] the connected control should get updates. 
+The array passed as the second parameter specifies from which [video state properties](/reference/observable-stream-state) the connected control should get updates. 
 
 `connectControl()` also supports retrieving the same information from the component's static property `streamStateKeysForObservation`, as shown for [this actual control code](https://github.com/vimond/replay/blob/master/src/replay/components/controls/TimeDisplay/TimeDisplay.js#L91).
 
@@ -204,7 +208,7 @@ const renderPlayerUI = ({ configuration, externalProps }) => {
 };
 ```
 
-Observe that the `TitleOverlay` element gets the `title` and `isUserActive` props set directly as part of the render method scope. On the other hand `isPaused` and `duration` is taken care of implictly within the now connected `TitleOverlay` component.
+Observe that the `TitleOverlay` element gets the `title` and `isUserActive` props set directly as part of the render method scope. On the other hand, `isPaused` and `duration` is taken care of implicitly within the now connected `TitleOverlay` component. These props will be passed down through the controller context to the title overlay.
 
 ### Composing the custom player component
 

src/replay/docs/custom-player/custom-strings-graphics.mdx

@@ -16,7 +16,7 @@ One or both of these sets can be combined when creating a custom player, and als
 
 The easiest approach to replace the set of strings/and or graphics, is to use the `composePlayer()` method. It produces a React component from what's typically being subject to customisation.
 
-The [default Replay player](https://github.com/vimond/replay/blob/master/src/replay/default-player/Replay.js) is composed with these parameters:
+As a starting point, this is how the [default Replay player](https://github.com/vimond/replay/blob/master/src/replay/default-player/Replay.js) is composed, with parameters specifying the strings and graphics to be part of the Replay component:
 
 ```javascript
 import composePlayer from '../playerComposer';
@@ -37,7 +37,7 @@ export default Replay;
 
 The [default strings](https://github.com/vimond/replay/blob/master/src/replay/default-player/strings.js), as referred by the composition of the Replay player, are grouped by controls. The properties for each controls correspond to actually prop types expected by the control. Most of the strings are tooltip texts, with some exceptions.
 
-Similarly, for the [graphics for the default skin](https://github.com/vimond/replay/blob/master/src/replay/default-player/default-skin/graphics.js), the definitions are structured per control or component. Here, the property values are mainly SVG graphics from the Feather icon set, wrapped as React components, so that they can be rendered within the control directly.
+Similarly, for the [graphics for the default skin](https://github.com/vimond/replay/blob/master/src/replay/default-player/default-skin/graphics.js), the definitions are structured per control or component. Here, the property values are mainly SVG graphics from the [Feather](https://feathericons.com/) icon set, wrapped as React components, so that they can be rendered within the control directly.
 
 Again, the property keys refer to prop names of the controls. Graphics can be added to all props with type `React.Node`, as listed in the controls reference. And as long as the property values are accepted by React and the browser, the graphics or content can be any element types.
 

src/replay/docs/custom-player/overview.mdx

@@ -6,7 +6,7 @@ menu: 'Building a custom player'
 
 # Overview
 
-Besides what can be achieved through [configuration overrides](/custom-replay/configuration) or [CSS rules](/custom-replay/skins-styles), some approaches exist for creating a custom Replay player component.
+Besides what can be achieved through [configuration overrides](/custom-replay/configuration) or [CSS rules (skinning, layout)](/custom-replay/skins-styles), some approaches exist for creating a custom Replay player component.
 
 ## Strategies for customisation
 
@@ -30,6 +30,8 @@ This might be an option if the architecture and patterns don't match the require
 
 ## The anatomy of Replay
 
+These modules, components, and concepts are essential to the Replay architecture.
+
 * The [main player component](https://github.com/vimond/replay/blob/master/src/replay/default-player/Replay.js), created from the playerComposer. A custom player means a new main player component.
 * The [player controller](https://github.com/vimond/replay/blob/master/src/replay/components/player/PlayerController/PlayerController.js). This is reused when creating a new, custom player. [More about the PlayerController](/architecture/player-controller).
 * The [player UI](https://github.com/vimond/replay/blob/master/src/replay/default-player/playerUI.js) with element tree, [graphics](https://github.com/vimond/replay/blob/master/src/replay/default-player/default-skin/graphics.js), and [strings](https://github.com/vimond/replay/blob/master/src/replay/default-player/strings.js). One or all of these might be reused or replaced when creating a custom player.
@@ -42,6 +44,6 @@ This might be an option if the architecture and patterns don't match the require
 * Configuration. A custom player can replace the [base configuration](https://github.com/vimond/replay/blob/master/src/replay/default-player/baseConfiguration.js). Configuration [overrides can be specified](http://localhost:3000/#/custom-replay/configuration) when inserting Replay.
 * CSS. The [default skin](https://github.com/vimond/replay/blob/master/src/replay/default-player/default-skin/index.css) can be replaced or [rules can be overridden](/custom-replay/skins-styles).
 
-## Creating a new video streamer
+## Custom video streamers
 
-The purpose of creating a new video streamer would be wrapping other streaming libraries or "headless" players into a React component, exposing the same API as those included in the Replay npm package. There is currently no specific documentation on doing this.
+The purpose of creating a custom video streamer would be wrapping other streaming libraries or "headless" players into a React component, exposing the same API as those included in the Replay npm package. There is currently no specific documentation on doing this.

src/replay/docs/custom-replay/configuration.mdx

@@ -138,9 +138,9 @@ See [Skin toggling and CSS scoping with prefixed class names](/custom-replay/ski
 
 ## Including/excluding player controls
 
-Replay components can be used to build a fully custom player with controls removed, replaced, and/or new controls added. 
+Replay components and custom components can be used to build a fully custom player with controls removed, replaced, and/or new controls added. 
 
-However, for simpler customisations, individual controls can be included or excluded by adding a configuration override.
+However, for simpler customisations, individual controls from the default Replay user interface can be included or excluded by adding a configuration override.
 
 The array `{ controls: { includeControls: [] }}` can be used to specify what controls to include. If this configuration setting is omitted, all controls will be included. Otherwise, only the ones listed in the array will be listed.
 

src/replay/docs/custom-replay/skins-styles.mdx

@@ -41,7 +41,7 @@ This would change the "primary colour" (icon and button surfaces) into green.
 
 ### Building a new stylesheet
 
-The default stylesheet can be completely replaced. For this, either reuse individual modules from the Replay library and substitute others (like colors.css) with your own, or create a copy of the file found at the npm path `'vimond-replay/index.css'`. If reusing individual modules, they need to be referred individually by either a preprocessor (e.g. SASS, PostCSS, Webpack) or the browser.
+The default stylesheet can be completely replaced. For this, either reuse some individual [CSS modules from the Replay library](https://github.com/vimond/replay/tree/master/src/replay/default-player/default-skin) and substitute some others (like `colors.css`) with your own. Another alternative is simply creating and modifying a copy of the file found at the npm path `'vimond-replay/index.css'`. If reusing individual modules, they need to be referred individually by either a preprocessor (e.g. SASS, PostCSS, Webpack), or the browser itself.
 
 Please see the chapter below, "CSS module organisation", and refer the source code, in order to look into individual CSS modules.
 
@@ -93,11 +93,11 @@ In summary:
 
 ## CSS module organisation
 
-For reference, in the Replay code base, the default stylesheet is built with several CSS files with the following setup. However, replacement stylesheets can be organised independently of the default one.
+For reference, in the Replay code base, the [default stylesheet](https://github.com/vimond/replay/blob/master/src/replay/replay-default.css) is built with several CSS files with the following setup. However, replacement stylesheets can be organised independently of the default one.
 
-* Some distinct, but general CSS files when there is a requirement for styles specifically for a component/control. These are located next to the components in the `components/` hierarchy, and contain no skin or layout styles.
+* Some distinct, but general CSS files when there is a requirement for styles specifically for a component/control. These are located next to the components in the [`components/` hierarchy](https://github.com/vimond/replay/tree/master/src/replay/components), and contain no skin or layout styles.
 * There are no CSS or SASS variables used.
-* Style rules for the default skin, are organised in different files, located in `default-player/default-skin/`: `sizesAndLayout.css`, `colors.css`, `animations.css`, and assembled with some more styles in `index.css`. This kind of separation makes it fairly easy to change e.g. only the colours on all controls while being DRY.
+* Style rules for the default skin, are organised in different files, [located in `default-player/default-skin/`](https://github.com/vimond/replay/tree/master/src/replay/default-player/default-skin): `sizesAndLayout.css`, `colors.css`, `animations.css`, and assembled with some more styles in `index.css`. This kind of separation makes it fairly easy to change e.g. only the colours on all controls while being DRY.
 * `replay-default.css` includes all above and constitutes the full default stylesheet.
 
 

src/replay/docs/reference/replay-component.mdx

@@ -0,0 +1,9 @@
+---
+name: Replay component reference
+route: /reference/replay-component
+menu: 'Reference'
+---
+
+# Replay component reference
+
+The Replay component API docuentation is located in the menu [Using the Replay player](/replay/api).

src/replay/docs/using-replay/controlling-playback.mdx

@@ -111,9 +111,9 @@ this.handleStreamStateChange = stateProperties => {
 };
 ```
 
-See the [full reference of state propertie](/reference/observable-stream-state) for all keys/value types passed in this callback.
+See the [full reference of state properties](/reference/observable-stream-state) for all keys/value types passed in this callback.
 
-## Full example showing operations on, and observation of the playback
+## Full example showing operations on playback, and observations of the playback state
 
 <Playground>
   {() => {