Zettlr

<h1 align="center"> <a href="https://github.com/Zettlr/Zettlr"> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/e05c036a-1186-442d-a7ab-c8096060c974.png" alt="Zettlr"/> </a> Zettlr [ˈset·lər] </h1> 您的一站式出版工作台。 <a href="https://doi.org/10.5281/zenodo.2580173"> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/8a5c84fb-e805-4836-a5cb-0ac4ccd72568.svg" alt="DOI"> </a> <a href="https://www.gnu.org/licenses/gpl-3.0"> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/73c27eae-e3e0-4d4e-ba10-01b594c2be56.svg" alt="许可证：GNU GPL v3"> </a> <a href="https://www.zettlr.com/download"> <img alt="GitHub 标签（最新日期）" src="https://yellow-cdn.veclightyear.com/0a4dffa0/7cfb6015-75de-4f80-b2ef-53fcb7918204.svg?label=latest"> </a> <img alt="GitHub 所有版本" src="https://yellow-cdn.veclightyear.com/0a4dffa0/afa5c855-3425-4172-8d64-9de53d81dd1a.svg"> <img alt="单元测试 / Lint" src="https://yellow-cdn.veclightyear.com/0a4dffa0/5904768d-288d-448f-a426-02f03ba2a7f6.svg"> <img alt="构建" src="https://yellow-cdn.veclightyear.com/0a4dffa0/59e342ef-fa53-4e10-9920-116efb5c6689.svg"> <a href="https://www.zettlr.com/" target="_blank">主页</a> | <a href="https://www.zettlr.com/download">下载</a> | <a href="https://docs.zettlr.com/" target="_blank">文档</a> | <a rel="me" href="https://fosstodon.org/@zettlr" target="_blank">Mastodon</a> | <a href="https://discord.gg/PcfS3DM9Xj" target="_blank">Discord</a> | <a href="#contributing">贡献</a> | <a href="https://www.patreon.com/zettlr" target="_blank">支持我们</a>

Zettlr 为您的文本带来简洁。开放式写作适应您的风格。快速信息检索找到对您重要的内容。多功能导出使您能够适应雇主或学校使用的任何出版流程。

专注于对您重要的事情。

发表，而非沉沦。

在我们的网站上了解更多。

特性

您的笔记属于您：Zettlr 以隐私为先
引用变得简单：与您喜爱的参考文献管理器（Zotero、JabRef 等）紧密集成，并不断扩展
提供十多种语言版本
在专业环境中起草您的出版物，支持 LaTeX 和 Word 模板
使用 Pandoc、LaTeX 和 Textbundle 进行简单而美观的导出
代码片段允许您自动插入常用代码
主题、深色模式和自定义 CSS 的完全灵活性
支持多种语言的代码高亮
支持最先进的知识管理技术（卡片盒笔记法）
强大的全文搜索帮助您随时随地找到任何内容

……最棒的是：Zettlr 是自由开源软件（FOSS）！

安装

要安装 Zettlr，只需下载适用于您操作系统的最新版本。目前支持 macOS、Windows 和大多数 Linux 发行版（通过 Debian 和 Fedora 软件包以及 AppImage）。

在我们的网站和 GitHub 上，我们提供了一套适用于最常见使用场景的安装程序。我们提供 64 位安装程序以及 ARM 系统安装程序（在 macOS 生态系统中称为"Apple Silicon"）。不支持 32 位。我们直接提供以下二进制文件：

Windows（x64）
macOS（Intel 和 Apple Silicon）
Debian 和 Fedora（x64 和 ARM）
AppImage（x64 和 ARM）

感谢我们的社区，我们还可以为您提供多种其他安装方式：

所有其他 Electron 支持的平台也受支持，但您需要自行构建应用程序才能使用。

请考虑成为赞助人或一次性捐赠！

入门

安装 Zettlr 后，前往我们的文档了解 Zettlr。如果您更喜欢直接上手使用软件，请参阅快速入门指南。

使用深色主题的 Zettlr 中央窗口

贡献

作为一个开源应用程序，Zettlr 始终欢迎来自社区的贡献。**您不需要懂得编写代码就能提供帮助！**在我们的贡献指南中可以找到您可以提供帮助的所有领域的完整概述。在这里，我们介绍了两个最需要帮助的主要领域：翻译和代码贡献。

翻译

开发团队维护英语和德语翻译，但缺乏对其他语言的充分了解。所有其他可用的翻译都是由我们的社区创建的。

Zettlr 的翻译使用 gettext 系统。这意味着翻译保存在 static/lang 目录中的 PO 文件中。要更新翻译，只需下载相应的语言文件并进行编辑。您可以使用简单的文本编辑器编辑 PO 文件，但如果您更喜欢更舒适的图形化编辑器，有很多可供选择。一个不错的选择是开源编辑器 POedit。

一旦您对修改感到满意，请在此处打开一个更新相应文件的拉取请求。GitHub 创建了一个很棒的如何打开拉取请求的指南。

贡献代码

Zettlr 是一个基于 Electron 的应用程序，因此要开始开发，您需要在电脑上安装以下内容：

NodeJS。确保至少是 Node 20（lts/iron）。要测试您的版本，运行 node -v。
Yarn。这是项目的包管理器，因为我们不提交 package-lock.json 文件，而且许多命令需要 yarn。您可以使用 npm install -g yarn 或 Homebrew（如果您使用 macOS）全局安装它。
在 Windows 上，我们建议安装 Windows 子系统 Linux (WSL)，这将使接下来的许多步骤更容易。
一些命令行工具，各种脚本需要这些工具来运行开发构建：
- cURL（Pandoc 下载脚本需要）
- unzip（Pandoc 下载脚本需要）
- jq（i18n 脚本需要）
适用于您操作系统的适当构建工具链，因为 Zettlr 需要一些必须在运行应用程序之前编译的原生 C++ 模块：
- macOS：在 macOS 上，通过 xcode-select --install 安装 XCode 命令行工具就足够了
- Windows：在 Windows 上，您需要免费的 Visual Studio 开发工具，其中包含所需的工具
- Linux：在 Linux 上，有各种兼容的工具链可用，有时它们已经预先安装。请参阅您发行版的手册以获取更多信息。

然后，只需克隆仓库并在本地计算机上安装依赖项：

$ git clone https://github.com/Zettlr/Zettlr.git
$ cd Zettlr
$ yarn install --immutable

--immutable 标志确保 yarn 会坚持使用 yarn.lock 中列出的版本，而不会尝试更新它们。

在开发过程中，热模块重载（HMR）处于活动状态，因此您可以轻松编辑渲染器的代码，并在 electron-forge 编译更改后按 F5。您可以保持开发者工具打开，以查看 HMR 何时完成加载您的更改。

我需要了解什么才能贡献代码？

为了提供代码，您应该对以下主题和/或手册有基本的了解（按重要性降序排列）：

[!TIP] 查看下面的"目录结构"部分，了解 Zettlr 的具体工作方式。

开发命令

本节列出了在应用程序开发过程中可以使用的所有可用命令。这些命令在 package.json 中定义，可以通过在命令前加上 yarn 来从命令行运行。请在仓库的基本目录中运行它们。

`start`

使用此命令可以无忧无虑地测试您对应用程序所做的任何更改。此命令将启动应用程序，但会提供自定义配置和自定义目录。因此，它不会触及常规 Zettlr 安装使用的任何文件。

第一次运行此命令时，传递 --clean 标志以将一些测试文件复制到您的 ./resources 目录，在项目根目录中创建 test-config.yml，并使用这个干净的配置启动应用程序。然后，您可以根据自己的喜好调整 test-config.yml（这样，某些您通常总是需要设置的设置就可以预先设置，而无需打开首选项）。

每当您想将测试目录重置为初始状态（或者您删除了目录，或重新克隆了整个项目）时，请向命令传递 --clean 标志以创建或重置目录。如果您在 test-config.yml 中更改了某些内容，这也是必要的。

如果您想阻止创建配置文件（例如，模拟首次启动体验），您可以向此命令传递 --no-config 标志。

您还可以向此命令传递其他命令行开关，如 --clear-cache。它们将被传递给子进程。

[!WARNING] 注意：在首次运行命令之前，您必须使用 --clean 标志运行它以首先创建目录！

另外，请查看我们的完整开发文档。

`package`

打包应用程序，但不将其捆绑成安装程序。没有任何后缀时，此命令将为您当前的平台和架构打包应用程序。要创建特定的包（可能需要在相应的平台上运行），可以使用以下后缀：

package:mac-x64（基于 Intel 的 Mac）
package:mac-arm（基于 Apple Silicon 的 Mac）
package:win-x64（基于 Intel 的 Windows）
package:linux-x64（基于 Intel 的 Linux）
package:linux-arm（基于 ARM 的 Linux）

生成的应用程序包存储在 ./out 中。

[!IMPORTANT] 此命令将跳过类型检查以加快构建速度，因此我们建议在打包之前运行 lint 以确保没有错误。

`release:{platform-arch}`

打包应用程序，然后将其捆绑成相应平台和架构的安装程序。要创建这样的捆绑包（可能需要在相应的平台上运行），{platform-arch} 需要是以下值之一：

release:mac-x64（基于 Intel 的 Mac）
release:mac-arm（基于 Apple Silicon 的 Mac）
release:win-x64（基于 Intel 的 Windows）
release:linux-x64（基于 Intel 的 Linux）
release:linux-arm（基于 ARM 的 Linux）

生成的安装包存储在 ./release 中。

[!NOTE] 虽然您可以直接使用 package 命令为您的平台打包而不需要任何后缀，但在创建发布捆绑包时，您需要指定平台和架构，因为 electron-builder 否则会在 app.asar 中包含开发依赖项，导致应用程序变得臃肿。

`csl:refresh`

这会下载应用程序附带的引文样式语言（CSL）文件，并将它们分别放置在 static/csl-locales 和 static/csl-styles 目录中。

[!NOTE] 该命令用于仓库中不时运行的自动化工作流，以执行此操作。请勿将更新后的文件提交到仓库。相反，每当你执行 git fetch 时，都会下载更新后的文件。

`lint`

运行 ESLint。像 Visual Studio Code 这样的应用程序会自动在后台对你打开的文件运行 ESLint。此命令会在整个代码库中运行它们。请确保在提交拉取请求之前运行此命令。

[!NOTE] 该命令将在每个拉取请求上自动运行，以检查你的代码是否存在不一致之处。

`shortcut:install`

在你的应用程序中创建一个 .desktop 文件，使你能够快速启动从源代码编译的应用程序。这需要 Linux 系统。要使用新的更改，只需同步仓库，再次运行 package，然后就可以使用了。

[!WARNING] 我们提供此命令是为了方便。除非你知道自己在做什么，否则不应直接运行从开发分支的 HEAD 提交编译的代码。然而，在某些情况下，如果你知道可能会出现什么问题并能采取适当的预防措施，此命令可能会有用。

`shortcut:uninstall`

删除由 shortcut:install 创建的 .desktop 文件。

[!NOTE] 每次重新编译二进制文件时，你不必卸载并重新安装快捷方式。只需确保在重新编译之前关闭 Zettlr。只有在模板（在 scripts/assets/zettlr-dev.desktop 中）发生变化时，你才需要重新安装快捷方式。

`test`

这会运行 ./test 目录中的单元测试。请确保在提交拉取请求之前运行此命令，因为每次你向拉取请求提交内容时都会运行此命令，这样你就可以确保你的更改不会破坏任何测试，从而使整个拉取请求过程更加顺利。

`test-gui`

参见 start。

[!IMPORTANT] 此命令已被弃用，只是 start 的别名。请使用 start 代替。

目录结构

Zettlr 是一个成熟的应用程序，在其开发过程中积累了数百个目录。由于没有任何指导就很难为应用程序做出贡献，我们编写了一个简短的目录描述，说明它们之间的相互关系。

.
├── out                         # 运行任何 `package` 命令后包含未打包的二进制文件
├── release                     # 运行任何 `release` 命令后包含可分发文件
├── resources                   # 通用资源文件
│   ├── NSIS                    # Windows 安装程序位图
│   ├── icons                   # 各种图标格式
│   ├── screenshots             # 包含主要截图
├── scripts                     # 构建过程和 CI 管道中使用的脚本
│   ├── assets                  # 脚本文件的资源
│   └── test-gui                # 用于 `test-gui` 命令的完整文件树
├── source                      # 这是实际的源文件树
│   ├── app                     # 主进程组件
│   │   ├── service-providers   # 处理大部分业务逻辑的服务提供者
│   │   └── util                # 主进程的实用函数
│   ├── common                  # 各种渲染进程之间共享的文件
│   │   ├── img                 # 在各处使用的图像
│   │   ├── modules             # 共享模块
│   │   │   ├── markdown-editor # 主 Markdown 编辑器
│   │   │   ├── markdown-utils  # MD 实用工具，如 md2html 转换器
│   │   │   ├── preload         # Electron 预加载文件
│   │   │   └── window-register # 每个渲染器在设置期间运行
│   │   ├── util                # 通用实用函数
│   │   └── vue                 # 共享 Vue 组件
│   ├── pinia                   # 渲染器状态管理
│   ├── types                   # 仅类型目录；已弃用
│   ├── win-about               # 关于对话框窗口
│   ├── win-assets              # 资源管理器
│   ├── win-error               # 错误窗口
│   ├── win-log-viewer          # 日志查看器
│   ├── win-main                # 主窗口
│   ├── win-paste-image         # 粘贴图像对话框
│   ├── win-preferences         # 首选项窗口
│   ├── win-print               # 打印预览
│   ├── win-project-properties  # 项目属性
│   ├── win-splash-screen       # 启动画面
│   ├── win-stats               # 统计窗口
│   ├── win-tag-manager         # 标签管理器
│   └── win-update              # 更新程序
├── static                      # 包含静态资源
│   ├── csl-locales             # CSL 语言环境文件
│   ├── csl-styles              # CSL 样式
│   ├── defaults                # 默认的默认值/Pandoc 配置文件
│   ├── dict                    # 随应用程序一起提供的字典
│   ├── fonts                   # 随应用程序一起提供的字体
│   ├── lang                    # 语言和 i18n 相关文件
│   ├── lua-filter              # 默认 Lua 过滤器
│   └── tutorial                # 各种语言的教程文件
└── test                        # 单元测试

模块和服务提供者的区别

你会注意到 Zettlr 同时包含"模块"和"服务提供者"。两者的区别很简单：服务提供者在主进程中运行，完全自主，同时为整个应用程序提供功能。另一方面，模块提供必须由用户操作触发的功能（例如导出器和导入器）。

应用程序生命周期

每当你运行 Zettlr 时，将执行以下步骤：

执行 source/main.ts
环境检查（source/app/lifecycle.ts::bootApplication）
启动服务提供者（source/app/lifecycle.ts::bootApplication）
启动主应用程序（source/main/zettlr.ts）
加载文件树和文档
显示主窗口

当你关闭应用程序时，将运行以下步骤：

关闭除主窗口之外的所有窗口
尝试关闭主窗口
关闭主应用程序（source/main/zettlr.ts::shutdown）
关闭服务提供者（source/app/lifecycle.ts::shutdownApplication）
退出应用程序

在应用程序开发期间（yarn start 和 yarn test-gui），将运行以下步骤：

Electron forge 将分别为主进程和每个渲染进程编译代码（因为这些是独立的进程），使用 TypeScript 和 webpack 进行编译和转译。
Electron forge 将该代码放入 .webpack 目录，用适当的入口点替换你可以在窗口管理器的"create"方法中找到的常量。
Electron forge 将启动几个开发服务器以提供热模块重载（HMR），然后实际启动应用程序。

每当构建应用程序时，将运行以下步骤：

Electron forge 将执行上述步骤 1 和 2，但不是运行应用程序，而是将生成的代码打包成一个功能性的应用程序包。
Electron builder 然后将这些预构建的包装入特定平台的安装程序（DMG 文件、Windows 安装程序或 Linux 包）。

Electron forge 将把打包的应用程序放入 ./out 目录，而 Electron builder 将把安装程序放入 ./release 目录。

命令行开关

Zettlr 二进制文件具有一些命令行开关，你可以将其用于不同目的。

`--launch-minimized`

此 CLI 标志将指示 Zettlr 在启动时不显示主窗口。这对创建自动启动项很有用。在这种情况下，在系统启动时使用此标志启动 Zettlr 将确保你只能在托盘中看到其图标。由于这意味着需要在以这种方式启动应用程序时将其运行在托盘栏或通知区域中，它会自动将相应的设置 system.leaveAppRunning 设为 true。

[!注意] 此标志对不支持在托盘栏或通知区域显示图标的 Linux 系统无效。

`--clear-cache`

这将指示文件系统抽象层在启动时完全清除其缓存。这可用于缓解与代码库变更相关的问题。为确保与缓存中存储的信息的任何更改兼容，当 config.json 中的版本字段与 package.json 中的不匹配时，缓存也会自动清除。这意味着，只要你没有在 test-config.yml 中显式设置 version 字段，每次运行 yarn test-gui 时缓存都会被清除。

[!提示] 如果你只是想随意清除缓存以进行故障排除，你也可以通过选择"帮助"菜单中的相应菜单项来清除缓存，这样可以避免你处理任何技术性问题。

`--data-dir=路径`

使用此开关指定自定义数据目录，该目录存放你的配置文件。如果不使用此开关，数据目录默认为 %AppData%/Zettlr（在 Windows 10 及更高版本上），~/.config/Zettlr（在 Linux 上），或 ~/Library/Application Support/Zettlr（在 macOS 上）。路径可以是绝对路径或相对路径。相对路径的基准将是二进制文件的目录（运行打包应用程序时）或仓库根目录（运行未打包的应用程序时）。如有必要，记得转义空格或用引号括起路径。在这种情况下，~ 字符不会被展开为表示主目录，所以如果需要，请确保传递完整的主目录路径。由于 Electron 的一个小 bug，会在默认数据目录中创建一个空的 Dictionaries 子目录，但这不会影响功能。

`--disable-hardware-acceleration`

此开关会导致 Zettlr 禁用硬件加速，这在某些设置中可能是必要的。有关为什么添加此标志的更多信息，请参见问题 #2127。

VSCode 扩展推荐

本仓库利用了 Visual Studio Code 的推荐扩展功能。这意味着：如果你使用 VS Code 并首次打开仓库，VS Code 会告诉你仓库推荐安装一些扩展。如果你使用 Zettlr，这些扩展是推荐的，它们将使贡献变得更加容易。推荐在 .vscode/extensions.json 文件中指定。

由于安装扩展有时是个人喜好的问题，我们在该文件中为每个推荐的扩展添加了简短描述，解释为什么我们推荐它。这样你可以自行决定是否要安装这些扩展（例如，如果你不处理仓库中提供的 SVG 文件，SVG 扩展就不是必要的）。

如果你选择不一次性安装所有推荐的扩展（我们建议这样做），VS Code 会在扩展侧边栏中显示推荐，这样你就可以先决定安装哪些扩展，然后手动安装你想要的扩展。