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，这是一个包含注册表中 3400 多个专门用于 Electron 的模块的集合。

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 thumbnail
• is:tutorial security
• is:package ipc
• is:app graphql

键盘导航​

人们都喜欢键盘快捷键！新的搜索功能无需离开键盘即可使用。

• / 将焦点置于搜索输入框
• esc 将焦点置于搜索输入框并清空内容
• down 移动到下一个搜索结果
• up 移动到上一个搜索结果，或搜索输入框
• enter 打开搜索结果

我们还开源了 模块，该模块实现了这种键盘交互功能。它设计用于与 Algolia InstantSearch 配合使用，但经过通用化处理，可与不同的搜索实现兼容。

我们需要您的反馈​

如果您在使用新的搜索工具时遇到任何问题，请告诉我们！

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

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

感谢​

特别感谢 Emily Jordan 和 Vanessa Yuen 构建了这些新的搜索功能，感谢 Libraries.io 提供了 SourceRank 分数，以及 Algolia 团队在启动阶段提供的帮助。🍹

自从 推出新的国际化 Electron 网站以来，我们一直在努力使 Electron 开发体验更容易被英语世界以外的开发者所访问。

所以，我们带来了激动人心的 i18n 更新！

🌐 语言切换​

您是否知道，许多阅读翻译文档的人通常会将其与原始英文文档交叉参考？他们这样做是为了熟悉英文文档，并避免过时或不准确的翻译，这是国际化文档的一个缺点。

为了更轻松地交叉参考英文文档，我们最近发布了一项功能，允许您在 Electron 文档的某个部分之间无缝切换英文和您正在查看网站的任何语言。只要您在网站上选择了非英语语言环境，语言切换功能就会显示出来。

⚡️ 快速访问翻译页面​

在阅读文档时发现错别字或翻译错误？您不再需要登录 Crowdin，选择您的语言环境，找到您想要修复的文件等等。相反，您只需向下滚动到该文档的底部，然后点击“翻译此文档”（或您语言中的等效内容）。瞧！您将直接跳转到 Crowdin 翻译页面。现在发挥您的翻译魔力吧！

📈 部分统计数据​

自从我们公布了 Electron 文档 i18n 工作以来，我们看到了来自世界各地 Electron 社区成员的翻译贡献的巨大增长。迄今为止，我们已经**翻译了 1,719,029 个字符串，来自 1,066 位社区翻译人员，并支持 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 web 服务器替换了静态的 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 收集的数据，应用程序页面现在可以显示每个具有公共存储库的应用程序的屏幕截图、下载链接、版本、发行说明和自述文件。通过提取每个应用程序图标的颜色调色板，我们可以生成 醒目且易于访问的颜色，使每个应用程序页面在视觉上有所区分。

应用程序索引页面现在还具有类别和关键词筛选器，以便查找有趣的应用程序，例如 GraphQL GUI 和 P2P 工具。

如果您有一个希望在网站上展示的 Electron 应用程序，请在 electron/electron-apps 存储库中打开一个拉取请求。

使用 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 项目诞生于 GitHub 的开源文本编辑器 Atom，Atom 基于 Web 技术构建。Electron 最初被称为 atom-shell。Atom 是第一个使用它的应用程序，但很快人们就意识到这个神奇的 Chromium + Node 运行时可以用于各种不同的应用程序。当微软和 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 上。我们使用部署管道和 审查应用程序 功能，该功能会为每个拉取请求自动创建应用程序的运行副本。这使得审阅者可以轻松查看拉取请求对网站实时副本的实际影响。

🙏 感谢贡献者​

我们想特别感谢世界各地所有抽出时间和精力帮助改进 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://www.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 代码风格检查器。Standard 的 README 总结了做出此选择的原因。

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

我们最近还创建了 standard-markdown，以验证我们文档中的所有 JavaScript 代码段是否有效且与代码库本身的风格一致。

这些工具共同帮助我们使用持续集成 (CI) 自动查找拉取请求中的错误。这减少了人为代码审查的负担，并使我们对文档的准确性更有信心。

社区的努力​

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

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

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

本周，我们在 electronjs.org 上为 Electron 的文档提供了一个归宿。您可以访问 /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 网站，我们利用了 集合 功能来处理文档，其结构如下所示。

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

前言​

为了让 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。我们还会添加已添加到站点的所有版本的列表，以及我们希望用于整个文档集合的永久链接。

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

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

---
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 中的配置列表。此外，我们还为该页面提供了一个永久链接：/docs/

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

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