docs: update contribution guidelines, technical setup and readme (#20)

Co-authored-by: AndrewB9lab <104000630+AndrewB9lab@users.noreply.github.com>
Co-authored-by: CitMC <75622342+CitMC@users.noreply.github.com>

CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+We welcome all contributions!
+
+## Setup and local development
+
+We recommend you run the platform locally to review your changes before submitting them. Please refer to the instructions in the [TECHNICAL-SETUP.md](TECHNICAL-SETUP.md) file to set up and run the app in your local environment.
+
+## Language and style
+
+Content production in this project follows the general conventions and best practices from the [Google developer documentation style guide](https://developers.google.com/style).
+
+## Components and platform features
+
+The platform supports a number of custom components. You can find an overview of all components, and a demonstration of their use, within the [`/features-test/index.md`](./features-test/index.md) file - the feature test is also deployed to the [live portal](https://docs.topos.technology/features-test).
+
+Additionally, the file [`features-test/landingpage.md`](./features-test/landingpage.md) demonstrates the use of the landingpage components, and is also deployed to the [live portal](https://docs.topos.technology/features-test/landingpage.html).
+
+## Pull request
+
+Please submit your contribution with a **Pull Request** using our default Pull Request template. If you are planning a larger contribution, we recommend you open an **Issue** first (indicating that you would like to contribute to solve the issue), to allow for further coordination before the submission.
+
+> [!NOTE]
+> When you submit your Pull Request for review, please make sure to add as much information as possible on the changes implemented through your Pull Request.
+> For example, include what existing files you are updating or creating and with what aim.

README.md

@@ -2,7 +2,7 @@
 
 This repository contains the documentation platform for the Topos protocol and ZkEcosystem.
 
-The platform is deployed automatically to
+The platform is deployed automatically to:
 
 ➡️ [https://docs.topos.technology](https://docs.topos.technology)
 
@@ -12,6 +12,9 @@ This repository is currently maintained by [B9Lab](https://github.com/b9lab).
 
 We welcome all contributions to this repository. If you see any error or would like to propose an idea, please feel free to open an Issue, or submit an update via a Pull Request.
 
+> [!NOTE]
+> Please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) guide for further information on how to contribute to this repository.
+
 ## Install
 Install packages using
 
@@ -29,6 +32,8 @@ npm install -g gatsby-cli
 
 Next to the default `gatsby-config.ts` file, additional configuration options are exposed in `config.ts`.
 
+> [!NOTE]
+> Please refer to the [TECHNICAL-SETUP.md](TECHNICAL-SETUP.md) guide for more information on the configuration, build, and deployment of the platform.
 
 ## Run local dev environment
 

TECHNICAL-SETUP.md

@@ -0,0 +1,97 @@
+# Technical Setup
+
+## Install and run locally
+
+Install packages with your package manager:
+
+```
+npm install
+```
+
+> [!WARNING]
+> Note: This platform uses Gatsby version 5, which requires Node.js 18 or later.
+
+### Gatsby CLI
+
+This platform uses Gatsby. For local development, you might want to install the gatsby-cli tools, which allow you to run gatsby commands directly. Install it globally with:
+
+```
+npm i -g gatsby-cli
+```
+
+### Run locally
+
+You can start the local development environment with:
+
+```
+npm run start
+```
+
+This calls the Gatsby command `gatsby develop`.
+
+## Platform configuration
+
+The configuration is split into two files, located in the root folder:
+
+* `gatsby-config.ts` - the main Gatsby configuration file, including the plugin config
+* `config.ts` - menu/content, meta, and theme configuration
+
+### Main menu and files
+
+The `config.ts` file defines the main menu and all content files that should be linked in it. This configuration is located in the `navigation` section and looks like this:
+
+```
+navigation: [
+  {
+    label: 'What is Topos?',
+    content: [
+      {
+        label: 'Chapter overview: What is Topos?',
+        path: '/content/module-1'
+      },
+      {
+        label: 'Introduction',
+        path: '/content/module-1/1-introduction.html'
+      },
+    ]
+  },
+  {
+    label: 'First steps with Topos',
+    content: [
+      {
+        label: 'Chapter overview: First steps with Topos',
+        path: '/content/module-2'
+      },
+    ]
+  }
+]
+```
+
+> [!NOTE]
+> * The top elements labeled _What is Topos_ and _First steps with Topos_ are the Category names (modules), which contain multiple content files (sections). Files will be displayed in the same order as configured here.
+> * When linking to an index file (named `index.md`), you should link to the folder (eg. `/content/module-1`).
+
+> [!IMPORTANT]
+> This is the main file to inform the platform about the content structure - it also sources into the prev/next page navigation.
+
+#### File names
+
+Files are prefixed with a number indicating their position in the config. This is just for convenience when viewing the file system and does not impact the menu.
+
+#### Adding new content folders
+
+Content is located in the `content` folder. If you want to add another folder next to the content folder, you also need to update the `includeFolder` setting in the `config.ts` file.
+
+## Build process
+
+You can start the build process locally with `npm run build`. During the build process:
+
+* All images are processed; images are resized to a max size, further size variants are created, and images are compressed.
+* Sharing cards (social-cards) are prepared for all pages.
+* Static html pages are generated.
+
+The output is generated in the `public` folder.
+
+## Deployment
+
+The page deploys as a static page. Preview deployments are built and deployed on Netlify. The main page deploys to GitHub Pages using a [GitHub Action](.github/workflows/deploy.yml).