Zotero 中文社区

主题

文档风格指南 ​

本文档旨在对于 Zotero 中文社区上发表文档的语言、版式、内容元素等方面提出可执行的要求，以便维持和改进文档的整体水平与可读性。

本文档未涉及的风格问题，应参考中文互联网一般实践，以及中文出版物的行业标准和国家标准；仍然不能得出结论的，可依兼顾严谨与开明的方针自行判断。

文件命名 ​

文档网站根据每个 Markdown 源文件的路径确定每个页面的路由。因而，确定文件名时应慎重，一旦确定，尽量不要再改动。 由于 Windows 不区分文件名大小写，故而 option-B.md 和 option-b.md 在 Windows 下会出现冲突。

我们使用的文件的命名规则是：

  • 文件名一律采用小写字母
  • 文件名应尽量使用单词全称，避免使用各种形式的简写
  • 若文件名中含多个单词，应使用连字符 (hyphen) - 连接

文档 FrontMatter 规范 ​

通过 FrontMatter 为每个 Markdown 页面引入配置。

一般情况下，不需要手动配置 FrontMatter。

详细信息

Frontmatter 必须在 Markdown 文件的顶部，并且被包裹在一对三短划线中间。下面是一个基本的示例:

md
---
title: 页面的标题
authors:
  - 作者1
  - 作者2
  - 作者3
date: 2023-07-20 23:46:54
---

<!-- 这里是 Markdown 内容 -->

...

下面是一些常用的 Frontmatter 键：

键类型必填默认值描述
titlestring否第一个一级标题页面的标题。如果你不在 Frontmatter 中设置 title ，那么页面中第一个一级标题（即 # title）的内容会被当作标题使用。
authorstring[]否-当前文档的作者增补，默认情况下会从 Git 记录获取作者。
datastring否文件的创建日期文档的创建日期

文档语法风格 ​

所有教程均采用 Markdown 语言编写，下面列出了一些本文档中可能用到的语法和注意事项。

标题 ​

md
# 一级标题

## 二级标题

### 三级标题

#### 四级标题

提示

一级标题是文档名，对应页面标题，一篇文档应有且只有一个一级标题。

  • 文档内容从二级标题开始
  • 文档中标题级别应逐级递增，例如：二级标题内应跟随三级标题，而不能越过三级标题直接使用四级标题
  • 标题不应含有特殊字符：如 latex 公式，代码块，数字编号等，不应以标点符号结尾
  • 标题前后空一行
  • 不应仅出于放大字体、突出重点或强调的目的而使用标题样式

正文文本 ​

md
正文段落 1
(空行)
正文段落 2

中英文字符间的空格 ​

汉字与英文字母、数字间应手动追加一个空格。但是，如英文部分之前或之后有中文标点符号，则英文部分与中文标点之间不设空格。

如 「中文 ABC 中文」 而非 「中文ABC中文」，「中文 123 中文」 而非 「中文123中文」

为什么鼓励在中英文之间添加空格？

依通说，中英文之间加入空隙，是为了实现视觉上的区隔，更加美观和易读。理想情况下，这种「空隙」应由排版引擎自动加入，宽度宜为 ¼ 个全角空格（em）。但由于数字排版环境复杂多变，在大多数时候（包括最常见的网页环境）不能指望排版引擎有这种能力，因此只能退而求其次，手动插入一个半角空格（因其宽度通常接近于 ¼ em），达到类似效果。

关于本规定的进一步讨论，参见知乎讨论「中英文混排时中文与英文之间是否要有空格？」，W3C 标准草案《中文排版需求》§ 3.2.2，以及《字谈字畅》播客 第 14 期。

仓库已经配置了工具自动在中英文之间添加空格，在安装了仓库需要的依赖项和 VS Code 的插件后，在保存时，会自动添加空格。

标点符号 ​

标点符号采用全角，如 ，、。、：、、、？ 等，标点符号与中文字符、英文字符以及数字之间不需加空格。

其他标点符号的使用参考 《少数派风格指南》§ 标点符号的形态 和 中国国家标准 GB/T 15834—2011《标点符号用法》。

特别的，我们期望对中文使用「直角引号」而不是“弯引号”：

使用单直角引号 「（U+300C）和 」（U+300D）。引号中再次使用引号时，用双直角引号 『（U+300E）和 』（U+300F）。

推荐使用直角引号

鼓励使用直角引号，是因为在中英文混排的场合，弯引号常常套用英文字体而显示为半角宽度，与汉字和其他中文标点差异很大，从而对排版效果产生不利影响。我们承认并尊重就此存在的不同审美判断，仅出于统一风格目的对文章做此要求。

你可以放心输入弯引号

由于直角引号确实不方便输入，所以仓库已经配置了自动化工具，如果你安装了仓库推荐的 vscode-markdownlint 插件，那么你输入的 “ ” 将被自动转换为 「 」。

要输入中文直角引号：

  • macOS 自带中文输入法：按 Shift + [ / ]。
  • iOS 自带中文输入法：长按引号键，在弹出的浮条中选择直角引号。
  • Windows 自带中文输入法：
    （旧版本）按 Win + .，切换到「Ω」标签页，选择直角引号。
    （新版本）或是按 Win + .，切换到「🔣 符号」标签页，选择「语言符号」标签页，然后选择直角引号。
  • 其他中文输入法：在设置中开启「使用直角引号」或类似选项（如提供）；或配置用户词典。

文字样式 ​

md
这是一段文本，
**用两对星号包裹的内容会被加粗**，
而*只用一对星号（或下划线）包裹的内容会显示为斜体*，
用~~两对波浪线包裹的内容会显示为删除~~，
你可以标记 ==重要的内容== 。

预览： 这是一段文本， 用两对星号包裹的内容会被加粗， 而只用一对星号（或下划线）包裹的内容会显示为斜体， 用两对波浪线包裹的内容会显示为删除， 你可以标记 重要的内容 。

快捷键

  • 粗体：Ctrl + B
  • 斜体：Ctrl + I

不应以下列方式使用粗体样式：

  • 频繁、连续、大面积地设置粗体
  • 以粗体样式代替标题样式

专有名词 ​

大小写应正确，如：Zotero 不是 zotero，GitHub 不是 github。

仓库配置了一些专有名词的正确格式，如果安装了仓库推荐的插件，保存文档时可以自动替换，名词列表见 Markdownlint 配置文件。

用户界面 ​

按键 ​

按键名称应当只大写第一个字母（sentence case）；除非会与上下文混淆，宜省略「键」字。

除方向键、空格键、菜单键外，按键名称不应翻译为中文。

组合键的各按键之间应以加号（+）连接，加号前后添加空格。

描述键盘输入的标准 HTML 元素为 <kbd>，但由于我们目前未对 <kbd> 标签提供专门样式和功能支持，我们期望使用行内代码样式作为替代。

界面元素 ​

除非容易产生混淆，宜在描述界面元素时省略其类型名称，直接以文本标签称呼。

将界面元素名称放入直角引号内。

如果有连续的步骤，使用大于号 >、连接号 - 或其组合 -> 来连接各步骤页面元素。

如： 操作步骤：「编辑」->「设置」->「引用」。

链接 ​

md
[相对路径访问主页](../README.md)

[相对路径访问贡献指南](./contributing.md)

引用文档内的内容，可以使用相对链接：./ 表示当前目录，../ 表示上一级目录，../../ 表示上两级目录。

引用社区网站的内容，使用完整链接：

  • 插件商店：https://zotero-chinese.com/plugins/
  • CSL 商店：https://zotero-chinese.com/styles/
  • 转换器列表：https://zotero-chinese.com/translators/

引用外部网站链接，也使用完整的绝对链接，例如 https://baidu.com/。

链接部分结尾的逗号、句号等点号，不宜纳入链接文本，但整句作为链接文本的情况除外。链接部分系引文、书名、篇名时，两端的引号、书名号不宜纳入链接文本。

链接左右应空一格。

图片 ​

md
![图片描述](../public/logo.png)

提示

所有的图片资源都应放入 assets/images/ 内，尽量以通俗的方式描述图片内容。

如果新增的图片是专用的（例如某个插件的界面），且数量较多，可以为其单独创建一个文件夹来存放。

警告

我们不使用 HTML 语法 <img> 标签来引入图片，请使用标准的 Markdown 语法。

Zotero 的图标资源

我们从 Zotero 源代码中拷贝了一部分常用的图标资源，存放在 assets/icons/ 目录中，使用语法与常规图片相同。

图标较多，可以阅读 assets/icons/README.md 快速找到图标目录的含义。

例如：![Zotero Logo](../assets/icons/z.svg)

Zotero Logo

无序列表和有序列表 ​

md
#### 无序列表

- item 1
  - 更多的列表项
  - 更多的列表项
  - 更多的列表项
- item 2
- item 3

#### 有序列表

1. item 1
2. item 2
3. item 3

表格 ​

使用 GitHub 风格表格：

md
|     居中      |         右对齐 | 左对齐         |
| :-----------: | -------------: | :------------- |
| 居中使用`:-:` | 右对齐使用`-:` | 左对齐使用`:-` |
|       b       |      aaaaaaaaa | aaaa           |
|       c       |           aaaa | a              |

提示

第二行表示对齐方式的 : 不是必须的，当没有时，会默认为居左。

代码 ​

行内代码 ​

md
行内代码效果: `code`

行内代码效果: code

下列内容应设置为行内代码样式：

  • 终端命令的名称或简短片段；
  • 软件包的名称；
  • 文件名、扩展名和文件路径；
  • URL（如用于程序输入和输出）、IP 地址和端口，HTTP 协议的状态码、动词；
  • 上下文讨论程序语言或标记语言时，句子中的属性、元素、类、数据类型、常量、变量、关键词、方法、函数、名称空间的名称及其值（如有）。

行内代码左右应空一格。

块级代码 ​

md
```js
var foo = function (bar) {
  return bar++;
};

console.log(foo(5));
```

三个反引号后跟随代码块语言：md、js、plain（纯文本） 等。

预览：

js
var foo = function (bar) {
  return bar++;
};

console.log(foo(5));

代码块的高级应用

块级代码允许设置行高亮、聚焦、diff 差异等，请参考 Markdown 扩展 - VitePress

徽章 推荐 ​

可以通过徽章来标记文档阅读难度、推荐等。语法如下，可以在正文和标题中使用，但是不能在一级标题（页面标题）中使用。

md
<Badge text="初级" />
<Badge text="中级" />
<Badge text="高级" />
<Badge text="推荐" />

通过 DOI 更新元数据 <Badge text="初级" /> 。
初级中级高级推荐

通过 DOI 更新元数据 初级 。

告示块 ​

信息 ​

md
::: info

这是一个备注

:::

信息

这是一个备注

提示 ​

md
::: tip

这是一个提示

:::

提示

这是一个提示

警告 ​

md
::: warning

这是一个警告

:::

警告

这是一个警告

危险 ​

md
::: danger

这是一个危险

:::

危险

这是一个危险

详情 ​

md
::: details

这是一个折叠可见内容

:::
详细信息

这是一个折叠可见内容

自定义标题 ​

自定义标题

通过在 tip、warning、danger、details 后添加文字，可以自定义块标题，例如：

md
::: tip 自定义标题

通过在 `tip`、`warning`、`danger`、`details` 后添加文字

:::

嵌套显示 ​

支持两级嵌套，第一级的标志使用四个冒号::::，例如：

md
:::: details 嵌套显示

::: tip

这是第二级提示。

:::

::::
嵌套显示

提示

这是第二级提示。

引用 ​

md
这是一段正文文本

> 这是一段引用文本

这是另一段正文文本

这是一段正文文本

这是一段引用文本

这是另一段正文文本

脚注 ​

脚注内容就近放置，以方便阅读源文本。

md
这是一段文本[^1]

[^1]: 这是一个脚注

这是一段文本[1]

提示

除上述文字样式外，不使用 html 语法改变文字样式，仅在特殊情况下使用 html 语法增添文档的趣味性。

文档侧边栏配置 ​

文档侧边栏是指文档左侧导航文档章节结构的模块，移动端是顶部的「菜单」按钮。

当增删页面后，需要修改这部分内容以让增删的页面在侧边栏显示或删除，以方便用户选择访问。如果没有增删页面，这部分配置一般不需要更改。

这部分内容需要在 .vitepress/sidebar.ts 中修改，在 sidebar 常量中，/user-guide/ 对象的值就是「百科全书」的侧边栏。

语法上，每一项都至少需要 text 属性，这是侧边栏的文本。link 属性代表这一项的链接，链接是 markdown 文件的绝对路径，不需要加 .md 后缀。如果存在 items 属性，则这个侧边栏项会变成一个分组。items 的内容是一个侧边栏项的数组。

你可以参考该文件上方的注释了解详细配置选项，参考已有的配置应该可以较为容易地增删侧边栏项。

作者信息配置 ​

你可能有注意到，社区文档每一页地页脚都包含了这一页文档地贡献者和变更历史信息。正常来说，这些贡献者信息都是从 Git 历史中自动生成的，但由于存在「昵称别名」、「邮箱别名」等情况，贡献者信息可能会重复显示。

这种情况下，你可以前往 .vitepress/contributors.ts 中修改贡献者信息以消除别名。它的语法特别简单，你可以参考该文件里已有的内容来修改自己的信息。

此外，你也可以在这个文件内为自己的信息增加链接 links，以让页脚的贡献者名直接链接到你的社交媒体主页或个人主页。

自动化工具 ​

仓库配置了 Prettier + MarkdownLint 来规范文档的格式。建议你安装仓库推荐的 prettier-vscode 插件和 markdownlint-vscode 插件，以实现自动格式化文本。

此外，你还可以使用 NPM 脚本 pnpm lint:fix 来自动修复格式。

致谢 ​

本指南部分内容参考了以下文档：

  1. 少数派编辑部. 少数派风格指南[EB/OL]. 2023. https://manual.sspai.com/rules/style/index.html
  2. 田冬冬, 姚家园. GMT 中文文档贡献指南[EB/OL]. 2023. https://docs.gmt-china.org/latest/contributing/
  3. Vue 团队. VitePress 的 Markdown 扩展[EB/OL]. 2024. https://vitepress.dev/zh/guide/markdown

贡献者

The avatar of contributor named as Northword NorthwordThe avatar of contributor named as jiaojiaodubai jiaojiaodubaiThe avatar of contributor named as l0o0 l0o0

页面历史

  1. 这是一个脚注 ↩︎

本工作以 知识共享 署名-相同方式共享 和 MIT 协议共享

版权所有 © 2020-至今 Zotero 中文社区及其贡献者