doc cleanup, fix errors

docs/deployment.adoc

@@ -5,16 +5,16 @@
 In this chapter you will launch cloud instances of both Enonic and Next - link them together, and see the glorious result.
 
 == Introduction
-To complete this chapter, you´ll be using Enonic to host the XP side of things, and Vercel for the front-end - Vercel are the makers of Next.js.
+To complete this chapter, you'll be using Enonic to host the XP side of things, and Vercel for the front-end - Vercel are the makers of Next.js.
 
 NOTE: Both Enonic and Next.js are open source software projects and can be deployed more or less anywhere. Have a look at the https://developer.enonic.com/docs/hosting[Enonic platform hosting page] for more details.
 
 == Task: Sign up to Enonic
 
 Create an account to get a free developer instance of Enonic XP
 
-. **Sign up** for a https://enonic.com/sign-up/cloud-trial[free developer instance].
-. **Create a new solution** using the `CMS essentials` template. This will install applications like `Content Studio` and `Guillotine` automatically.
+. *Sign up* for a https://enonic.com/sign-up[free developer account].
+. *Create a new solution using the `CMS essentials` template*. This will install applications like `Content Studio` and `Guillotine` automatically.
 
 When the new solution has started, launch `Enonic XP Admin` to verify that everything is up and running.
 
@@ -57,11 +57,11 @@ NOTE: The URL should look something like this: `https://account-solution-environ
 
 == Task: Add your front-end to Git
 
-Vercel will need to access the code from a Git repo where your user has write access.
+Vercel (which will be hosting your front-end) will need write access to a Git repo with your code.
 
 . **Create a new Git repo** - Vercel supports Github, Gitlab and Bitbucket.
 +
-. **Commit and push** your Next.js app files to a new Git repo.
+. **Commit and push** your Next.js app files to a the new repo.
 
 
 == Task: Deploy Next app
@@ -73,6 +73,7 @@ You are now ready to deploy the the front-end application.
 +
 * ENONIC_API:<enonic route URL>
 * ENONIC_API_TOKEN:<yourSecret>
+* ENONIC_PROJECTS:moviedb/hmdb
 
 . **Verify the result**. The front-page of your app should now display a 404 - as you are back to the originally imported content without a site.
 +
@@ -89,32 +90,20 @@ NOTE: You now have to create your site and tree structure once more, or for conv
 
 . **Install the Next.XP app** `Solution` -> `Applications` -> `Install` -> Search for `Next.XP`, select it an click install
 . **Add configuration**.
-This way you can override defaults and add more configurations.
 +
 image:console-configure-app.png[title="Configure the Next.XP application in the solution console",width=769px]
 +
-By default `Next.XP` uses the following values:
-+
-`url: *http://127.0.0.1:3000*`
-+
-`secret: *mySecretKey*`
-+
-.Add the following lines to the app config field if you want to override default values:
+.Add the following lines to the app config field to override the default values:
 [source,properties]
 ----
 nextjs.default.url = <Vercel app URL>
 nextjs.default.secret = <yourSecret>
 ----
 +
-.You can also add as many named configurations as needed:
-[source,properties]
-----
-nextjs.<configurationName>.url = <Vercel app URL>
-nextjs.<configurationName>.secret = <yourSecret>
-----
+TIP: Remember, you can also create named configurations if needed.
 +
 NOTE: If you imported content from your local environment, the following two steps can be skipped
-. **Add the Next.XP app to the site**.Since you have already placed configuration on file, simply adding the app to the site will do the trick.
+. **Add the Next.XP app to the site** to activate preview.
 . **Save and verify** that the configuration is working by testing the Content Studio preview.
 
 == Task: Publish a page
@@ -128,4 +117,13 @@ image:cloud-preview.png[title="Front page as seen from Content Studio", width=14
 +
 image:live.png[title="Content rendered on the live server", width=1033px]
 
-Now that we have everything working, let's see how to add <<i18n#, multi-language>> support !
+== Summary, and whats Next?
+
+🎉 Congratulations 🥳 - You've reached the end of this tutorial - we hope you enjoyed it!
+
+There are other aspects of Enonic and Next.js that will never be covered by this tutorial - to learn more about Enonic check out the following resources:
+
+* https://developer.enonic.com[Enonic Developer portal]
+* https://developer.enonic.com/guides/developer-101/xp7[Enonic Developer 101]
+
+

docs/i18n.adoc

@@ -2,15 +2,50 @@
 :toc: right
 :imagesdir: media/
 
-In this chapter you will learn what it takes to make your project multi-language.
+In this chapter you will learn what it takes to support multi-language for your site.
 
 == Introduction
 
 Next.js has native multi-language support, allowing your projects to switch language on the fly.
-This is enabled by specifying locale list in the `next.config.js` file:
 
+To back this, Content Studio has a feature called content layering. This means you can create additional content projects that inherit content from another project, and the inherited items may then be translated and published independently of the parent items.
+
+== Task: Create a layered project
+
+To demonstrate multi-language, you first need to activate support for translating your content in Content Studio. In our case, let's try Norwegian.
+
+. **Create a new project** in Content Studio by clicking on the `Settings` cog icon, on the left-hand side of the grid. You will be presented with the currently available projects:
++
+image:content-studio-settings.png[title="Project list",width=1024px]
++
+Click `New...` button, and select type `Layer`. Then choose the `Movie DB` project as the parent
++
+image:content-studio-create-layer.png[title="Layered project type",width=1024px]
++
+Fill in the rest of the form, using the following values:
++
+* *Name*: `Film DB`
+* *Identifier*: `moviedb-no`
+* *Language*: `norsk (no)`
+* *Access mode*: `Public`
+* Other fields may be skipped
++
+After saving and closing the wizard, the new project should appear in the list.
++
+. *Verify the new layer* by going back to the content list (via the pencil icon), and then switching context using the context selector in the top bar.
++
+After switching context, you should see the following:
++
+image:content-studio-filmdb.png[title="Film DB project",width=1024px]
+
+== Task: Set up i18n in Next.js
+
+Next, let's turn on multi-language support in Next.js. 
+
+. Start by activating Next.js' multilanguage support by adding a few lintes to the `next.config.js` file:
++
 .next.config.js
-[source,JavaScript,options="nowrap"]
+[source,JSON]
 ----
 module.exports = {
     // ...
@@ -21,60 +56,87 @@ module.exports = {
     // ...
 }
 ----
++
+. *Configure the Enonic adapter*, by specifying which content project to use for each specific locale:
++
+..env
+[source,Properties]
+----
+// ...
+ENONIC_PROJECTS=moviedb/hmdb,no:moviedb-no/hmdb
+// ...
+----
++
+Let's break down the syntax.
++
+For each comma separated entry, you will find the following pattern: `<locale>:<repository>/<sitekey>`. From the example above `no:moviedb-no/hmdb`. 
++
+The first entry in the list may skip the locale. As it will map to the `defaultLocale` specified in `next.config.js` earlier. In our case,`en`.
++
+NOTE: The reason for repeating the is that when using paths, the path may be different in each project/translation.
 
-Full documentation is https://nextjs.org/docs/pages/building-your-application/routing/internationalization[available here].
-
-== Task: Create localized content
-
-First, we need to create some localized content in Enonic XP.
-To do that, go to Content Studio and click on the `Settings` icon on the left-hand side of the grid.
-You will be presented with the list of projects:
-
-image:content-studio-project-list.png[title="Project list",width=2559px]
-
-Select the `Movie DB` project and click on the `New...` button that will take you to the new layer wizard:
-
-image:content-studio-project-wizard.png[title="New layer wizard",width=2559px]
 
-Fill in the form with the following values:
+== Task: Translate and publish
 
-* *Name*: `Norsk Movie DB`
-* *Identifier*: `moviedb-no`
-* *Language*: `norsk (no)`
-* *Access mode*: `Public`
+As long as your preview configuration was working before you started, Content Studio should automatically be able to detect the right locale for each project.
 
-Rest of the fields are arbitrary and can be left as is.
-After saving it and closing the wizard you should see new layer in the list:
+NOTE: You may need to restart/rebuild your Next.js server for the changes to be picked up.
 
-image:content-studio-project-list-2.png[title="Project list",width=2559px]
+. In Content Studio, *Switch editing context* to the `Film DB` project by toggling in the top left corner of Content Studio.
++
+Content Studio should automatically be able to detect the correct Next.js locale for the project. Select an item, and you should get a preview.
++
+. *Translate the site content* by selecting the site content, then click `localize` (rather than edit..). This effectively takes you to the edit form. You may now show off your skills while translating the page to Norwegian.
++
+Once finished, click `Mark as Ready` and proceed to publish the entire site structure.
++
+[TIP]
+====
+*Publish the entire tree* by selecting the tree icon in the publishing wizard.
+image:content-studio-mark-as-ready.png[title="Click tree icon to include all children",width=819px]
 
-Now you can move on to configuring Next.XP to use this new layer.
+====
++
+. **Verify that your front-end is working**
++
+Finally. By adding `/no` i.e. `localhost:4242/no` to the URL of your Next.js server, you should now see the published content from the Norwegian project.
 
-== Task: Set up i18n in Next.XP
 
-In addition to specifying locales in `next.config.js` file, you will need to instruct Next.XP which project to use for every locale.
-This is done in the `ENONIC_PROJECTS` environmental variable:
+== Multi front-end setup
 
-..env
-[source,Properties,options="nowrap"]
-----
-ENONIC_PROJECTS=moviedb/hmdb,no:moviedb-no/hmdb
-----
+In some cases, you may prefer a setup where each language/market is served by a separate Next.js front-end, or you may simply have different sites accessing the same Enonic instance.
 
-Let's break down the syntax:
+To use different front-ends for previewing different sites, follow these steps:
 
-1. First comes the repository name and site path for default locale (`en` in this case): `hmdb/hmdb`.
+. *Update the Next.xp configuration file* for your Enonic installation by adding multiple entries:
 +
-IMPORTANT: This should be present at all times, even when you have no locales configuration in `next.config.js` because this instructs Next.XP where to get the data from.
+NOTE: The sandbox configuration files are located in the sandbox home directory, located in your users home directory at `.enonic/sandboxes/<your-sandbox-name>/home/config`. 
 +
-2. Then comes additional locale identifier and the repository with site path, separated by a colon: `no:moviedb-no/hmdb` telling Next.XP to use `/hmdb` site in `moviedb-no` project for `no` locale
+.com.enonic.app.nextxp.cfg
+[source,properties]
+----
+# uncomment to override default values
+# nextjs.default.secret=yourSecret
+# nextjs.default.url=http://127.0.0.1:4242
+#
+# config 'someName'
+nextjs.someName.secret=yourSecret
+nextjs.someName.url=https://your.next-site.com
+#
+# config 'anotherName'
+nextjs.anotherName.secret=yourOtherSecret
+nextjs.anotherName.url=https://your.other-next-site.com
+# ...
+----
 +
-NOTE: You can have different site paths for different locales: i.e. `/hmdb` for english and `/norges-hmdb` for norwegian
+. *Assign the configuration to your site* by click the pencil icon next to the `Next.XP` app name in the site form, and selecting it from the list of named configurations:
 +
-3. You need to have `<locale>:<project>/<site-path>` definition for all locales configured in `next.enonic.js` except for the default one which suffice `<project>/<site-path>`.
+image:content-studio-configure-nextxp.png[title="Form with fields for server url and nextjs token",width=771px]
 
 == Accessing locale in views
 
+Here are some tips on how to make further use of locales in Next.js.
+
 When using `getStaticProps` or `getServerSideProps`, `locale` is accessible through the `Context`:
 
 [source,TypeScript]
@@ -109,16 +171,4 @@ export interface MetaData {
 }
 ----
 
-== Summary, and whats Next?
-
-🎉 Congratulations 🥳 - You've reached the end of this tutorial - we hope you enjoyed it!
-
-The following topics were not covered, but will be covered in later versions of this tutorial:
-
-* Handling Rich text in form fields
-* and more...
-
-There are other aspects of Enonic and Next.js that will never be covered by this tutorial - to learn more about Enonic check out the following resources:
-
-* https://developer.enonic.com[Enonic Developer portal]
-* https://developer.enonic.com/guides/developer-101/xp7[Enonic Developer 101]
+Now that we have everything working, it's about time you <<deployment#, deploy to live servers>>.

docs/index.adoc

@@ -2,7 +2,7 @@
 :toc: right
 :imagesdir: media/
 
-This is a step-by-step tutorial on building and managing Next.js sites, using Enonic XP as the backend. The combined set of software and tools used in this tutorial is simply called Next.XP. 
+This is a step-by-step tutorial on building and managing Next.js sites, using Enonic as your backend. The combined set of software and tools used in this tutorial is simply called Next.XP. 
 
 NOTE: **Impatient?** Skip to the end of the tutorial and get a live demo by following <<tldr#,these instructions>>.
 
@@ -24,14 +24,15 @@ This tutorial assumes you are somewhat familiar with link:https://nextjs.org/[Ne
 You will complete the following steps:
 
 * Set up the Enonic SDK and sample content
-* Get familiar with the headless API
+* Get familiar with the GraphQL API
 * Learn about the site concept in Enonic
-* Create a Next.js app using a template
+* Create a Next.js app from a template
 * Activate live preview in Enonic
 * Render content based on type
 * Build landing pages using components
 * Create page templates
-* Learn about static rendering in Next.js
+* Static Site Generation SSG
 * Deploy to live servers
+* How to handle multi-language sites
 
 Get started by <<enonic-setup#, setting up the Enonic development environment>>.

docs/menu.json

@@ -45,12 +45,12 @@
             "document": "static"
         },
         {
-            "title": "12 - Live deployment",
-            "document": "deployment"
+            "title": "12 - Multi language",
+            "document": "i18n"
         },
         {
-            "title": "13 - I18n",
-            "document": "i18n"
+            "title": "13 - Live deployment",
+            "document": "deployment"
         },
         {
             "title": "TL;DR",

docs/preview.adoc

@@ -21,39 +21,14 @@ Add the Next.XP app to the site by selecting it in the applications combobox.
 image:content-studio-add-nextxp.png[title="Open app config by pressing pencil icon",width=597px]
 +
 Save the site to make all the features of the app available.
-
-. *Configure the `Next.XP` app*
-+
-By default `Next.XP` uses the following values:
-+
-`url: *http://127.0.0.1:3000*`
 +
-`secret: *mySecretKey*`
+By default Next.XP preview uses the following values:
 +
-You can change default values and add more configurations by adding a config file named `_com.enonic.app.nextxp.cfg_` in `_<xp-home>/config/_` folder:
+* *url*: `http://127.0.0.1:3000`
+* *secret*: `mySecretKey`
 +
-[source,properties]
-----
-# uncomment to override default values
-# nextjs.default.secret=yourSecret
-# nextjs.default.url=http://127.0.0.1:4242
-#
-# config 'someName'
-nextjs.someName.secret=yourSecret
-nextjs.someName.url=https://your.next-site.com
-#
-# config 'anotherName'
-nextjs.anotherName.secret=yourOtherSecret
-nextjs.anotherName.url=https://your.other-next-site.com
-# ...
-----
+This accidentally matches your setup, so everything should work out of the box. We will get back to tuning these values in the <<static#, Static pages>>, and <<deployment#, Deployment>> chapters.
 +
-NOTE: Remember to update properties' values with your own data
-+
-To assign a configuration to a site, click the pencil icon next to the `Next.XP` app name in the site wizard and select from the list of named configurations:
-+
-image:content-studio-configure-nextxp.png[title="Form with fields for server url and nextjs token",width=771px]
-
 . After applying and saving the changes, you should be able to see the live preview in Content Studio.
 +
 image:morgan-freeman-preview.png[title="Next.js-rendered preview in Content Studio",width=1072px]