New documents

important

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.

Overview

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.

tip

Visit this link to learn how to create docs in Docusaurus.

Guidelines

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:

class-constructors.mdx

Since we already have a classes directory, we can skip the class- prefix, and finally end up with:

classes/constructors.mdx

Document metadata

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]
hide_title:			true
---

Legacy field

The 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 /sidebars/<section>.js file.

danger

hide_title: true should be only used when there is something between metadata and the Markdown H1 heading, for example:

---
...
hide_title:			true
---

{/* 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 /sidebars directory, and find appropriate file (learn.js for Learn section, tools.js for Tools section, etc.) then add constructors to the list.

Sidebars are configured using JavaScript, but most of the their configuration is done with simple arrays and objects so it will be easy for you to use, even if you don't know the language. The document we created should be added to the sidebar like this:

// ...
{
	type: 'category',
	label: '9. Classes',
	items: [
		'course/intermediate/classes/intro',
		'course/intermediate/classes/constructors',
		'course/intermediate/classes/destructors',
		// ...
	]
}

Adding the content

caution

Please read our General editing rules and tips

Templates

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:

Documentation:

• 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

Learning:

• First program (Basics)
• Functions (Basics)
• Structures (Basics)