Przejdź do głównej zawartości

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.

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.

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.

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.

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.

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.