General editing rules and tips

Write simple

The main goal is to make it as easy to understand as possible. Imagine that you teach your 9 year old nephew how to program. When you teach someone a new topic, assume that the student does not know anything about it yet.

Use images, GIFs, video links

Do not flood the students with pages full of text only. Roughly 1/3 of the content should be in a graphical form. Prefer showing, not only talking about it.

Be careful with links

There is a known issue with a trailing slash at the end of page URL. By default, we assume, that our URLs end with a slash.

Let's say that you have a following folder structure:

- docs
  - std
  --> index.mdx
	- math
	--> functions.mdx

When you open the std/index.mdx, it will be used as a default document from that directory, with following url:

https://cpp-lang.net/docs/std/		<-- notice the trailing slash

To add a link to std/math/functions.mdx you'll have to use:

[Math functions](math/functions)

or

<a href="math/functions">Math functions</a>

because we're already inside of the docs/std/ folder, because of the trailing slash. That leads to an unexpected behavior, if you want to reference a document from the same directory, when the referencing document is not a default document.

Lets now consider the following folder structure:

- docs
--> foo.mdx
--> bar.mdx

If you open the foo document, the URL will be:

https://cpp-lang.net/docs/foo/		<-- notice the trailing slash!

This creates a false impression that the foo is a directory, which it isn't. If you want to reference bar from the foo document, you'll have to start at the parent directory (docs):

[Bar](../bar)

or

<a href="../bar">Bar</a>

Add tags

Tags help people find the topic they're interested in. Please add tags to the document metadata.

---
tags: [tag1, tag2]
---

Use admonitions (notes, tips, cautions, dangers)

To create a fancy looking admonition, use the following syntax:

:::tip[Title]
This is a tip
:::

:::note[Title]
This is a note
:::

:::important[Title]
This is an important note
:::

:::caution[Title]
This is a caution note
:::

:::danger[Title]
This is a danger note
:::

Preview:

Title

This is a tip

Title

This is a note

Title

This is an important note

Title

This is a caution note

Title

This is a danger note

important

This section requires improvement. You can help by editing this doc page.