How to contribute to Chroma?

Contributing to Chroma

This guide is designed to walk you step by step through the process of contributing to Chroma. Whether it’s suggesting ideas, identifying issues, or writing your own pages, there is always a way to lend a hand!

Giving Feedback: Questions & Suggestions

The first way to contribute to improving the site is by sharing your feedback and suggestions for improvement. There are two main ways to do this:

On Discord: The 🔍 Review and Feedback channel allows you to ask questions, discuss with other contributors, and suggest ideas to improve the site.
On GitHub: If you notice a bug, don’t hesitate to create an issue on the Chroma repository.

Contributing to Chroma Development

If your goal is to write a new tutorial, rewrite part of an existing one, or dive into the site’s source code to help improve it, you can set up a development environment on your local computer.

Prerequisites

Node.js — version 20.11 or higher (LTS).
Hugo — version 0.143.1.
Hugo extended — version 0.143.1.
An IDE such as Visual Studio Code.
Basic GitHub knowledge (forks, issues, pull requests) — a tutorial is available on the site.

Setting Up the Development Environment

First, create a fork of the Chroma repository. Then clone your fork to your machine with git clone. Inside a terminal in the project directory, run the following command to install the necessary dependencies:

npm install

This gives you access to a development server to preview the site. Still inside the project directory, run the command below to start the local development server:

npm run dev

If everything went well, your terminal will display a message with a clickable link to your local site (at a localhost address):

Watching for changes in /.../chroma/{assets,content,i18n,layouts,node_modules,package.json,static}
Watching for config changes in /.../chroma/config/_default, /home/mowibox/Documents/WorkspaceU/Git_folders/chroma/config/_default/menus
Start building sites … 
hugo v0.143.1-0270364a347b2ece97e0321782b21904db515ecc+extended linux/amd64 BuildDate=2025-02-04T08:57:38Z VendorInfo=gohugoio


                   | EN  | FR
-------------------+-----+------
  Pages            |  69 |  68
  Paginator pages  |   0 |   0
  Non-page files   |   2 |   2
  Static files     | 253 | 253
  Processed images |   4 |   0
  Aliases          |  13 |  12
  Cleaned          |   0 |   0

Built in 1638 ms
Environment: "development"
Serving pages from disk
Web Server is available at http://localhost:1313/chroma/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Click the link to browse the site in your browser. While the server is running, any saved changes will automatically update on the local preview.

Tip

If you encounter build or display issues, this command cleans previously generated files by Hugo (public, resources, etc.) to reset the environment before rerunning npm run dev:

npx shx rm -rf public resources hugo_stats.json .hugo_build.lock

Site Structure

The Chroma folders and files are organized as follows:

.
├── assets/
├── config/
│   └──_default/
│      ├── hugo.toml
│      ├── menus.toml
│      ├── module.toml
│      └── params.toml
├── content/
│   ├── en/
│   └── fr/
|       ├── blog/
|       ├── computer_vision/
|       └── tutorials/
├── i18n/
├── layouts/
└── static/
    ├── gifs/
    ├── icons/
    └── images/

assets/ contains source resources (SCSS, JavaScript, styles, etc.) used by the site.
config/ contains configuration files and general settings.
content/ holds all site pages, organized by language (en/ and fr/).
i18n/ contains translation files.
static/ contains static files (images, gifs, icons, etc.).

Generally, the tutorials/ folder is the main focus, subdivided into four categories: Computer Science (computer_science/), Electronics (electronics/), 3D Design & Development (design_3d_development/), and Miscellaneous (miscellaneous/). Contributions may also involve other parts of the site, e.g., known issues.

Writing a Tutorial

The following section details the steps to create and format a new tutorial:

Step	Description
VSCode Extensions	Install useful extensions for site development
Adding the Tutorial	Create the folder and `index.md` file for your tutorial
Front-Matter	Fill out the front-matter (title, description, date, weight, etc.)
Weight Convention	Define the tutorial’s order using the `weight` field
Content Formatting	Write the tutorial in Markdown using the recommended structure
Adding Images	Add images to the appropriate folders and reference them correctly
Page Credits	Add a credits section at the bottom of the tutorial

VSCode Extensions Useful for Site Development

If you use VSCode, here is a non-exhaustive list of extensions that can help properly format your files:

Adding the Tutorial to the Folders

To create a tutorial, create a folder containing an index.md file. First identify the theme of your tutorial to place it in the correct folder (Computer Science, Electronics, etc.). There is two rules for folder naming:

The folder name must be in English to simplify fr/en localization.
Keep folder names reasonably short.

You can use the command hugo new content content/<folder_path>/index.md to create the page directly with its path.

Example: The tutorial “Introduction to Embedded Programming” is a English electronics tutorial. The folder introduction_to_embedded_prog/ and its index.md file were created in content/en/tutorials/electronics/ using:

hugo new content content/en/tutorials/electronics/introduction_to_embedded_prog/index.md

The URL will be: https://mowibox.github.io/chroma/en/tutorials/electronics/introduction-to-embedded-programing/

.
└── en/
    ├── blog/
    ├── computer_vision/
    └── tutorials/
        ├── computer_science/
        ├── design_3d_development/
        └── electronics/
            └── introduction_to_embedded_prog/
                └── index.md

Front-Matter

Each tutorial page starts with front-matter, enclosed by ---. Fields are as follows:

---
title: ""
description: ""
summary: ""
date:
lastmod:
draft: false
weight:
toc: true
icon: ""

seo:
   title: ""
   description: ""
   canonical: ""
   noindex: false
   robots: "index, follow"

---

title: This is the title of your tutorial. I think that’s pretty self-explanatory, right?
description: Describe your content in one short sentence. Used in particular for the preview in the list of tutorials.
summary: Describe your tutorial in a little more detail, in 2-3 sentences.
date: The date you started writing your tutorial, in YYYY-MM-DD format.
lastmod: The date the tutorial was last modified, in YYYY-MM-DD format.
draft: Makes the tutorial visible or invisible during preview. By default, it is visible (true).
weight: Defines the display order of your content in the list of tutorials. How to fill it in is detailed in the next section.
toc: Displays the table of contents for the page. By default, it is displayed (true).
icon: You can add a new icon by going to Tabler Icons. This will be the icon that illustrates your page in the list of tutorials
Warning
Please note that the icon color must be #a514e9 and must be added to the static/icons folder.
seo.title: Title optimized for search engines. It may differ from title.
seo.description: Description displayed in search engine results.
seo.canonical: Canonical URL of the page
seo.noindex: Manages the indexing of the page by search engines. Enabled by default (false).
seo.robots: Tells search engines how to index the page.

Tutorial cardlist example
Example of a tutorial preview in the list. Fields title, description, and icon are used.

Tip

Do not hesitate to check existing tutorial front-matter to see how to fill yours!

Weight Convention

Tutorial order is defined in the front-matter using the weight field. Currently, this value is manually managed (by myself). You can leave it empty, or launch the site locally, identify tutorials near your desired position, and adjust weights accordingly.

Content Formatting

Write your content mainly in Markdown, which is easy to learn. Markdown is also used for README files on GitHub.

To go further and take advantage of all the site’s features, the Doks documentation offers detailed guides on content creation:

Authoring content explains text structuring, headings, paragraphs, lists, etc.
Use shortcodes for notes, tips, buttons, and dynamic content.
For writing code, see Code blocks.
For mathemarical expressions, use Math support.
Diagrams and schematics are possible via Diagrams.

Feel free to combine Markdown features and Doks shortcodes to give your tutorial a visual identity. And speaking of visuals, here’s the section about images!

Adding Images

All images on the site dedicated to pages are stored in the static/images/. folder. To integrate an image from the folder into your page, adapt the following HTML block to your needs:

<p align="center">
    <img src="/chroma/images/image1.jpg" alt="Image 1 short description" class="w-full h-auto" />
</p>

Where image1.jpg is the name of the image. If you want to add a new image, simply add the image in question to the static/images/ folder so that it can be used. As with the rest of the site, there are certain points to bear in mind when adding images:

The image must not exceed 2 MB.
The image used must be royalty-free.
It is preferable to name the image in relation to the tutorial you are writing. For example, the images in this tutorial are named contribute1.jpg, contribute2.png, etc. This makes it easier to find which tutorial the image is used in.
If certain images can be used in several tutorials, you can give them a more generic name, while adding an underscore (_) at the beginning to distinguish them (e.g., _buzzer.jpg).
The alt field must contain a very short description of the image content in English.

You can also add a caption to your image using the HTML block below:

<p align="center">
    <img src="/chroma/images/image2.jpg" alt="Image with caption" class="w-full h-auto" />
    </br>
    <em style="font-size: 0.95em;">An image with a caption.</em>
</p>

Image caption example
An image with a caption.

Tip

Gifs and icons follow the same rules (static/icons/, static/gifs/).

Page Credits

At the end of each page of the site (such as this one), a section dedicated to page credits must be added. Here is the format:

---

## Credits

* **Writer:**
* **Reviewer:**

Writer: You! There may be several authors, separated by commas.
Reviewer: These are the people who proofread your tutorial and offered suggestions. There is no need to indicate this if you are the author. If you do not have proofreaders, the field can be left blank, but it must be present in all cases.

Requesting a Review

Satisfied with your tutorial? All you have to do now is make a pull request so that a collaborator can check the tutorial! The title of the pull request should be clear, for example:

“Add tutorial “Introduction to Python” - EN”
“Suggested correction in the tutorial “Utilisation du terminal” - FR”
“Improvement to the tutorial viewing interface”
etc.

The pull request description should briefly explain the modifications or additions. A contributor will check that all points are respected. If not, you will receive feedback to make changes. Once correct, the changes will be merged into the main site.

Congrats and thank you!

Credits

Writer: Ousmane THIONGANE
Reviewer:

Last updated on March 2, 2026

PWM signal generation tutorial

Perform a dual-boot with Windows

How to contribute to Chroma?

Giving Feedback: Questions & Suggestions#

Contributing to Chroma Development#

Prerequisites#

Setting Up the Development Environment#

Site Structure#

Writing a Tutorial#

VSCode Extensions Useful for Site Development#

Adding the Tutorial to the Folders#

Front-Matter#

Weight Convention#

Content Formatting#

Adding Images#

Page Credits#

Requesting a Review#

Credits#

Giving Feedback: Questions & Suggestions

Contributing to Chroma Development

Prerequisites

Setting Up the Development Environment

Site Structure

Writing a Tutorial

VSCode Extensions Useful for Site Development

Adding the Tutorial to the Folders

Front-Matter

Weight Convention

Content Formatting

Adding Images

Page Credits

Requesting a Review

Credits