broken links + tuning

docs/index.adoc

@@ -2,7 +2,7 @@
 :toc: right
 :imagesdir: media/
 
-This tutorial will show you step-by-step how to build XP sites and apps with React rendering, helping you kickstart a React4xp project of your own.
+Introduction to server side React rendering with the Enonic framework.
 
 {zwsp} +
 
@@ -11,62 +11,44 @@ image:react4xp.svg[title="React4xp logo",width=256px]
 
 {zwsp} +
 
-== Upgrade
-
-If you are upgrading to lib-react4xp 5.x.x, please read this <<upgrade/v5#,upgrade guide>>.
-
 == Introduction
 
 [NOTE]
 ====
-A little bare-bone knowledge of link:https://reactjs.org/tutorial/tutorial.html[React] and link:https://developer.enonic.com/start[Enonic XP] is recommended.
+A little bare-bone knowledge of link:https://reactjs.org/tutorial/tutorial.html[React] and link:https://developer.enonic.com/start[Enonic XP] is recommended before you dive into this tutorial.
 ====
 
-
-React4XP is a library (with a companion build structure) that facilitates advanced use of React in Enonic XP, and:
+React4XP facilitates advanced use of React when rendering with Enonic XP
 
 * enables you to use TSX/JSX as a templating language, similar to other XP templating engines
 * supports isomorphic client- or serverside rendering and hydration,
 * handles build flow and compilation with automated optimized asset serving
 * is modular and flexible enough to cover many advanced use cases
 
-
-{zwsp} +
-
+
 == Tutorial overview
 
-After <<setup#, getting set up>>, we'll begin with *3 basic lessons* - just the minimum of what you need to get started:
+After <<setup#, getting set up>>, you start with *three basic lessons*:
 
 - <<hello-react#, Hello React: server and clientside>>: Meet the React4xp library and display a react component from content studio - first serverside rendered, then clientside.
 - <<editorial-data-and-props#, Editorial data and props>>: Use props to pass data - for example editorial data from XP - into the react component.
 - <<pages-parts-and-regions#, XP Pages, Parts, Regions and Content>>: Taking more advantage of the page-building powers in Content Studio - react rendering from any XP controller.
 
-
-{zwsp} +
-
-The next 5 lessons present a few more *advanced usages*:
+The following five lessons present a more *advanced use cases*:
 
 - <<source-file-structure#, Free source file structure>>: Which react components are available to React4xp (called _entries_), and how to reference them.
 - <<custom-flow-syntax#, Custom flow syntax>>: A more detailed and explicit syntax, for when your controller needs more control.
 - <<imports-and-dependency-chunks#, Imports, chunks, config, webpack>>: Importing things into your entries, and controlling the compilation rules and output.
 - <<guillotine#, Headless, part 1>>: Introduction of how to use React4xp in a headless-CMS context: set up a data endpoint that serves XP content as pure data, and have the already-rendered React4xp components add more content asynchronously with that content data.
 - <<webapp#, Headless, part 2>>: "pure headless" with preview - standalone webapps that take the same React4xp components out of Content Studio, and render the content with assets and data served from anywhere.
 
-{zwsp} +
-
-== Details
-If you *need to go deeper* after going through the lessons, the most important concepts you'll encounter along the way are explained on pages of their own:
+== Dive deeper
+Have an urge for details beyond the basic tutorial, check out the following:
 
 - <<entries#, Entries>>
 - <<jsxpath#, JsxPath>>
 - <<chunks#, Optimizing dependency chunks>>
-
-There's also an <<api#, API reference>> for the methods that the react4xp library (link:https://market.enonic.com/vendors/enonic/react4xp-lib[_lib-react4xp_]) exposes to the XP controllers:
-
-- <<api#react4xp_render, React4xp.render>>
-- <<api#react4xp_object, React4xp data objects>>
-
-{zwsp} +
+- <<api#, API reference>> for the (link:https://market.enonic.com/vendors/enonic/react4xp-lib[React4XP library]).
 
 == Issues?
 Questions, bug reports or suggestions are welcome!