通用编辑规则与技巧

写得简单

主要目标是使其尽可能易于理解。想象一下您正在教您 9 岁的侄子如何编程。当您教授某人一个新主题时，请假设该学生对此一无所知。

使用图片、GIF、视频链接

不要只用满页的文字来轰炸学生。大约 1/3 的内容应该以图形形式呈现。更倾向于展示，而不仅仅是谈论。

小心链接

页面 URL 末尾的斜杠存在一个已知问题。默认情况下，我们假设我们的 URL 以斜杠结尾。

假设您有以下文件夹结构

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

当您打开 std/index.mdx 时，它将作为该目录的默认文档使用，URL 如下：

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

要添加指向 std/math/functions.mdx 的链接，您必须使用

[Math functions](math/functions)

or

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

因为我们已经位于 docs/std/ 文件夹中，**由于末尾的斜杠**。如果您想引用同一目录中的文档，而引用的文档**不是**默认文档，这会导致意外行为。

现在考虑以下文件夹结构

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

如果您打开 foo 文档，URL 将是

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

这会造成 foo 是目录的假象，但它不是。如果您想从 foo 文档引用 bar，您必须从父目录（docs）开始

[Bar](../bar)

or

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

添加标签

标签有助于人们找到他们感兴趣的主题。请在文档元数据中添加标签。

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

使用警示（notes、tips、cautions、dangers）

要创建漂亮的警示，请使用以下语法

:::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
:::

预览

标题

这是一个提示

标题

这是一个注释

标题

这是一个重要提示

标题

这是一个警告

标题

这是一个危险提示

重要

本节需要改进。您可以通过编辑此文档页面来帮助我们。