Docs Github Pages - Navigation menu (#21)

* Don't use incremental mode, doesn't properly apply changes even when restarting local server * Make a common and a specific section in both config files for ease of maintenance * Configure navigation menu * Fix useless TOC * Improve CHANGELOG.md and FAQ * Add script to build dependencies TOC * Add CONTRIBUTING
UnlyEd · Mar 27, 2020 · d5afecb · d5afecb
1 parent a55e8db
commit d5afecb
Show file tree

Hide file tree

Showing 66 changed files with 486 additions and 58 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1 @@
-Changelog
-===
-
-
-- v1.0.0 - 2020-02-28
-    - Initial release, production-ready (doc to be improved)
+[GO TO CHANGELOG](https://unlyed.github.io/next-right-now/CHANGELOG)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1 @@
+[GO TO CONTRIBUTING](https://unlyed.github.io/next-right-now/CONTRIBUTING)
diff --git a/README.md b/README.md
@@ -95,6 +95,7 @@ Thus, **you can still use this boilerplate even if you don't like all our choice
   * [Showcases - Live demo](#showcases---live-demo)
 - [Documentation](#documentation)
 - [FAQ](#faq)
+- [Contributing](#contributing)
 - [License](#license)
 - [Vulnerability disclosure](#vulnerability-disclosure)
 - [Contributors and maintainers](#contributors-and-maintainers)
@@ -166,9 +167,15 @@ You can see 2 almost identical demo at:
 
 ---
 
+# Contributing
+
+[GO TO CONTRIBUTING](https://unlyed.github.io/next-right-now/CONTRIBUTING)
+
+---
+
 # License
 
-MIT
+[MIT](LICENSE)
 
 ---
 

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1,35 @@
+---
+layout: default
+title: CONTRIBUTING
+nav_order: 90
+---
+
+# Contributing
+
+## Contributing about documentation
+
+Our documentation lives in the `docs/` folder. It is generated by Github Pages.
+
+Only the master branch generates the online documentation. It is available at [https://unlyed.github.io/next-right-now/](https://unlyed.github.io/next-right-now/)
+
+It uses [Jekyll](https://jekyllrb.com/) behind the wheel, and [`just-the-docs`](https://pmarsceill.github.io/just-the-docs/) theme for Jekyll.
+
+### Installing Jekyll locally
+
+In order to contribute to the docs, you may need to install Jekyll locally (especially for non-trivial changes).
+Jekyll needs Ruby binary.
+
+1. Install and configure Jekyll on your computer, follow [https://jekyllrb.com/docs/](https://jekyllrb.com/docs/)
+1. Once Jekyll is installed, you can install all Ruby gems using `yarn doc:gem:install`
+1. Once gems are installed, you can run Jekyll by using `yarn doc:start`
+
+### Configuring Jekyll properly
+
+Jekyll configuration uses 2 different files.
+- [`docs/_config.yml`](docs/_config.yml) used by Github Pages
+- [`docs/_config-development.yml`](docs/_config-development.yml) used by your local installation
+
+There are a few, but important differences between both. The custom configuration must be written at the top of each config file.
+The shared configuration must be written below.
+
+> **N.B**: If you add custom/shared configuration, don't forget update both config files, as needed.
diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -1,12 +1,15 @@
 ---
-layout: page
+layout: default
 title: FAQ
 permalink: /FAQ/
+nav_order: 70
 ---
 
 # FAQ
 
-> Q: I wanted to understand how the i18next integration works. How is the `i18nextInstance` passed to react? It seems to be passed to the `Layout` component, but the `Layout` component never uses it. So how does this work?
+<div class="code-example" markdown="1">
+  **Question**: _I wanted to understand how the i18next integration works. How is the `i18nextInstance` passed to react? It seems to be passed to the `Layout` component, but the `Layout` component never uses it. So how does this work?_
+</div>
 
 - The i18nextInstance isn't necessary to perform translations actually, it's forwarded as a utility.
 - Manipulating the i18nextInstance is not often necessary, using import { Trans, useTranslation } from 'react-i18next'; is what you'll need most of the time when translating content.

diff --git a/docs/VARIANTS.md b/docs/VARIANTS.md
diff --git a/docs/_config-development.yml b/docs/_config-development.yml
@@ -1,5 +1,11 @@
 # XXX This file is only used when working on your local machine, in development
 
+# XXX --------- Specific to GHP config ------------
+theme: 'just-the-docs' # XXX Our Jekyll theme - See https://pmarsceill.github.io/just-the-docs/
+
+
+# XXX --------- Common to all config --------------
+
 # Welcome to Jekyll!
 #
 # This config file is meant for settings that affect your whole blog, values
@@ -23,7 +29,12 @@ description: >- # this means to ignore newlines until "baseurl:"
 #baseurl: "" # the subpath of your site, e.g. /blog
 #url: "" # the base hostname & protocol for your site, e.g. http://example.com XXX Auto-resolved by GitHub
 
-theme: 'just-the-docs' # XXX Our Jekyll theme - See https://pmarsceill.github.io/just-the-docs/
+# Aux links for the upper right navigation
+aux_links:
+  "Github": "https://github.com/UnlyEd/next-right-now"
+
+footer_content: "Copyright &copy; 2020 Unly. <a href=\"https://github.com/UnlyEd/next-right-now/blob/master/LICENSE\">MIT license.</a>"
+#color_scheme: "dark"
 
 # 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
@@ -1,5 +1,12 @@
 # XXX This file is only used by GitHub Pages, when deploying online
 
+# XXX --------- Specific to GHP config ------------
+remote_theme: pmarsceill/just-the-docs # XXX Our Jekyll theme - See https://pmarsceill.github.io/just-the-docs/
+ga_tracking: UA-89785688-8
+
+
+# XXX --------- Common to all config --------------
+
 # Welcome to Jekyll!
 #
 # This config file is meant for settings that affect your whole blog, values
@@ -23,7 +30,12 @@ description: >- # this means to ignore newlines until "baseurl:"
 #baseurl: "" # the subpath of your site, e.g. /blog
 #url: "" # the base hostname & protocol for your site, e.g. http://example.com XXX Auto-resolved by GitHub
 
-remote_theme: pmarsceill/just-the-docs # XXX Our Jekyll theme - See https://pmarsceill.github.io/just-the-docs/
+# Aux links for the upper right navigation
+aux_links:
+  "Github": "https://github.com/UnlyEd/next-right-now"
+
+footer_content: "Copyright &copy; 2020 Unly. <a href=\"https://github.com/UnlyEd/next-right-now/blob/master/LICENSE\">MIT license.</a>"
+#color_scheme: "dark"
 
 # Exclude from processing.
 # The following items will not be processed, by default. Create a custom list

diff --git a/docs/_posts/2020-03-26-welcome-to-jekyll.markdown b/docs/_posts/2020-03-26-welcome-to-jekyll.markdown
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1,12 @@
+---
+layout: default
+title: CHANGELOG
+nav_order: 80
+---
+
+Changelog
+===
+
+
+- v1.0.0 - 2020-02-28
+    - Initial release, production-ready (doc to be improved)
diff --git a/docs/concepts/MONITORING.md b/docs/concepts/MONITORING.md
diff --git a/docs/concepts/TENANCY.md b/docs/concepts/TENANCY.md
diff --git a/docs/concepts/ANALYTICS.md → docs/concepts/analytics.md b/docs/concepts/ANALYTICS.md → docs/concepts/analytics.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: Analytics
+parent: Concepts
+nav_order: 45
+---
+
 # [Amplitude](https://amplitude.com/) (Analytics)
 
 > Amplitude is used to collect usage metrics (analytics) of the application.

diff --git a/docs/concepts/CI_CD.md → docs/concepts/ci-cd.md b/docs/concepts/CI_CD.md → docs/concepts/ci-cd.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: CI/CD
+parent: Concepts
+nav_order: 60
+---
+
 # Continuous Integration & Continuous Deployment (CI/CD)
 
 ## Overview

diff --git a/docs/concepts/ENV_AND_STAGES.md → docs/concepts/env-and-stages.md b/docs/concepts/ENV_AND_STAGES.md → docs/concepts/env-and-stages.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: Environments and Stages
+parent: Concepts
+nav_order: 10
+---
+
 # Understanding `Environments` and `Stages`
 
 > The application relies on environment variables to function correctly.

diff --git a/docs/concepts/GRAPHQL.md → docs/concepts/graphql.md b/docs/concepts/GRAPHQL.md → docs/concepts/graphql.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: GraphQL
+parent: Concepts
+nav_order: 30
+---
+
 # [GraphCMS](https://graphcms.com/?ref=unly-nrn)
 
 ## Discount

diff --git a/docs/concepts/I18N.md → docs/concepts/i18n.md b/docs/concepts/I18N.md → docs/concepts/i18n.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: I18n
+parent: Concepts
+nav_order: 40
+---
+
 # I18n (Internationalization)
 
 The content displayed on NRN is translated using different ways, depending on where the translations are stored:

diff --git a/docs/concepts/index.md b/docs/concepts/index.md
@@ -0,0 +1,7 @@
+---
+layout: default
+title: Concepts
+nav_order: 30
+has_children: true
+---
+
diff --git a/docs/concepts/monitoring.md b/docs/concepts/monitoring.md
@@ -0,0 +1,8 @@
+---
+layout: default
+title: Monitoring
+parent: Concepts
+nav_order: 50
+---
+
+TODO wasn't documented
diff --git a/docs/concepts/tenancy.md b/docs/concepts/tenancy.md
@@ -0,0 +1,8 @@
+---
+layout: default
+title: Tenancy (MT & MST)
+parent: Concepts
+nav_order: 20
+---
+
+TODO explain multi-tenants and multi single-tenants designs
diff --git a/docs/concepts/TESTING.md → docs/concepts/testing.md b/docs/concepts/TESTING.md → docs/concepts/testing.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: Testing
+parent: Concepts
+nav_order: 70
+---
+
 # Testing
 
 ## CI tests Workflow

diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
@@ -0,0 +1,45 @@
+---
+layout: default
+title: Getting started
+nav_order: 20
+has_children: true
+---
+
+# Introduction
+
+> Below are explanations about how NRN works and why we did things the way we did
+>
+> **Tip**: If you're interested about how to use this project for your own need, see our ["How to use" Guide](./README_HOW_TO_USE.md) instead!
+
+## Introduction videos
+
+### Part 1 - Overview of Next Right Now (15 minutes)
+[![Part 1 - Overview of Next Right Now](https://img.youtube.com/vi/kltkFwnFL-k/maxresdefault.jpg)](http://youtu.be/kltkFwnFL-k?hd=1)
+
+> Let's talk about why we built RNR in the first place, how it's meant to be used, whom it is for.
+>
+> This video features Zeit deployments, i18n, GraphCMS, Locize in-context editor, Sentry monitoring, Amplitude analytics, CI/CD Github Actions
+
+### Part 2 - Developer Experience with Next Right Now (15 minutes)
+[![Part 2 - Developer Experience with Next Right Now](https://img.youtube.com/vi/fGlgIEeUqFg/maxresdefault.jpg)](http://youtu.be/fGlgIEeUqFg?hd=1)
+
+> Let's talk about the developer experience (DX) provided by NRN and how it helps being more efficient.
+>
+> This video features GraphQL auto-completion and local schema update, deployment workflow, CI/CD Github Actions explanations, interactive E2E testing, GraphsCMS field creation
+
+### Guides
+- [How to run NRN in debug mode using WebStorm debug configuration](http://youtu.be/3vbkiRAT4e8?hd=1) (2 minutes)
+
+---
+
+## Showcases - Live demo
+
+You can see 2 almost identical demo at:
+- [https://nrn-customer1.now.sh](https://nrn-customer1.now.sh)
+- [https://nrn-customer2.now.sh](https://nrn-customer2.now.sh)
+
+**Both share the same source code and configuration**, but the database content is different (hosted on GraphCMS).
+
+> **Tip**: You can get metadata at [/api/status](https://nrn-customer1.now.sh/api/status)
+>
+> **Tip**: All `/api/*` are serverless functions, running under AWS Lambda
diff --git a/docs/LIVE_DEMO.md → docs/getting-started/live-demo.md b/docs/LIVE_DEMO.md → docs/getting-started/live-demo.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: Online demo
+parent: Getting started
+nav_order: 20
+---
+
 ## Showcases - Live demo
 
 You can see 2 almost identical demo at:

diff --git a/docs/overview/INTRODUCTION.md → docs/getting-started/overview.md b/docs/overview/INTRODUCTION.md → docs/getting-started/overview.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: Overview
+parent: Getting started
+nav_order: 10
+---
+
 # Introduction
 
 > Below are explanations about how NRN works and why we did things the way we did

diff --git a/docs/QUICKSTART.md → docs/getting-started/quick-start.md b/docs/QUICKSTART.md → docs/getting-started/quick-start.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: Quick start
+parent: Getting started
+nav_order: 30
+---
+
 ## Super quick local installation (for local-only testing purpose, without Zeit account)
 
 > This assumes you've **cloned** the project on your own computer.

diff --git a/docs/getting-started/variants.md b/docs/getting-started/variants.md
@@ -0,0 +1,8 @@
+---
+layout: default
+title: Variants
+parent: Getting started
+nav_order: 40
+---
+
+TODO Explain variants https://github.com/UnlyEd/next-right-now/issues/18
diff --git a/docs/how-to/analytics-amplitude/index.md b/docs/how-to/analytics-amplitude/index.md
@@ -0,0 +1,7 @@
+---
+layout: default
+title: "[Analytics] Amplitude"
+parent: How to
+nav_order: 40
+has_children: true
+---
diff --git a/docs/how-to/analytics/REMOVE_AMPLITUDE.md → ...o/analytics-amplitude/remove-amplitude.md b/docs/how-to/analytics/REMOVE_AMPLITUDE.md → ...o/analytics-amplitude/remove-amplitude.md
@@ -1,3 +1,11 @@
+---
+layout: default
+title: Remove Amplitude
+parent: "[Analytics] Amplitude"
+grand_parent: How to
+nav_order: 30
+---
+
 ## How to remove Amplitude
 
 > You can use other alternative libraries for analytics.

diff --git a/docs/how-to/analytics-amplitude/setup-amplitude.md b/docs/how-to/analytics-amplitude/setup-amplitude.md
@@ -0,0 +1,10 @@
+---
+layout: default
+title: Setup Amplitude
+parent: "[Analytics] Amplitude"
+grand_parent: How to
+nav_order: 10
+---
+
+TODO wasn't documented
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		[GO TO CONTRIBUTING](https://unlyed.github.io/next-right-now/CONTRIBUTING)