5 篇标记为“网站”的文章

Electron 网站有了一个新的搜索引擎，可以为 API 文档、教程、Electron 相关的 npm 包等提供即时结果。

学习像 Electron 这样的新技术或框架可能令人望而却步。 一旦你过了快速入门阶段，学习最佳实践、找到正确的 API 或发现可以帮助你构建梦想应用程序的工具可能会很困难。 我们希望 Electron 网站成为一个更好的工具，可以让你更快、更轻松地找到构建应用程序所需的资源。

访问 electronjs.org 上的任何页面，你都会在页面顶部找到新的搜索输入框。

搜索引擎​

当我们最初开始向网站添加搜索功能时，我们使用 GraphQL 作为后端推出了自己的搜索引擎。 GraphQL 很有趣，搜索引擎的性能也很好，但我们很快意识到构建搜索引擎并非易事。 诸如多字搜索和错字检测之类的事情需要大量工作才能做好。 我们决定使用现有的搜索解决方案：Algolia，而不是重新发明轮子。

Algolia 是一项托管搜索服务，已迅速成为 React、Vue、Bootstrap、Yarn 等流行的开源项目以及 许多其他项目的首选搜索引擎。

以下是一些使 Algolia 非常适合 Electron 项目的功能

• InstantSearch.js 可在你键入时提供结果，通常约为 1 毫秒。
• 错字容错意味着即使你输入 widnow 仍然会获得结果。
• 高级查询语法 启用 "精确引用匹配" 和 -排除。
• API 客户端是开源的，并且有完善的文档。
• 分析告诉我们人们搜索最多的内容，以及他们搜索但未找到的内容。 这将为我们提供有关如何改进 Electron 文档的宝贵见解。
• Algolia 对 开源项目免费。

API 文档​

有时你知道你想要完成什么，但你不知道如何去做。 Electron 有超过 750 种 API 方法、事件和属性。 没有人可以轻松记住所有这些，但是计算机擅长此操作。 使用 Electron 的 JSON API 文档，我们将所有这些数据索引到 Algolia 中，现在你可以轻松找到你正在寻找的确切 API。

尝试调整窗口大小？ 搜索 resize 并直接跳转到你所需的方法。

教程​

Electron 有一个不断增长的教程集合，以补充其 API 文档。 现在，你可以更轻松地找到关于给定主题的教程，以及相关的 API 文档。

正在寻找安全最佳实践？ 搜索 security。

npm 包​

现在 npm 注册表中有超过 700,000 个包，并且并非总是很容易找到你需要的包。 为了更容易发现这些模块，我们创建了 electron-npm-packages，它是注册表中专门为与 Electron 一起使用的 3400 多个模块的集合。

Libraries.io 的人们创建了 SourceRank，这是一个基于代码、社区、文档和使用等指标的组合来为软件项目评分的系统。 我们创建了一个 sourceranks 模块，其中包括 npm 注册表中每个模块的分数，我们使用这些分数对包结果进行排序。

想要 Electron 内置 IPC 模块的替代方案？ 搜索 is:package ipc。

Electron 应用程序​

使用 Algolia 索引数据很容易，所以我们从 electron/apps 中添加了现有的应用程序列表。

尝试搜索 music 或 homebrew。

筛选结果​

如果你以前使用过 GitHub 的 代码搜索，你可能知道它的冒号分隔的键值过滤器，如 extension:js 或 user:defunkt。 我们认为这种过滤技术非常强大，因此我们在 Electron 的搜索中添加了 is: 关键字，它让你过滤结果以仅显示一种类型

• is:api 缩略图
• is:tutorial 安全
• is:package ipc
• is:app graphql

键盘导航​

人们喜欢键盘快捷键！ 无需将手指从键盘上移开即可使用新的搜索

• / 聚焦搜索输入框
• esc 聚焦搜索输入框并清除它
• 向下 移动到下一个结果
• 向上 移动到上一个结果或搜索输入框
• 输入 打开结果

我们还开源了 模块，它启用了这种键盘交互。 它专为与 Algolia InstantSearch 一起使用而设计，但已通用化以实现与不同搜索实现的兼容性。

我们需要你的反馈​

如果你在使用新搜索工具时遇到任何问题，我们希望听到你的意见！

提交反馈的最佳方式是在 GitHub 上的相应存储库中提交问题

• electron/electronjs.org 是 Electron 网站。 如果你不知道在哪里提交问题，这是你的最佳选择。
• electron/algolia-indices 是编译所有可搜索 Electron 数据的地方。
• electron/search-with-your-keyboard 使搜索界面可以通过键盘导航。
• algolia/instantsearch.js 是浏览器端客户端，它支持键入时查找搜索。
• algolia/algoliasearch-client-javascript 是用于将数据上传到 Algolia 服务器的 Node.js 客户端。

感谢​

特别感谢 Emily Jordan 和 Vanessa Yuen 构建这些新的搜索功能，感谢 Libraries.io 提供 SourceRank 分数，以及感谢 Algolia 团队帮助我们入门。 🍹

自从新的国际化 Electron 网站发布以来，我们一直在努力使非英语世界的开发人员更容易获得 Electron 开发体验。

所以我们在这里提供一些激动人心的 i18n 更新！

🌐 语言切换​

你知道吗，许多阅读翻译文档的人经常将其与原始英文文档进行交叉引用？ 他们这样做是为了熟悉英文文档，并避免过时或不准确的翻译，这是国际化文档的一个警告。

为了使交叉引用英文文档更容易，我们最近发布了一项功能，该功能允许你在英文和你在网站上查看的任何语言之间无缝切换 Electron 文档的一部分。 只要你在网站上选择了非英语区域设置，语言切换就会显示。

⚡️ 快速访问翻译页面​

在阅读文档时注意到错字或不正确的翻译？ 你不再需要登录 Crowdin、选择你的区域设置、找到你想要修复的文件等等。 相反，你可以向下滚动到所述文档的底部，然后单击“翻译此文档”（或你的语言中的等效项）。 瞧！ 你将直接进入 Crowdin 翻译页面。 现在应用你的翻译魔法！

📈 一些统计数据​

自从我们公开了 Electron 文档 i18n 工作以来，我们看到了来自世界各地的 Electron 社区成员的翻译贡献的巨大增长。 迄今为止，我们有来自 1,066 位社区翻译人员的 1,719,029 个翻译字符串，并支持 25 种语言。

这是一个有趣的图表，显示了如果保留现有速度（基于撰写时过去 14 天的项目活动），将项目翻译成每种语言所需的大概时间。

📃 翻译人员调查​

我们要向所有为帮助改进 Electron 贡献时间的人表示衷心的感谢 ❤️！ 为了正确地感谢我们的翻译人员社区的辛勤工作，我们创建了一个调查，以收集有关我们的翻译人员的一些信息（即他们的 Crowdin 和 Github 用户名之间的映射）。

如果你是我们出色的翻译人员之一，请花几分钟填写此表：https://goo.gl/forms/b46sjdcHmlpV0GKT2。

🙌 Node 的国际化工作​

由于 Electron 的 i18n 计划的成功，Node.js 决定效仿我们使用的模式来改进他们的 i18n 工作！ 🎉 Node.js i18n 计划现已启动并获得巨大动力，但你仍然可以阅读有关早期提案及其背后原因的信息此处。

🔦 贡献指南​

如果你有兴趣加入我们，让 Electron 更具国际友好性，我们提供了一个方便的贡献指南来帮助你入门。 国际化快乐！ 📚

Electron 在 electronjs.org 上有一个新的网站！ 我们已经用 Node.js 网络服务器替换了我们的静态 Jekyll 网站，这使我们能够灵活地对网站进行国际化，并为更多激动人心的新功能铺平道路。

🌍 翻译​

我们已经开始了网站国际化的过程，目的是让全球开发人员更容易获得 Electron 应用程序开发。 我们正在使用一个名为 Crowdin 的本地化平台，该平台与 GitHub 集成，并在内容被翻译成不同的语言时自动打开和更新拉取请求。

尽管我们一直在默默地开展这项工作，但已有超过 75 位 Electron 社区成员有机地发现了该项目并加入了将网站国际化并将 Electron 的文档翻译成 20 多种语言的工作。 我们看到了来自世界各地的人们的每日贡献，法语、越南语、印度尼西亚语和中文等语言的翻译处于领先地位。

要选择你的语言并查看翻译进度，请访问 electronjs.org/languages

如果你是多语种，并且有兴趣帮助翻译 Electron 的文档和网站，请访问 electron/electron-i18n 存储库，或直接在 Crowdin 上进行翻译，你可以在其中使用你的 GitHub 帐户登录。

Crowdin 上目前为 Electron 项目启用了 21 种语言。 添加对更多语言的支持很容易，因此如果你有兴趣帮助翻译但没有看到你的语言列出，请告诉我们，我们将启用它。

原始翻译文档​

如果您喜欢阅读原始 Markdown 文件中的文档，现在您可以用任何语言进行阅读

git clone https://github.com/electron/electron-i18n
ls electron-i18n/content

应用页面​

从今天开始，任何 Electron 应用都可以轻松地在 Electron 网站上拥有自己的页面。 例如，查看 Etcher、1Clipboard 或 GraphQL Playground，此处显示的是该网站的日文版本

有很多很棒的 Electron 应用，但它们并不总是容易找到，而且并非每个开发者都有时间和资源来构建一个合适的网站来营销和分发他们的应用。

仅使用一个 PNG 图标文件和少量应用元数据，我们就能收集到关于给定应用的很多信息。 通过从 GitHub 收集的数据，应用页面现在可以显示屏幕截图、下载链接、版本、发行说明以及每个具有公共仓库的应用的 README 文件。 使用从每个应用的图标中提取的调色板，我们可以产生 大胆且易于访问的颜色，从而为每个应用页面提供一些视觉区分。

应用索引页面 现在还具有类别和关键字过滤器，可以查找有趣的应用程序，例如 GraphQL GUI 和 p2p 工具。

如果您有一个 Electron 应用想要在网站上展示，请在 electron/electron-apps 仓库上打开一个 pull request。

使用 Homebrew 一行安装​

macOS 的 Homebrew 包管理器有一个名为 cask 的子命令，可以轻松地使用终端中的单个命令安装桌面应用程序，例如 brew cask install atom。

我们已经开始收集流行的 Electron 应用的 Homebrew cask 名称，现在在每个具有 cask 的应用页面上显示安装命令（对于 macOS 访问者）

要查看所有具有 Homebrew cask 名称的应用，请访问 electronjs.org/apps?q=homebrew。 如果您知道其他尚未编入索引的具有 cask 的应用，请添加它们！

🌐 新域名​

我们已将该网站从 electron.atom.io 迁移到新域名：electronjs.org。

Electron 项目诞生于 Atom 内部，Atom 是 GitHub 基于 Web 技术构建的开源文本编辑器。 Electron 最初名为 atom-shell。 Atom 是第一个使用它的应用，但人们很快意识到，这种神奇的 Chromium + Node 运行时可以用于各种不同的应用。 当 Microsoft 和 Slack 等公司开始使用 atom-shell 时，很明显该项目需要一个新名称。

因此，“Electron”诞生了。 2016 年初，GitHub 组建了一个新团队，专门负责 Electron 的开发和维护，与 Atom 分开。 从那时起，Electron 已被成千上万的应用开发者采用，并且现在被许多大型公司所依赖，其中许多公司都有自己的 Electron 团队。

支持 GitHub 的 Electron 项目（如 Atom 和 GitHub Desktop）仍然是我们团队的首要任务，但通过迁移到新域名，我们希望有助于澄清 Atom 和 Electron 之间的技术区别。

🐢🚀 Node.js 无处不在​

之前的 Electron 网站是使用 Jekyll 构建的，Jekyll 是流行的基于 Ruby 的静态网站生成器。 Jekyll 是构建静态网站的好工具，但该网站已经开始超出它的范围。 我们想要更多的动态功能，例如正确的重定向和动态内容渲染，因此 Node.js 服务器是显而易见的选择。

Electron 生态系统包括使用多种不同编程语言（从 Python 到 C++ 再到 Bash）编写组件的项目。 但是 JavaScript 是 Electron 的基础，并且是我们社区中使用最多的语言。

通过将网站从 Ruby 迁移到 Node.js，我们旨在降低希望为网站做出贡献的人员的入门门槛。

⚡️ 更轻松的开源参与​

如果在您的系统上安装了 Node.js（8 或更高版本）和 git，您可以轻松地在本地运行该网站

git clone https://github.com/electron/electronjs.org
cd electronjs.org
npm install
npm run dev

新网站托管在 Heroku 上。 我们使用部署管道和 Review Apps 功能，该功能会自动为每个 pull request 创建一个正在运行的应用副本。 这使得审阅者可以轻松地在网站的实时副本上查看 pull request 的实际效果。

🙏 感谢贡献者​

我们要特别感谢世界各地所有贡献自己的时间和精力来帮助改进 Electron 的人们。 开源社区的热情极大地帮助了 Electron 的成功。 谢谢！

今天，我们宣布对 Electron 的文档进行一些改进。 每个新版本现在都包含一个 JSON 文件，该文件详细描述了 Electron 的所有公共 API。 我们创建此文件是为了使开发者能够以有趣的新方式使用 Electron 的 API 文档。

模式概述​

每个 API 都是一个对象，具有名称、描述、类型等属性。 诸如 BrowserWindow 和 Menu 之类的类具有描述其实例方法、实例属性、实例事件等的其他属性。

这是描述 BrowserWindow 类的模式摘录

{
  name: 'BrowserWindow',
  description: 'Create and control browser windows.',
  process: {
    main: true,
    renderer: false
  },
  type: 'Class',
  instanceName: 'win',
  slug: 'browser-window',
  websiteUrl: 'https://electron.js.cn/docs/api/browser-window',
  repoUrl: 'https://github.com/electron/electron/blob/v1.4.0/docs/api/browser-window.md',
  staticMethods: [...],
  instanceMethods: [...],
  instanceProperties: [...],
  instanceEvents: [...]
}

这是一个方法描述的示例，在本例中是 apis.BrowserWindow.instanceMethods.setMaximumSize 实例方法

{
  name: 'setMaximumSize',
  signature: '(width, height)',
  description: 'Sets the maximum size of window to width and height.',
  parameters: [{
    name: 'width',
    type: 'Integer'
  }, {
    name: 'height',
    type: 'Integer'
  }]
}

使用新数据​

为了方便开发者在其项目中使用此结构化数据，我们创建了 electron-docs-api，这是一个小的 npm 包，每当有新的 Electron 版本发布时，它会自动发布。

npm install electron-api-docs --save

为了立即获得满足，请在您的 Node.js REPL 中试用该模块

npm i -g trymodule && trymodule electron-api-docs=apis

数据的收集方式​

Electron 的 API 文档遵循 Electron 编码风格 和 Electron 风格指南，因此可以对其内容进行编程解析。

electron-docs-linter 是 electron/electron 仓库的一个新的开发依赖项。 它是一个命令行工具，可以检查所有 markdown 文件并强制执行风格指南的规则。 如果发现错误，则会列出这些错误并停止发布过程。 如果 API 文档有效，则会创建 electron-json.api 文件并 作为 Electron 版本的一部分上传到 GitHub。

标准 Javascript 和标准 Markdown​

今年早些时候，Electron 的代码库已更新为对所有 JavaScript 使用 standard linter。 Standard 的 README 总结了此选择背后的原因

采用标准样式意味着将代码清晰度和社区惯例的重要性置于个人风格之上。 这对于 100% 的项目和开发文化可能没有意义，但是开源对于新手来说可能是一个充满敌意的地方。 建立清晰的自动化贡献者期望可以使项目更健康。

我们最近还创建了 standard-markdown 来验证我们文档中的所有 JavaScript 代码段是否有效并与代码库本身的样式一致。

这些工具一起帮助我们使用持续集成 (CI) 自动查找 pull request 中的错误。 这减轻了人工进行代码审查的负担，并使我们对文档的准确性更有信心。

社区力量​

Electron 的文档在不断改进，我们感谢我们出色的开源社区。 截至撰写本文时，已有近 300 人为文档做出了贡献。

我们很高兴看到人们如何使用这种新的结构化数据。 可能的用途包括

• 改进 https://electron.js.cn/docs/
• TypeScript 定义文件，用于在使用 TypeScript 的项目中进行更精简的 Electron 开发。
• 适用于 Dash.app 和 devdocs.io 等工具的可搜索离线文档

本周，我们已将 Electron 的文档放在 electronjs.org 上。 您可以访问 /docs/latest 以获取最新的文档集。 我们还将保留旧文档的版本，因此您可以访问 /docs/vX.XX.X 以获取与您使用的版本相关的文档。

您可以访问 /docs 以查看哪些版本可用，或者访问 /docs/all 以在一个页面上查看最新版本的文档（非常适合 cmd + f 搜索）。

如果您想为文档内容做出贡献，您可以在 Electron 仓库 中进行，该仓库是提取文档的来源。 我们为每个小版本提取它们，并将它们添加到 Electron 网站仓库，该仓库是使用 Jekyll 创建的。

如果您有兴趣了解有关我们如何将文档从一个仓库提取到另一个仓库的更多信息，请继续阅读下文。 否则，请享用 文档！

技术细节​

我们将文档按原样保留在 Electron 核心仓库中。 这意味着 electron/electron 将始终具有最新版本的文档。 发布新版本的 Electron 时，我们会将它们复制到 Electron 网站仓库 electron/electronjs.org 上。

script/docs​

为了获取文档，我们运行一个 脚本，该脚本具有命令行界面 script/docs vX.XX.X，带或不带 --latest 选项（取决于您导入的版本是否为最新版本）。 我们的 用于获取文档的脚本 使用了一些有趣的 Node 模块

• nugget 用于 获取发行版 tarball 并将其保存到临时目录。
• gunzip-maybe 用于 解压缩 tarball。
• tar-fs 用于 仅流式传输 tarball 中的 /docs 目录 和 过滤和处理文件（在 through2 的帮助下），以便它们与我们的 Jekyll 网站良好配合（下文将详细介绍）。

测试 帮助我们了解所有位和片段是否按预期着陆。

Jekyll​

Electron 网站是一个 Jekyll 网站，我们使用 Collections 功能来处理文档，其结构如下所示

electron.atom.io
└── _docs
    ├── latest
    ├── v0.27.0
    ├── v0.26.0
    ├── so on
    └── so forth

Front matter​

为了使 Jekyll 渲染每个页面，它至少需要空的 front matter。 我们将在所有页面上使用 front matter，因此在流式传输 /docs 目录时，我们会检查文件是否为 README.md 文件（在这种情况下，它会收到一个 front matter 配置），或者是否为带有 markdown 扩展名的任何其他文件（在这种情况下，它会收到略有不同的 front matter）。

每个页面都收到以下 front matter 变量集

---
version: v0.27.0
category: Tutorial
title: 'Quick Start'
source_url: 'https://github.com/electron/electron/blob/master/docs/tutorial/quick-start.md'
---

README.md 获得一个额外的 permalink，因此其 URL 具有 index.html 的公共根目录，而不是尴尬的 /readme/。

permalink: /docs/v0.27.0/index.html

配置和重定向​

在站点的 _config.yml 文件中，每次在获取文档时使用 --latest 标志时，都会设置一个变量 latest_version。 我们还添加了已添加到站点的所有版本的列表，以及我们希望为整个文档集合使用的 permalink。

latest_version: v0.27.0
available_versions:
  - v0.27.0
collections:
  docs: { output: true, permalink: '/docs/:path/' }

我们站点根目录中的文件 latest.md 是空的，除了此 front matter 之外，它允许用户通过访问此 URL electron.atom.io/docs/latest 来查看最新版本文档的索引（也称为 README），而不是专门使用最新版本号（尽管您也可以这样做）。

---
permalink: /docs/latest/
redirect_to: /docs/{{ site.data.releases[0].version }}
---

布局​

在 docs.html 布局模板中，我们使用条件来显示或隐藏标题和面包屑中的信息。

{% raw %} {% if page.category != 'ignore' %}
<h6 class="docs-breadcrumb">
  {{ page.version }} / {{ page.category }} {% if page.title != 'README' %} / {{
  page.title }} {% endif %}
</h6>
{% endif %} {% endraw %}

为了创建一个显示可用版本的页面，我们只需在站点根目录中的文件 versions.md 上循环遍历我们配置中的列表。 此外，我们还为此页面提供了一个 permalink：/docs/

{% raw %} {% for version in site.available_versions %} - [{{ version
}}](/docs/{{ version }}) {% endfor %} {% endraw %}

希望您喜欢这些技术细节！ 如果您有兴趣了解有关使用 Jekyll 构建文档网站的更多信息，请查看 GitHub 的文档团队如何使用 Jekyll 发布 GitHub 的文档。