Merge pull request #89 from ic123-xyz/add-style-guide

docusaurus/docs/about/2-how-to-contribute/index.md

@@ -1,22 +1,28 @@
+---
+# Display h2 to h4 headings
+toc_min_heading_level: 2
+toc_max_heading_level: 4
+---
+
 # 非程序员如何贡献文章
 
 本文档的目的在于简化非程序员参与 [ic123](https://github.com/ic123-xyz/ic123) 的流程。
 
 目前 [ic123](https://github.com/ic123-xyz/ic123) 的流程偏程序员。团队目前没有资源为 [ic123.xyz](https://ic123.xyz/) 实现一个交互式的前端：登录 + 在线文件编辑。这里我们编写了此文档用来引导非程序员参与到 [ic123](https://github.com/ic123-xyz/ic123)。
 
-## 基本要求
+## 基本要求 {#prerequisites}
 
 **GitHub 账号 + 基本的 Markdown 文件编辑**
 
-## GitHub
+## GitHub {#github}
 
 目前的流程下，您需要一个 `GitHub` 账号。因为 [ic123.xyz](https://ic123.xyz/) 的源文件都是托管在 GitHub 上，所以向 [ic123.xyz](https://ic123.xyz/) 添加、修改内容唯一的方式就是向 [ic123](https://github.com/ic123-xyz/ic123) 发起 pull requests。 
 
-### 注册账号
+### 注册账号 {#github-account}
 
 如果您还没有 GitHub 账号，请参考[如何注册 GitHub 账号](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account)。
 
-### Fork
+### Fork {#github-fork}
 
 Fork 操作就是在您的 GitHub 账号下，创建一个 [ic123](https://github.com/ic123-xyz/ic123) 的拷贝仓库，关于 Fork 的具体介绍可以参考 [GitHub 的官方文档](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks)。
 
@@ -35,7 +41,7 @@ Fork 操作就是在您的 GitHub 账号下，创建一个 [ic123](https://githu
 
 ***通常以上的 GitHub 账号注册、Fork 这两步操作只需完成一次。***
 
-### 编辑
+### 编辑 {#github-editing}
 
 至此，通常程序员会选择：
 1. 本地安装好 git，配置 sshkey；
@@ -45,7 +51,7 @@ Fork 操作就是在您的 GitHub 账号下，创建一个 [ic123](https://githu
 
 但这些步骤对于非程序员来说比较麻烦，也很难配置，不过 GitHub 提供了在线文档编辑可以一定程度解决这个问题。
 
-#### 编辑文件
+#### 编辑文件 {#github-edit-file}
 
 找到您想编辑的文件，点击如下所示的编辑按钮。
 
@@ -59,7 +65,7 @@ Fork 操作就是在您的 GitHub 账号下，创建一个 [ic123](https://githu
 
 ![edit-3](./img/contribute-edit-3.png)
 
-#### 添加文件
+#### 添加文件 {#github-add-file}
 
 可以通过如下所示的 `Add file` 来添加文件。
 
@@ -76,8 +82,7 @@ Fork 操作就是在您的 GitHub 账号下，创建一个 [ic123](https://githu
 2. 小写
 3. 空格请用 `-` 替代。
 
-
-#### 添加目录
+#### 添加目录 {#github-add-directory}
 
 如果您想将您新增的文件放在一个新目录下，请按下述步骤进行操作，以 `ic123/test/test.md` 为例。
 
@@ -86,7 +91,7 @@ Fork 操作就是在您的 GitHub 账号下，创建一个 [ic123](https://githu
 
 ![add-3](./img/contribute-add-3.png)
 
-### 发起 Pull Request
+### 发起 Pull Request {#github-pull-request}
 
 当您在 forked 仓库上完成修改后，就可以发起 `PR (Pull Request)` 将您的改动提交回 [ic123](https://github.com/ic123-xyz/ic123) 。发起 PR 的界面如下图所示。
 
@@ -106,7 +111,7 @@ Fork 操作就是在您的 GitHub 账号下，创建一个 [ic123](https://githu
 
 完成以上步骤后请点击 `Create pull request` 最终完成 PR 的发起过程。
 
-### 同步 Fork
+### 同步 Fork {#github-sync-fork}
 
 当 [ic123](https://github.com/ic123-xyz/ic123) 处于开发过程中，它的改动会比较频繁，这也意味着您 Fork 的仓库可能与 ic123 并不同步。这里建议当您想添加内容、并发起一个 PR 之前，可以先同步 ic123，以减少冲突的可能性。同步的方法如下图所示。
 
@@ -120,5 +125,5 @@ Markdown 是一种轻量级标记语言，本身并不复杂。关于如何编
 1. [Markdown 的官方文档](https://www.markdownguide.org/getting-started/)
 2. [Markdown 菜鸟教程](https://www.runoob.com/markdown/md-tutorial.html)
 
-### 
+### Markdown 编辑器 {#markdown-editor}
 支持 Markdown 文件的编辑器也很多，比如 [Obsidian](https://obsidian.md/)、面向程序员的 [Visual Studio Code](https://code.visualstudio.com/) 等，可以参考[该文档](https://www.markdownguide.org/getting-started/#notes)来选择您熟悉的工具进行编辑。

docusaurus/docs/about/3-styling-guide/index.md

@@ -132,4 +132,48 @@ Docusaurus 的架构中，会被社区内容贡献者用到的文件夹有两个
 1. 文件夹的名字遵循 `x-my-dear-icp`。`x` 为阿拉伯数字序列号，方便在 IDE 里管理本地文件。网页相对应的 URL 为 `docs/yyy/my-dear-icp`。`yyy` 为 `docs/` 下选择的合适的文件夹。`x` 会被 Docusaurus 自动忽略，直接摘取后续的名字。
 2. 文章的标题在 `index.md` 文件第一行用 `#` 标明，然后就可以进入 `##` 的正文结构了。不需要 `front matter`，也不需要 `<!--truncate-->`。
 3. 文章的作者将直接在网页下方显示（包括时间戳），按照最后递交 PR ，被 merge 了的 commit 作者为准。
-4. 整篇文章在 commit 的时候，最重要的是 `my-dear-icp` 部分，因为它决定了文章的 URL 以及后续的 SEO (搜索引擎的搜索效率)。文章的其他部分都可以在初始 commit 之后继续更改而不影响文章在互联网和社交媒体上的有效传播。
+4. 整篇文章在 commit 的时候，最重要的是 `my-dear-icp` 部分，因为它决定了文章的 URL 以及后续的 SEO (搜索引擎的搜索效率)。文章的其他部分都可以在初始 commit 之后继续更改而不影响文章在互联网和社交媒体上的有效传播。
+
+## Markdown 文本编辑功能
+
+下面介绍一些在 Docusaurus 中常用的 Markdown 文本编辑功能。
+
+### 如何生成英文内链 {#enlish-heading-id}
+
+Docusaurus 默认会为中文标题生成中文的标题 ID，这样会使得生成类似如下所示的链接。
+
+`https://ic123.xyz/docs/about/styling-guide/#%E9%80%9A%E7%94%A8 `
+
+这样的链接可读性并不好，如果您觉得您的标题可能会被单独链接，推荐使用自定义的标题 ID，如下所示。
+
+`### account: 账号 {#account}`
+
+这样 Docusaurus 会为您生成如下所示的链接。
+
+`https://ic123.xyz/docs/getting-started/ic-glossary/#account`
+
+具体代码请参考 [GitHub](https://github.com/ic123-xyz/ic123/blob/main/docusaurus/docs/getting-started/4-ic-glossary/index.md?plain=1#L5) 。
+
+更多信息，请参考 [Docusaurus 官方文档](https://docusaurus.io/docs/markdown-features/toc#heading-ids)。
+
+请注意：
+1. 不要使用重复的标题 ID，会产生冲突。
+2. 该功能 GitHub 并不支持，所以您在 GitHub 的预览页面该功能并不会启用。
+
+### 如何修改目录层级 {#headings-of-toc}
+
+Docusaurus 默认会在文档右侧的目录栏包含三级、及三级以上的标题。如果您需要支持到四级、甚至四级以上的目录结构，请按一下方式配置。
+
+在您的文档的前文使用 `toc_min_heading_level` 和 `toc_max_heading_level` 来定义目录所包含的最小和最大标题级别，如下所示。
+
+```
+---
+# 显示 h2 到 h5 标题
+toc_min_heading_level: 2
+toc_max_heading_level: 5
+---
+```
+
+具体的示例请参考[注册互联网身份](https://ic123.xyz/docs/ic-web3/internet-identity/)。对应的代码示例请参考 [GitHub](https://github.com/ic123-xyz/ic123/blob/main/docusaurus/docs/ic-web3/1-internet-identity/index.md?plain=1#L1)。
+
+更多信息，请参考 [Docusaurus 官方文档](https://docusaurus.io/docs/markdown-features/toc#table-of-contents-heading-level)。