Massive doc update

gouttebroze · Mar 29, 2020 · 9513140 · 9513140
1 parent c68a7e1
commit 9513140
Show file tree

Hide file tree

Showing 65 changed files with 562 additions and 119 deletions.
diff --git a/docs/Gemfile b/docs/Gemfile
@@ -8,8 +8,9 @@ git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 
 # If you have any plugins, put them here!
 group :jekyll_plugins do
- gem 'just-the-docs' # XXX Our Jekyll theme - See https://pmarsceill.github.io/just-the-docs/
- gem "github-pages" # XXX Necessary to reproduce the behaviour of GitHub Pages - When this is loaded, "jekyll" must not be bundled because it's included within
+  gem 'just-the-docs' # XXX Our Jekyll theme - See https://pmarsceill.github.io/just-the-docs/
+  gem "github-pages" # XXX Necessary to reproduce the behaviour of GitHub Pages - When this is loaded, "jekyll" must not be bundled because it's included within
+  gem 'jemoji' # XXX GitHub-flavored Emoji plugin for Jekyll - See https://github.com/jekyll/jemoji
 end
 
 # ------- WINDOWS SUPPORT ---------

diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
@@ -251,6 +251,7 @@ PLATFORMS
 
 DEPENDENCIES
   github-pages
+  jemoji
   just-the-docs
   tzinfo (~> 1.2)
   tzinfo-data

diff --git a/docs/_config-development.yml b/docs/_config-development.yml
@@ -33,6 +33,7 @@ footer_content: "Copyright &copy; 2020 Unly. <a href=\"https://github.com/UnlyEd
 
 plugins:
   - jekyll-sitemap
+  - jemoji
 
 # Exclude from processing.
 # The following items will not be processed, by default. Create a custom list

diff --git a/docs/_config.yml b/docs/_config.yml
@@ -34,6 +34,7 @@ footer_content: "Copyright &copy; 2020 Unly. <a href=\"https://github.com/UnlyEd
 
 plugins:
   - jekyll-sitemap
+  - jemoji
 
 # Exclude from processing.
 # The following items will not be processed, by default. Create a custom list

diff --git a/docs/_includes/installation-guide-full.md b/docs/_includes/installation-guide-full.md
@@ -0,0 +1,10 @@
+1. `git clone git@github.com:UnlyEd/next-right-now.git` - Clones the boilerplate
+1. `git checkout {{ include.variant }}` - Select the variant
+1. Duplicate the `.env.build.example` and rename it `.env.build` _(this file is only used on your local computer)_
+1. Create an account for all required 3rd party vendors above, and fill-in missing environment variables in your `.env.build` file
+1. `nvm use` - Selects the right node.js version based on the `.nvmrc` file
+1. `yarn` - Installs all deps from `package.json`
+1. `yarn start` - Starts the app on [http://localhost:8888/](http://localhost:8888/)
+1. That's it! The project now works on your local computer, and should be identical to the online demo
+
+{% include installation-guide-tips.md %}
diff --git a/docs/_includes/installation-guide-simple.md b/docs/_includes/installation-guide-simple.md
@@ -0,0 +1,8 @@
+1. `git clone git@github.com:UnlyEd/next-right-now.git` - Clones the boilerplate
+1. `git checkout v1-ssr` - Select the variant
+1. Duplicate the `.env.build.example` and rename it `.env.build` _(this file is only used on your local computer)_
+1. `nvm use` - Selects the right node.js version based on the `.nvmrc` file
+1. `yarn add -D now@16.7.3`, now@17+ requires to be authenticated to Zeit in order to launch the project **locally**, so you must use now@16 instead, to avoid additional setup
+1. `yarn` - Installs all deps from `package.json`
+1. `yarn start` - Starts the app on [http://localhost:8888/](http://localhost:8888/)
+1. That's it! The project now works on your local computer, and should be identical to the online demo
diff --git a/docs/_includes/installation-guide-tips.md b/docs/_includes/installation-guide-tips.md
@@ -0,0 +1,4 @@
+> **Tip**: You can start the project in **debug mode** (built-in for WebStorm only) [by running the WebStorm "Debug" configuration in debug mode](https://youtu.be/3vbkiRAT4e8)
+>
+> **Tip**: Configure your IDE not to index `.next` and `.now` folders as they will eat a lot of your memory because they're changed very frequently
+> On WebStorm, right click on the folders and select `Mark directory as > Excluded`.
diff --git a/docs/_includes/vendors/vendor-row-amplitude.md b/docs/_includes/vendors/vendor-row-amplitude.md
@@ -0,0 +1 @@
+| [Amplitude](https://amplitude.com/pricing?ref=unly-nrn) | :white_check_mark: | :white_check_mark: [1<sup>st</sup> year free](https://amplitude.com/startups?ref=unly-nrn) _(for startups and non-profit)_ | Don't provide discounts |
diff --git a/docs/_includes/vendors/vendor-row-graphcms.md b/docs/_includes/vendors/vendor-row-graphcms.md
@@ -0,0 +1 @@
+| [GraphCMS](https://graphcms.com/pricing?ref=unly-nrn) | :white_check_mark: | :white_check_mark: **Growth** plan 2 weeks | Provide discounts for non-profit organisations |
diff --git a/docs/_includes/vendors/vendor-row-locize.md b/docs/_includes/vendors/vendor-row-locize.md
@@ -0,0 +1 @@
+| [Locize](https://locize.com/pricing.html?ref=unly-nrn) | :x: | :white_check_mark: 2 weeks | May provide discount for non-profit organisations, contact them at [support@locize.com](support@locize.com ) |
diff --git a/docs/_includes/vendors/vendor-row-sentry.md b/docs/_includes/vendors/vendor-row-sentry.md
@@ -0,0 +1 @@
+| [Sentry](https://sentry.io/pricing?ref=unly-nrn) | :white_check_mark: | :white_check_mark: Any plan 2 weeks | Don't provide discounts |
diff --git a/docs/_includes/vendors/vendor-row-zeit.md b/docs/_includes/vendors/vendor-row-zeit.md
@@ -0,0 +1 @@
+| [Zeit](https://zeit.co/pricing?ref=unly-nrn) | :white_check_mark: | :x: (but free plan is better than trial) | Friendly pricing for [non-commercial usage](https://spectrum.chat/zeit/general/deploying-on-ziet-now~700e3286-551f-42d1-a289-df4cb52e23ea?m=MTU4MzgzMjg1MzAyOA==) |
diff --git a/docs/_includes/vendors/vendor-table.md b/docs/_includes/vendors/vendor-table.md
@@ -0,0 +1,7 @@
+{% if variant %}
+The following vendors are **built-in** with the variant `{{variant}}`.
+{% endif %}
+
+| Vendor | Has free plan | Has free trial | Potential discounts |
+|:-------------|:------------------|:------|:----|
+{% if include.zeit == true%}{% include vendors/vendor-row-zeit.md %}{% endif %}{% if include.graphcms == true%}{% include vendors/vendor-row-graphcms.md %}{% endif %}{% if include.locize == true%}{% include vendors/vendor-row-locize.md %}{% endif %}{% if include.amplitude == true%}{% include vendors/vendor-row-amplitude.md %}{% endif %}{% if include.sentry == true%}{% include vendors/vendor-row-sentry.md %}{% endif %}
diff --git a/docs/_includes/zeit-online-deployment-full.md b/docs/_includes/zeit-online-deployment-full.md
@@ -0,0 +1,15 @@
+1. (Optional) Run `now login` if you aren't authenticated to Zeit from your local machine. Typically, if it's the first time you use Zeit you'll need to do it.
+1. You need to change the associated Zeit `scope` (it currently uses the boilerplate's, because it's required for our CI/CD Github Actions)
+    - Remove the whole line `"scope": "team_qnVfSEVc2WwmOE1OYhZr4VST",` in all `now.*.json` files
+    - `yarn start` - Will create a `.now` folder containing project metadata.
+    - Add a `scope` line in all `now.*.json` files using the `projectId` in `.now/project.json`
+1. Create all [Zeit secrets](https://zeit.co/docs/v2/environment-variables-and-secrets) by running `now secrets add $secretName $secretValue`, for instance `now secrets add nrn-sentry-dsn https://14fa1cae05079675b18cd05403ae5c48@sentry.io/1234567`.
+    The full list of expected Zeit secrets to define is in any `now.*.json` file.
+1. `yarn deploy` - Will deploy the project online, and automatically create the Zeit project first, if it doesn't exist already.
+    This command will fail if any secret is missing.
+1. Go to [Zeit](https://zeit.co/) to see the project being deployed, go through logs, etc.
+
+At this point, manual deploy through command line should work.
+But CI/CD requires [additional configuration](../guides/ci-cd/setup-github-actions) to automatically deploy when a change is applied on the remote repository.
+
+{% include zeit-online-deployment-tips.md  %}
diff --git a/docs/_includes/zeit-online-deployment-tips.md b/docs/_includes/zeit-online-deployment-tips.md
@@ -0,0 +1,5 @@
+> Zeit doesn't provide the `projectId` from the Zeit platform itself, even if the project exists already. Running `yarn start` locally is the only way to know what is your `projectId`, AFAIK.
+>
+> If you create a secret with a wrong value, you will have to delete it and create it again (there is no update feature). See `now secrets --help`
+>
+> **Tip**: If you ever need to store files as secrets (such as ssh keys), see [this solution](https://github.com/zeit/now/issues/749#issuecomment-533873759)
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -87,6 +87,7 @@ <h2 class="text-delta">Table of contents</h2>
           {% endif %}
 
           {% unless page.comments == false %}
+            <hr />
             <div id="disqus_thread"></div>
             <script>
               /**

diff --git a/docs/_sass/overrides.scss b/docs/_sass/overrides.scss
@@ -9,3 +9,21 @@ blockquote {
   display: flex;
   justify-content: space-between;
 }
+
+// Overrides https://github.com/jekyll/jemoji for better positioning alongside text
+img.emoji {
+  top: 5px;
+  position: relative;
+}
+
+h1 {
+  code {
+    font-size: 36px;
+  }
+}
+
+h2 {
+  code {
+    font-size: 24px;
+  }
+}
diff --git a/docs/concepts/analytics.md b/docs/concepts/analytics.md
@@ -26,3 +26,14 @@ We only use react-amplitude to manipulate events.
 
 - [Tutorial](https://help.amplitude.com/hc/en-us/articles/360003032451-Instrumentation-Explorer-Debugger)
 - [Chrome plugin](https://chrome.google.com/webstore/detail/amplitude-instrumentation/acehfjhnmhbmgkedjmjlobpgdicnhkbp)
+
+---
+
+<div class="pagination-section">
+    <span class="fs-4" markdown="1">
+    [< I18n](./i18n){: .btn }
+    </span>
+    <span class="fs-4" markdown="1">
+    [Monitoring >](./monitoring){: .btn .btn-purple }
+    </span>
+</div>
diff --git a/docs/concepts/ci-cd.md b/docs/concepts/ci-cd.md
@@ -29,3 +29,14 @@ Here is how the multiple steps are ordered:
 ## In-depth project's dependencies
 
 See [README_DEPENDENCIES](./README_DEPENDENCIES.md)
+
+---
+
+<div class="pagination-section">
+    <span class="fs-4" markdown="1">
+    [< Monitoring](./monitoring){: .btn }
+    </span>
+    <span class="fs-4" markdown="1">
+    [Testing >](./testing){: .btn .btn-purple }
+    </span>
+</div>
diff --git a/docs/concepts/env-and-stages.md b/docs/concepts/env-and-stages.md
@@ -5,52 +5,76 @@ parent: Concepts
 nav_order: 10
 ---
 
-# Understanding `Environments` and `Stages`
+# Understanding **Environments** and **Stages**
 
-> The application relies on environment variables to function correctly.
-> Those variables are provided differently depending on the environment.
+<div class="code-example" markdown="1">
+- NRN relies on environment variables to function correctly.
+- Those variables are provided differently depending on the environment.
+
+The following examples use the [`v1-ssr`](../getting-started/pick-variant.html#v1-ssr---default-variant) variant, which uses a multi single-tenants design.
+</div>
+
+---
 
 When working on the `development` environment (localhost), the variables from [`.env.build`](.env.build) are used by [the webpack configuration](./next.config.js),
-also, the [`now.json`](./now.json) configuration file is used _(it's a symlink to [`now.customer1.staging.json`](now.customer1.staging.json))_, but the variable defined in `.env.build` take precedence.
+also, the [`now.json`](./now.json) configuration file is used _(it's always a symlink to another staging `now.*.json` file, i.e: `now.customer1.staging.json`)_, but the variable defined in `.env.build` take precedence.
 
 When deploying an instance to the Zeit's platform, the variables used are the one that belong to that instance, such as:
-- `yarn deploy:customer1`: This script will deploy an instance using the [`now.customer1.production.json`](now.customer1.staging.json) file.
-- `yarn deploy:customer1:production`: This script will deploy an instance using the [`now.customer1.production.json`](now.customer1.production.json) file.
+- `yarn deploy:customer1`: This script will deploy an instance using the `now.customer1.staging.json` file.
+- `yarn deploy:customer1:production`: This script will deploy an instance using the `now.customer1.production.json` file.
 
-> In those files, it's the `build.env` part that is used at build time (build is done on Zeit), which basically replaces all references of every environment variable by the actual value (string replace).
+> In those files, it's the `build.env` part that is used at build time (build is done on Zeit), which basically replaces all references of every environment variable by the actual value (string replace at build time).
 
-## What is an `environment`?
+---
+
+## What is an **environment**?
 
 > An environment is "where" the application is running.
 > It can be either "development" (localhost) or "production" (on Zeit's servers).
 >
 > **The `environment` is defined by the `NODE_ENV` environment variable.**
 >
-> **N.B**: It is not possible to any other value, [as enforced by Next](https://github.com/zeit/next.js/blob/master/errors/env-key-not-allowed.md)
+> **N.B**: It is **not** possible to use any other value, [as enforced by Next](https://github.com/zeit/next.js/blob/master/errors/env-key-not-allowed.md)
 
 When working on your local computer, you automatically use `NODE_ENV=developement`.
 
-The environment affects how the application **is bundled**, it is used at **build time**. (webpack, hot-reloading, etc.)
+The environment affects how the application **is bundled**, it is defined at **build time**. (webpack, hot-reloading, etc.)
 
-> i.e: In `development` environment, you have access to PropTypes warnings, but you won't in `production`.
+> i.e: When building the app using the `development` environment, you have access to PropTypes warnings, but you won't when using `production`.
 
-## What is a `stage`?
+---
+
+## What is a **stage**?
 
 > A stage is "how" the application is running.
-> It can be either "development" (localhost), "staging" or "production" (on Zeit's servers) - _You can add more if you need_
+> It can be either "development" (localhost), "staging" or "production" (on Zeit's servers) - _You can even add more if you need_
 >
 > **The `stage` is defined by the `APP_STAGE` environment variable.**
 >
 > **N.B**: You can use any stage name you like, there is no restriction.
 
-- When working on your local computer, you automatically use `APP_STAGE=developement`.
-- When creating a Zeit preview deployment (i.e: when pushing a commit/branch (CD), when using `yarn deploy`, etc.), you automatically use `APP_STAGE=staging`.
-- When creating a Zeit production deployment (i.e: when using `yarn deploy:customer1:production`, when merging a PR to `master`, etc.), you automatically use `APP_STAGE=production`.
+- When working on your local computer, NRN automatically uses `APP_STAGE=developement` _(as defined in `.env.build`)_.
+- When creating a Zeit preview deployment (i.e: when pushing a commit/branch (CD), or when using `yarn deploy`, etc.), NRN automatically uses `APP_STAGE=staging` _(as defined in `now.customer1.staging.json`)_.
+- When creating a Zeit production deployment (i.e: when using `yarn deploy:customer1:production`, or when merging a PR to `master`, etc.), NRN automatically uses `APP_STAGE=production` _(as defined in `now.customer1.production.json`)_.
 
 The stage changes the behaviour of the application, because we sometimes need the application to behave differently depending on the stage.
 
+> The stage **isn't magically chosen by NRN**, it is **automated** but it's because of either your `.env.build`, or because **Github Actions** have been configured this way.
+> (any push on **master** is considered as **production** stage, while any push on **any other branch** is considered as **staging** stage)
+
 > i.e: In `production` stage, the Locize configuration uses the `production` version.
 > When using another stage, it uses the `latest` version.
 
 > i.e: We don't want to enable the same level of debugging in production environment.
 > For instance, Locize is configured to be in `debug` mode only in non-production stages.
+
+---
+
+<div class="pagination-section">
+    <span class="fs-4" markdown="1">
+    [< Variants](./variants){: .btn }
+    </span>
+    <span class="fs-4" markdown="1">
+    [Tenancy >](./tenancy){: .btn .btn-purple }
+    </span>
+</div>
diff --git a/docs/concepts/graphql.md b/docs/concepts/graphql.md
@@ -25,3 +25,14 @@ There are several ways of fetching data from a GraphQL API:
 - [**`react-hooks`**](https://www.apollographql.com/docs/react/api/react-hooks): Hooks can only be used with Functional components (not classes), the GraphQL query is described in the function's body.
 
 We used the hooks approach because it's just cleaner and simpler to understand.
+
+---
+
+<div class="pagination-section">
+    <span class="fs-4" markdown="1">
+    [< Tenancy](./tenancy){: .btn }
+    </span>
+    <span class="fs-4" markdown="1">
+    [I18n >](./i18n){: .btn .btn-purple }
+    </span>
+</div>
diff --git a/docs/concepts/i18n.md b/docs/concepts/i18n.md
@@ -59,3 +59,17 @@ Locize provides a few [additional services](https://locize.com/services.html?ref
 - One interesting thing is the ability to share part of the project to be translated by a third party using [`Crowdbased`](https://locize.com/services.html?ref=unly-nrn), without sharing the whole project.
 - There are also several paid [Translation services](https://locize.com/services.html?ref=unly-nrn), where you can pay people to translate your content.
 - It is also possible to enable [Audit](https://locize.com/services.html?ref=unly-nrn), which allows to audit every change to our translations, and keep changes up to 10 years. (_expensive_)
+
+---
+
+<div class="pagination-section">
+    <span class="fs-4" markdown="1">
+    [< GraphQL](./graphql){: .btn }
+    </span>
+    <span class="fs-4" markdown="1">
+    [Analytics >](./analytics){: .btn .btn-blue }
+    </span>
+    <span class="fs-4" markdown="1">
+    [Analytics >](./analytics){: .btn .btn-purple }
+    </span>
+</div>
diff --git a/docs/concepts/index.md b/docs/concepts/index.md
@@ -5,3 +5,25 @@ nav_order: 30
 has_children: true
 ---
 
+# Concepts
+
+<div class="code-example" markdown="1">
+This section explains in details the different concepts around Next Right Now.
+
+We recommend to follow the given order to go through them all.
+
+You don't have to read/understand all of them, pick those that seem related to your needs.
+
+> We strongly recommend reading both **Variants** and **Environments and Stages**, because they're both pillars of NRN and will be necessary anyway.
+</div>
+
+---
+
+<div class="pagination-section">
+    <span class="fs-4" markdown="1">
+    [< Getting started: Quick start](../getting-started/quick-start){: .btn }
+    </span>
+    <span class="fs-4" markdown="1">
+    [Variants >](./variants){: .btn .btn-purple }
+    </span>
+</div>
diff --git a/docs/concepts/monitoring.md b/docs/concepts/monitoring.md
@@ -6,3 +6,14 @@ nav_order: 50
 ---
 
 TODO wasn't documented
+
+---
+
+<div class="pagination-section">
+    <span class="fs-4" markdown="1">
+    [< Analytics](./analytics){: .btn }
+    </span>
+    <span class="fs-4" markdown="1">
+    [CI/CD >](./ci-cd){: .btn .btn-purple }
+    </span>
+</div>
diff --git a/docs/concepts/tenancy.md b/docs/concepts/tenancy.md
@@ -6,3 +6,14 @@ nav_order: 20
 ---
 
 TODO explain multi-tenants and multi single-tenants designs
+
+---
+
+<div class="pagination-section">
+    <span class="fs-4" markdown="1">
+    [< Environments and Stages](./env-and-stages){: .btn }
+    </span>
+    <span class="fs-4" markdown="1">
+    [GraphQL >](./graphql){: .btn .btn-purple }
+    </span>
+</div>
diff --git a/docs/concepts/testing.md b/docs/concepts/testing.md
@@ -25,3 +25,14 @@ You can run interactive E2E tests using Cypress with `yarn e2e:open` script.
 You can also run them non-interactively using `yarn e2e:run` script.
 
 > You may need to run `yarn e2e:install` script first
+
+---
+
+<div class="pagination-section">
+    <span class="fs-4" markdown="1">
+    [< CI/CD](./ci-cd){: .btn }
+    </span>
+    <span class="fs-4" markdown="1">
+    [Getting started: Pick your variant >](../getting-started/pick-variant){: .btn .btn-purple }
+    </span>
+</div>
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		\| [Amplitude](https://amplitude.com/pricing?ref=unly-nrn) \| :white_check_mark: \| :white_check_mark: [1<sup>st</sup> year free](https://amplitude.com/startups?ref=unly-nrn) _(for startups and non-profit)_ \| Don't provide discounts \|
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		\| [GraphCMS](https://graphcms.com/pricing?ref=unly-nrn) \| :white_check_mark: \| :white_check_mark: Growth plan 2 weeks \| Provide discounts for non-profit organisations \|
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		\| [Locize](https://locize.com/pricing.html?ref=unly-nrn) \| :x: \| :white_check_mark: 2 weeks \| May provide discount for non-profit organisations, contact them at [support@locize.com](support@locize.com ) \|
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		\| [Sentry](https://sentry.io/pricing?ref=unly-nrn) \| :white_check_mark: \| :white_check_mark: Any plan 2 weeks \| Don't provide discounts \|
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		\| [Zeit](https://zeit.co/pricing?ref=unly-nrn) \| :white_check_mark: \| :x: (but free plan is better than trial) \| Friendly pricing for [non-commercial usage](https://spectrum.chat/zeit/general/deploying-on-ziet-now~700e3286-551f-42d1-a289-df4cb52e23ea?m=MTU4MzgzMjg1MzAyOA==) \|