📝(website) create a documentation & "marketing" website for Richie

Richie was documented through markdown files in a docs/ folder in the
repository, and publicized through the README.md. As we're starting to
grow the community, this is not enough.

We're starting a documentation website with a decicated "marketing"
landing page to introduce new users/contributors to the project. We
used Docusaurus to automatically build out the documentation using
our own markdown files for content.

.dockerignore

@@ -17,6 +17,7 @@ env.d
 # Docs
 docs
 *.md
+*.log
 
 # Development/test cache & configurations
 .cache

.gitignore

@@ -84,3 +84,11 @@ yarn-error.log
 src/frontend/i18n/js
 *.pot
 
+# Documentation related files to ignore
+lib/core/metadata.js
+lib/core/MetadataBlog.js
+website/translated_docs
+website/build/
+website/yarn.lock
+website/node_modules
+website/i18n/*

CHANGELOG.md

@@ -8,6 +8,11 @@ Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- Create a documentation & marketing website for the project. It lives under
+  the `docs` folder and is deployed to Github Pages.
+
 ## [1.12.0] - 2019-10-23
 
 ### Added

CONTRIBUTING.md

@@ -0,0 +1,5 @@
+# Contributing to Richie
+
+Want to contribute to Richie? We got you covered.
+
+Take a look at our [contributing guide](https://richie.education/docs/contributing-guide) to get started.

README.md

@@ -26,137 +26,22 @@ Among the features that `Richie` offers out of the box:
   inter-relations),
 - Extensible with any third-party `DjangoCMS` plugin or any third-party `Django` application.
 
-## Demo
+## Quick preview
 
-You can test Richie on our [demo site](https://richie.education).
+If you're just looking for a quick preview of `Richie`, you can take look and have a tour of `Richie` on our dedicated [demo site](https://demo.richie.education).
 
-login/password: admin/admin
-
-The database, is regularly flushed.
-
-## Architecture
-
-`Richie` is a **container-native application** but can also be installed
-[on your machine](./docs/native_installation.md).
-
-For development, the project is defined using a [docker-compose file](../docker-compose.yml) and
-consists of 4 services:
-
-- **db**: the `Postgresql` database,
-- **elasticsearch**: the search engine,
-- **app**: the actual `DjangoCMS` project with all our application code,
-- **node**: used for front-end related tasks, _i.e._ transpiling `TypeScript` sources, bundling
-  them into a JS package, and building the CSS files from Sass sources.
-
-At "France Université Numérique", we deploy our applications on `OpenShift`/`Kubernetes` using
-[`Arnold`](https://github.com/openfun/arnold).
+Login/password are `admin`/`admin`. The database is regularly flushed.
 
 ## Getting started
 
-First, make sure you have a recent version of Docker and
-[Docker Compose](https://docs.docker.com/compose/install) installed on your laptop:
-
-```bash
-$ docker -v
-  Docker version 1.13.1, build 092cba3
-
-$ docker-compose --version
-  docker-compose version 1.17.1, build 6d101fb
-```
-
-⚠️ You may need to run the following commands with `sudo` but this can be avoided by assigning your
-user to the `docker` group.
-
-The easiest way to start working on the project is to use our `Makefile`:
-
-    $ make bootstrap
-
-This command builds the `app` container, installs front-end and back-end dependencies, builds the
-front-end application and styles, and performs database migrations. It's a good idea to use this
-command each time you are pulling code from the project repository to avoid dependency-related or
-migration-related issues.
-
-Now that your `Docker` services are ready to be used, start the full CMS by running:
-
-    $ make run
-
-You should be able to view the site at [localhost:8070](http://localhost:8070)
-
-Once the CMS is up and running, you can create a superuser account:
-
-    $ make superuser
-
-You can create a basic demo site by running:
-
-    $ make demo-site
-
-Note that if you don't create the demo site and start from a blank CMS, you will get some errors
-requesting you to create some required root pages. So it is easier as a first approach to test the
-CMS with the demo site.
+Take a look at our [Quick start guide](https://richie.education/docs/quick-start) to get started with Richie.
 
 ## Contributing
 
-This project is intended to be community-driven, so please, do not hesitate to get in touch if you
-have any question related to our implementation or design decisions.
-
-We try to raise our code quality standards and expect contributors to follow the recommandations
-from our [handbook](https://openfun.gitbooks.io/handbook/content).
-
-### Checking your code
-
-We use strict flake8, pylint, isort and black linters to check the validity of our backend code:
-
-    $ make lint-back
-
-We use strict tslint and prettier to check the validity of our frontend code:
-
-    $ make lint-front
-
-### Running tests
-
-On the backend, we use pytest to run our test suite:
-
-    $ make test-back
-
-On the frontend, we use karma to run our test suite:
-
-    $ make test-front
-
-### Running migrations
-
-The first time you start the project with `make bootstrap`, the `db` container automatically
-creates a fresh database named `richie` and performs database migrations. Each time a new
-**database migration** is added to the code, you can synchronize the database schema by running:
-
-    $ make migrate
-
-### Handling new dependencies
-
-Each time you add new front-end or back-end dependencies, you will need to rebuild the
-application. We recommend to use:
-
-    $ make bootstrap
-
-### To go further
-
-To see all available commands, run:
-
-    $ make
-
-We also provide shortcuts for docker-compose commands as sugar scripts in the
-`bin/` directory:
-
-```
-bin
-├── exec
-├── pylint
-├── pytest
-└── run
-```
+### [Contributing guide](https://richie.education/docs/contributing-guide)
 
-More details and tips & tricks can be found in our [development with Docker
-documentation](./docs/docker_development.md)
+Read our [contributing guide](https://richie.education/docs/contributing-guide) to learn about our development process and get started developing on `Richie`.
 
-## License
+### License
 
 This work is released under the MIT License (see [LICENSE](./LICENSE)).

docs/contributing.md

@@ -0,0 +1,65 @@
+---
+id: contributing-guide
+title: Contributing guide
+sidebar_label: Contributing guide
+---
+
+This project is intended to be community-driven, so please, do not hesitate to get in touch if you have any question related to our implementation or design decisions.
+
+We try to raise our code quality standards and expect contributors to follow the recommandations
+from our [handbook](https://openfun.gitbooks.io/handbook/content).
+
+## Checking your code
+
+We use strict flake8, pylint, isort and black linters to check the validity of our backend code:
+
+    $ make lint-back
+
+We use strict tslint and prettier to check the validity of our frontend code:
+
+    $ make lint-front
+
+## Running tests
+
+On the backend, we use pytest to run our test suite:
+
+    $ make test-back
+
+On the frontend, we use karma to run our test suite:
+
+    $ make test-front
+
+## Running migrations
+
+The first time you start the project with `make bootstrap`, the `db` container automatically
+creates a fresh database named `richie` and performs database migrations. Each time a new
+**database migration** is added to the code, you can synchronize the database schema by running:
+
+    $ make migrate
+
+## Handling new dependencies
+
+Each time you add new front-end or back-end dependencies, you will need to rebuild the
+application. We recommend to use:
+
+    $ make bootstrap
+
+## Going further
+
+To see all available commands, run:
+
+    $ make
+
+We also provide shortcuts for docker-compose commands as sugar scripts in the
+`bin/` directory:
+
+```
+bin
+├── exec
+├── pylint
+├── pytest
+└── run
+```
+
+More details and tips & tricks can be found in our [development with Docker
+documentation](docker-development.md)

docs/css.md → docs/css-guidelines.md

@@ -1,12 +1,16 @@
-# CSS guidelines
+---
+id: css-guidelines
+title: CSS Guidelines
+sidebar_label: CSS Guidelines
+---
 
 The purpose of these CSS guidelines is to make our CSS as easy as possible to maintain, prune and/or modify over time. To that end, they forgo some of the unwanted parts of CSS. They also require the use of a CSS preprocessor (we picked SASS) to be used effortlessly.
 
 Our approach is two-pronged. First, we put every piece of CSS as close as we can to the place it is used in a template or component. Second, we use strict class naming rules that act as a replacement to CSS selector combinations.
 
 ## File structuration
 
-Rules should be placed where their purpose is most apparent, and where they are easiest to find. 
+Rules should be placed where their purpose is most apparent, and where they are easiest to find.
 
 Generally, this means CSS rules should live as close as possible to the place they are used. For example, the selectors and rules that define the look for a component should live in a `.scss` file in the same folder as the JS file for this component. This goes for templates too. Such files can only contain rules that are __specific to this component/template and this one only__
 
@@ -21,7 +25,7 @@ Following the [BEM naming convention](http://getbem.com/introduction/), we will
     .block {}
     .block__element {}
     .block--modifier {}
-    
+
 - `.block` represents the higher level of an abstraction or component.
 - `.block__element` represents a descendent of .block that helps form .block as a whole.
 - `.block--modifier` represents a different state or version of .block.

docs/django_react_interop.md → docs/django-react-interop.md

@@ -1,14 +1,18 @@
-# Django/React interop
+---
+id: django-react-interop
+title: Connecting React components with Django
+sidebar_label: Django & React
+---
 
 `richie` is a hybrid app, that relies on both HTML pages generated by the backend (Django/DjangoCMS) based on templates, and React components rendered on the frontend for parts of these HTML pages.
 
-### Convention
+## Convention
 
 Therefore, we need a convention that enables us to easily mark those areas of the page that React needs to take control of, and to tell React which component to load there.
 
 We decided to use a specific CSS class name along with its modifiers. We reserve the `fun-react` class and its modified children for this purpose.
 
-### Example
+## Example
 
 Here is how we would call a "FeaturedCourses" component from a template, a plugin or a snippet:
 

docs/docker_development.md → docs/docker-development.md

@@ -1,6 +1,12 @@
-## To go further with development
+---
+id: docker-development
+title: Developing Richie with Docker
+sidebar_label: Docker development
+---
 
-### Settings
+Now that you have `Richie` up and running, you can start working with it.
+
+## Settings
 
 Settings are defined using [Django
 Configurations](https://django-configurations.readthedocs.io/en/stable/) for
@@ -16,7 +22,7 @@ different environments:
 
 The `Development` environment is defined as the default environment.
 
-### Front-end tools
+## Front-end tools
 
 If you intend to work on the front-end development of the CMS, we also have
 sweet candies for you! 🤓
@@ -29,7 +35,7 @@ $ make watch-css
 $ make watch-ts
 ```
 
-### Container control
+## Container control
 
 You can stop/start/restart a container:
 
@@ -39,7 +45,7 @@ or stop/start/restart all containers in one command:
 
     $ docker-compose [stop|start|restart]
 
-### Debugging
+## Debugging
 
 You can easily see the latest logs for a container:
 
@@ -60,7 +66,7 @@ section):
 
     $ bin/run app python sandbox/manage.py shell
 
-### Using sugar scripts
+## Using sugar scripts
 
 While developing using Docker, you will fall into permission issues if you mount
 the code directory as a volume in the container. Indeed, the Docker engine will,
@@ -79,7 +85,7 @@ error-prone, we provide shortcuts that we call our "sugar scripts":
 - `bin/pytest`: runs `pytest` in the `app` service using the test docker-compose
   file
 
-### Cleanup
+## Cleanup
 
 If you work on the Docker configuration and make repeated modifications,
 remember to periodically clean the unused docker images and containers by
@@ -88,9 +94,9 @@ running:
     $ docker image prune
     $ docker container prune
 
-### Troubleshooting
+## Troubleshooting
 
-#### ElasticSearch service is always down
+### ElasticSearch service is always down
 
 If your `elasticsearch` container fails at booting, checkout the logs via:
 

docs/native_installation.md → docs/native-installation.md

@@ -1,10 +1,14 @@
-# Installing Richie on your machine
+---
+id: native-installation
+title: Installing Richie on your machine
+sidebar_label: Native installation
+---
 
 This document aims to list all needed steps to have a working `Richie`
 installation on your laptop.
 
 A better approach is to use [`Docker`](https://docs.docker.com) as explained in
-our guide for [container-native](../README.md) instructions.
+our guide for [container-native](quick-start.md) instructions.
 
 ## Installing a fresh server