Its highly recommended to view the source code of other existing files before adding a new document. This allows you to become familiar with the convention and ensure that your new file fits the criteria. Before doing so, however, we ask that you consult with us first by filing an issue.
We're using Docusaurus to write documents. This tool uses an extended markdown format (MDX). It is a combination of Markdown and JSX, which allows us to write custom components in React. We use our component library to extend the capabilities of what we can put inside a document. With MDX, we can create documents that are more interactive and engaging for our users than a typical site.
Visit this link to learn how to create docs in Docusaurus.
Depending on what type of document you're looking to write, the content of the document will have to follow certain guidelines.
Let's say that you want to write a lesson (within the course) about class constructors.
First, you have to create an English version of the document, even if you want to write in other language. This is because it's our fallback language, therefore all locales that doesn't provide translation for certain documents will fallback to the English one. Pick a lowercase name without spaces, separated by hyphens, for example:
Since we already have a
classes directory, we can skip the
class- prefix, and finally end up with:
You'll have to fill the metadata of the document. Open it, and at the very top create a document metadata section.
sidebar_label: "1. Class constructors"
title: "Class constructors"
description: "Lesson: basics of class constructors in C++ language"
tags: [class, constructor, method, object, object-oriented-programming, object-oriented, oop]
sidebar_position field was mandatory, but it's not used now. Feel free to remove it from documents that
still contain it. The position is now strictly managed through order in
hide_title: true should be only used when there is something between metadata and the Markdown H1 heading,
<!-- Components -->
import Columns from "@site-comps/Columns";
<!-- Presets -->
import NotFinished from "@site/i18n/en/presetsNotFinished";
# The title of the document
Do not use it if metadata is directly above
# The title of the document, because
Docusaurus will generate an additional H1 heading.
For complete metadata list, please visit this page.
Adding to the sidebar
Your document won't be visible in the sidebar at first. Navigate to the
and find appropriate file (
learn.js for Learn section,
tools.js for Tools section, etc.)
constructors to the list.
label: '9. Classes',
Adding the content
Please read our General editing rules and tips
Right now we don't have doc templates. We will create them in the future, once we establish some kind of a standard.
We have examples of good docs that you should visit and possibly use them as a temporary template:
- std::array reference - a good template for class summary page
- std::basic_string constructors - a good template for constructors or other methods
- std::basic_string::at - a good (?) template for class methods