diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ef61ee5 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/README.md b/README.md index c010c92..774237b 100644 --- a/README.md +++ b/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 diff --git a/TECHNICAL-SETUP.md b/TECHNICAL-SETUP.md new file mode 100644 index 0000000..8e6338b --- /dev/null +++ b/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).