Skip to content

Commit a7a4f51

Browse files
docs: Revise headings and add labels
1 parent d6510aa commit a7a4f51

File tree

3 files changed

+187
-56
lines changed

3 files changed

+187
-56
lines changed

README.en.md

Lines changed: 44 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,18 +75,36 @@ For each issue, please try to:
7575

7676
For example, typing Chinese characters requires an IME. You can link to [Unicode FAQ on Chinese and Japanese](https://unicode.org/faq/han_cjk.html).
7777

78-
7978
But in most cases:
8079

8180
- No need to provide a solution directly
8281

8382
Just link it as `#workaround("https://…")`.
8483

85-
8684
- No need to describe comprehensively, nor is it recommended to propose improvements too much
8785

8886
These contents can be initially proposed at [GitHub Issues](https://github.com/typst-doc-cn/clreq/issues/), and should eventually be forwarded to the Typst official.
8987

88+
### Maintaining
89+
90+
GitHub Actions are watching `#issue` and `#pull` annotated in the document, and will report in [🤖 Cron check · Issue #22](https://github.com/typst-doc-cn/clreq/issues/22) and pull request if their states changes.
91+
92+
We can update the document once we notice. There is no need to wait until Typst releases a new version.
93+
94+
An example update is as follows.
95+
96+
```diff
97+
- #level.basic
98+
+ #level.ok
99+
- #issue("typst#633")
100+
- #pull("typst#5777")
101+
+ #issue("typst#633", closed: true)
102+
+ #pull("typst#5777", merged: true)
103+
#workaround("https://typst-doc-cn.github.io/guide/FAQ/cite-flying.html")
104+
+
105+
+ #till-next(now-fixed.with(last-affected: "0.13.1", last-level: "basic"))
106+
```
107+
90108
### Multilingual content (`babel`/`bbl`)
91109

92110
- The `en` and `zh` fields are displayed in English and 中文 modes, respectively.
@@ -112,6 +130,30 @@ Tips:
112130

113131
- Don’t pay special attention to line breaks and indentation. Just use tinymist (VS Code) / typstyle default settings. To make version comparison easier, we have set up a pull request robot to automatically format them.
114132

133+
### Title formats
134+
135+
- Top-level sections representing **categories**
136+
137+
The title should be as consistent as possible with [W3C Gap Analysis documents](https://www.w3.org/TR/clreq-gap/).
138+
139+
- Low-level sections derscribing **specific gaps**
140+
141+
- For features that are needed but **not yet supported**, express titles as **phrases** whenever possible.
142+
143+
Examples:
144+
145+
- Vertical writing mode | 直排
146+
- Customizing punctuation overhang | 定制标点悬挂
147+
148+
- For issues of **existing** features, express titles as **sentences** whenever possible.
149+
150+
Examples:
151+
152+
- Spacing between heading numbering and title is too wide | 标题编号与内容之间的空隙过宽
153+
- Citation numbers are flying over their brackets | 引用编号的数字高于括号
154+
155+
- Do not edit the title after the gap is resolved, unless you have a good reason.
156+
115157
### Adding a code example
116158

117159
Code examples will be compiled when rendering the website.

README.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,26 @@ pnpm dev --open # ⇒ http://localhost:3000
8686

8787
这些内容可初步在 [GitHub Issues](https://github.com/typst-doc-cn/clreq/issues/) 提出,最终应反馈给 Typst 官方。
8888

89+
### 维护更新
90+
91+
GitHub Actions 会监控文档中标记的`#issue``#pull`,发现状态变化就会在 [🤖 Cron check · Issue #22](https://github.com/typst-doc-cn/clreq/issues/22) 和 pull request 提醒。
92+
93+
收到提醒即可更新文档,不必等到 Typst 发布新版本。
94+
95+
更新示例如下。
96+
97+
```diff
98+
- #level.basic
99+
+ #level.ok
100+
- #issue("typst#633")
101+
- #pull("typst#5777")
102+
+ #issue("typst#633", closed: true)
103+
+ #pull("typst#5777", merged: true)
104+
#workaround("https://typst-doc-cn.github.io/guide/FAQ/cite-flying.html")
105+
+
106+
+ #till-next(now-fixed.with(last-affected: "0.13.1", last-level: "basic"))
107+
```
108+
89109
### 多语言内容(`babel`/`bbl`
90110

91111
- `en``zh`两字段分别在 English、中文模式显示。
@@ -111,6 +131,30 @@ pnpm dev --open # ⇒ http://localhost:3000
111131

112132
- 不用刻意关注换行与缩进,按 tinymist (VS Code) / typstyle 默认即可。为方便对比版本,已设置 pull request 机器人自动统一格式。
113133

134+
### 标题格式
135+
136+
- 表示**分类**的大章节
137+
138+
标题尽量与 [W3C 差距分析文档](https://www.w3.org/TR/clreq-gap/)保持一致。
139+
140+
- 描述**具体差距**的小章节
141+
142+
- 对于需要支持但**尚不支持**的功能,标题尽量用**短语**表达。
143+
144+
示例:
145+
146+
- Vertical writing mode | 直排
147+
- Customizing punctuation overhang | 定制标点悬挂
148+
149+
- 对于**已支持**功能存在的问题,标题尽量用**句子**表达。
150+
151+
示例:
152+
153+
- Spacing between heading numbering and title is too wide | 标题编号与内容之间的空隙过宽
154+
- Citation numbers are flying over their brackets | 引用编号的数字高于括号
155+
156+
- 差距解决之后,尽量不再修改标题。
157+
114158
### 添加代码例子
115159

116160
代码例子会在渲染网站时编译。

0 commit comments

Comments
 (0)