5 篇博文 含有标签「网站」

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

学习像 Electron 这样的新技术或框架可能有点令人生畏。 当您学习完快速开始部分后，寻找最佳实践、正确的 API 或者合适的辅助工具可能会有点困难。 我们希望 Electron 网站成为帮助您寻找开发资料的更好工具。

访问 electronjs.org 的任意页面，您便可以在页面顶端找到搜索框。

搜索引擎​

起初我们为网站添加搜索时，我们使用了自己的，基于 GraphQL 的后端。 GraphQL 很有趣，并且搜索的效率很高，但我们很快认识到构建搜索引擎只是很基础的一部分。 像多词搜索和错别字检测等特性需要大量工作才能完成。 与其重复造轮子，我们决定使用现有的方案：Algolia。

Algolia 是一个托管的搜索服务，已经很快成为不少热门开源项目（如 React，Vue，Bootstrap，Yarn 等等）的选择。

以下特性让 Algolia 很适合 Electron 官网的搜索任务：

• InstantSearch.js 在您输入时提供实时搜索结果，延迟通常在 1 ms 之内。
• 输入容忍度 让您在输入 [widnow] 等错别字时也能获得结果。
• 高级查询语法 允许您使用 "exact quoted matches" 和 -exclusion 等语句。
• API 客户端 是开源的，并有大量文档。
• 分析 帮助我们了解人们经常搜索的内容，以及哪些缺失的内容需要补充。 这将为我们提供有关如何改进 Electron 文档的宝贵见解。
• Algolia 对开源项目 免费。

API 文档​

有时你知道_你想要完成什么_ ，但你不完全知道_如何做_。 Electron 拥有超过 750 个 API 方法、事件和属性。 没有人能够轻易地记住所有这些，但计算机在这件事上很擅长。 通过 Electron 的 JSON API 文档，我们将所有这些数据编入了 Algolia 。 现在你可以轻松地找到你想要的 API。

尝试调整窗口大小？ 搜索 [调整大小] 并直接跳转到您需要的方法。

教程​

Electron 的教程正在逐步丰富，以跟进它的 API 文档。 现在你可以更容易地找到关于某个主题的教程，以及相关的 API 文档。

寻找安全方面的最佳实践？ 搜索 [security]。

npm 包​

目前 npm 注册表中有超过 70 万个包，找到所需的包并不总是容易。 为了更容易地寻找这些依赖包，我们创建了 electron-npm-packages 这个集合，包含 3400 余个专为 Electron 编写的依赖项目。

Libraries.io 的工作者们做了 SourceRank，可以基于一系列指标（如代码、社区、文档、用法等）对开源项目进行评分。 我们创建了一个 [sourceranks] 模块，它包含了在 npm 注册表中每个模块的分数。 并且我们 使用这些分数来排序包结果。

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

Electron 应用​

使用 Algolia 索引数据很容易，所以我们添加了 GitHub 的 electron/apps 中的项目。

尝试搜索 [音乐] 或 [自制程序]。

Filtering Results​

如果你以前使用过 GitHub 的代码搜索功能，你可能知道它的键 - 值过滤用法，如 extension:js 或 user:defunkt 。 我们认为这种机制很有用，因此我们添加了一个 is: 关键词到 Electron 网站的搜索引擎中，帮助你筛选结果的类型：

• is:api thumbnail
• is:tutorial security
• is:package ipc
• is:app graphql

快捷键​

人们喜欢键盘快捷键！ 新的搜索可以让你手不离键盘：

• / 聚焦到搜索输入框
• Esc 聚焦到搜索输入框并清除内容
• ↓ 移动到下一个结果
• ↑ 移动到之前的结果，或搜索内容
• Enter 打开结果

我们已经将这个模块开源了。 它被设计成与 Algolia InstantSearch 一起使用，但是也为不同的搜索实现做了兼容。

我们希望得到您的反馈​

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

提交反馈的最佳方式是在 GitHub 的对应仓库中提交 issue：

• electron/electronjs.org 是 Electron 的网站。 如果你不知道某个问题应该在哪提 issue，可以在这里提出。
• 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 团队。 🍹

Ever since the launch of the new internationalized Electron website, we have been working hard to make the Electron development experience even more accessible to developers outside of the English speaking world.

So here we are with some exciting i18n updates!

🌐 Language Toggle​

Did you know that many people who read translated documentation often cross reference that with the original English documentation? They do this to familiarize themselves with English docs, and to avoid outdated or inaccurate translations, which is one caveat of internationalized documentations.

To make cross-referencing to English docs easier, we recently shipped a feature that allows you to seamlessly toggle a section of the Electron documentation between English and whatever language you're viewing the website in. The language toggle will show up as long as you have a non-English locale selected on the website.

⚡️ Quick Access to Translation Page​

Notice a typo or an incorrect translation while you're reading the documentation? You no longer have to log in to Crowdin, pick your locale, find the file you'd like the fix, etc etc. Instead, you can just scroll down to the bottom of the said doc, and click "Translate this doc" (or the equivalent in your language). Voila! You are brought straight to the Crowdin translation page. Now apply your translation magic!

📈 Some Statistics​

Ever since we have publicized the Electron documentation i18n effort, we have seen huge growth in translation contributions from Electron community members from all around the world. To date, we have 1,719,029 strings translated, from 1,066 community translators, and in 25 languages.

Here is a fun graph showing the approximate amount of time needed to translate the project into each language if the existing tempo (based on the project activity during the last 14 days at the time of writing) is preserved.

📃 Translator Survey​

We would like to give a huge ❤️ thank you ❤️ to everyone who has contributed their time to help improving Electron! In order to properly acknowledge the hard work of our translator community, we have created a survey to collect some information (namely the mapping between their Crowdin and Github usernames) about our translators.

If you are one of our incredible translators, please take a few minutes to fill this out: https://goo.gl/forms/b46sjdcHmlpV0GKT2.

🙌 Node's Internationalization Effort​

Because of the success of Electron's i18n initiative, Node.js decided to model their revamped i18n effort after the pattern we use as well! 🎉 The Node.js i18n initiative has now been launched and gained great momentum, but you can stil read about the early proposal and reasoning behind it here.

🔦 Contributing Guide​

If you're interested in joining our effort to make Electron more international friendly, we have a handy-dandy contributing guide to help you get started. Happy internationalizing! 📚

Electron has a new website at electronjs.org! We've replaced our static Jekyll site with a Node.js webserver, giving us flexibility to internationalize the site and paving the way for more exciting new features.

🌍 翻译​

We've begun the process of internationalizing the website with the goal of making Electron app development accessible to a global audience of developers. We're using a localization platform called Crowdin that integrates with GitHub, opening and updating pull requests automatically as content is translated into different languages.

Though we've been working quietly on this effort so far, over 75 Electron community members have already discovered the project organically and joined in the effort to internationalize the website and translate Electron's docs into over 20 languages. We are seeing daily contributions from people all over the world, with translations for languages like French, Vietnamese, Indonesian, and Chinese leading the way.

To choose your language and view translation progress, visit electronjs.org/languages

If you're multilingual and interested in helping translate Electron's docs and website, visit the electron/electron-i18n repo, or jump right into translating on Crowdin, where you can sign in using your GitHub account.

There are currently 21 languages enabled for the Electron project on Crowdin. Adding support for more languages is easy, so if you're interested in helping translate but you don't see your language listed, let us know and we'll enable it.

Raw Translated Docs​

If you prefer to read documentation in raw markdown files, you can now do that in any language:

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

App Pages​

As of today, any Electron app can easily have its own page on the Electron site. For a few examples, check out Etcher, 1Clipboard, or GraphQL Playground, pictured here on the Japanese version of the site:

There are some incredible Electron apps out there, but they're not always easy to find, and not every developer has the time or resources to build a proper website to market and distribute their app.

Using just a PNG icon file and a small amount of app metadata, we're able to collect a lot of information about a given app. Using data collected from GitHub, app pages can now display screenshots, download links, versions, release notes, and READMEs for every app that has a public repository. Using a color palette extracted from each app's icon, we can produce bold and accessible colors to give each app page some visual distinction.

The apps index page now also has categories and a keyword filter to find interesting apps like GraphQL GUIs and p2p tools.

If you've got an Electron app that you'd like featured on the site, open a pull request on the electron/electron-apps repository.

One-line Installation with Homebrew​

The Homebrew package manager for macOS has a subcommand called cask that makes it easy to install desktop apps using a single command in your terminal, like brew cask install atom.

We've begun collecting Homebrew cask names for popular Electron apps and are now displaying the installation command (for macOS visitors) on every app page that has a cask:

To view all the apps that have homebrew cask names, visit electronjs.org/apps?q=homebrew. If you know of other apps with casks that we haven't indexed yet, please add them!

🌐 A New Domain​

We've moved the site from electron.atom.io to a new domain: electronjs.org.

The Electron project was born inside Atom, GitHub's open-source text editor built on web technologies. Electron was originally called atom-shell. Atom was the first app to use it, but it didn't take long for folks to realize that this magical Chromium + Node runtime could be used for all kinds of different applications. When companies like Microsoft and Slack started to make use of atom-shell, it became clear that the project needed a new name.

And so "Electron" was born. In early 2016, GitHub assembled a new team to focus specifically on Electron development and maintenance, apart from Atom. In the time since, Electron has been adopted by thousands of app developers, and is now depended on by many large companies, many of which have Electron teams of their own.

Supporting GitHub's Electron projects like Atom and GitHub Desktop is still a priority for our team, but by moving to a new domain we hope to help clarify the technical distinction between Atom and Electron.

🐢🚀 Node.js Everywhere​

The previous Electron website was built with Jekyll, the popular Ruby-based static site generator. Jekyll is a great tool for building static websites, but the website had started to outgrow it. We wanted more dynamic capabilities like proper redirects and dynamic content rendering, so a Node.js server was the obvious choice.

The Electron ecosystem includes projects with components written in many different programming languages, from Python to C++ to Bash. But JavaScript is foundational to Electron, and it's the language used most in our community.

By migrating the website from Ruby to Node.js, we aim to lower the barrier to entry for people wishing to contribute to the website.

⚡️ Easier Open-Source Participation​

If you've got Node.js (8 or higher) and git installed on your system, you can easily get the site running locally:

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

The new website is hosted on Heroku. We use deployment pipelines and the Review Apps feature, which automatically creates a running copy of the app for every pull request. This makes it easy for reviewers to view the actual effects of a pull request on a live copy of the site.

🙏 Thanks to Contributors​

We'd like to give special thanks to all the folks around the world who have contributed their own time and energy to help improve Electron. The passion of the open-source community has helped immeasurably in making Electron a success. Thank you!

今天我们正式宣布对Electron文档的一些改进。 现在，每个新的发布版本都将包括一份对Electron公共API详细描述的JSON文件 我们创建该文件，以此让开发者能够用新潮有趣的方式来访问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://electronjs.org/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文件并强制执行styleguid中的规则。 如果发现错误，则会列出这些错误，并暂停发布 过程。 如果 API 文档有效，则会创建 electron-json.api 文件 ，并作为 Electron 版本的一部分上传到 GitHub。

标准 Javascript 和标准 Markdown​

今年早些时候，Electron的代码库进行了更新，以在所有JavaScript中使用 standard 代码纠错工具（linter）。 Standard的 README文件总结了这一选择背后的原因：

采用标准风格意味着代码清晰度和社区约定的重要性比个人风格更高。 也许这对所有项目和发展文化来说是难以理解的，但对新手来说开源可能是一个令人生畏的地方。 设定明确、自动的代码贡献者期望能使一个项目更加健康。

我们最近还创建了[standard-markdown](https://github. com/zeke/standard-markdown) ，以验证文档中所有JavaScript代码片段是否有效且与代码库本身的样式一致。

这些工具一起帮助我们使用连续集成 (CI) 来自动找到 拉取请求（Pull Request）中的错误。 这减轻了人类在代码 审查方面的负担，并使我们对文档的准确性更有信心。

社区的努力​

因我们可敬的开源社区的不懈努力，Electron的文档在不断改进。 在撰写本文时， 近300人为文档做出了贡献。

我们很期待看到人们如何处理这个新的结构化数据。 可能的用途包括：

• 对https://electronjs.org/docs/的改进
• 一个 TypeScript 定义文件 用于简化 使用 TypeScript 进行 Electron 开发的项目。
• 为Dash.app和devdocs.io等工具提供可搜索的离线技术文档

This week we've given Electron's documentation a home on electronjs.org. You can visit /docs/latest for the latest set of docs. We'll keep versions of older docs, too, so you're able to visit /docs/vX.XX.X for the docs that correlate to the version you're using.

You can visit /docs to see what versions are available or /docs/all to see the latest version of docs all on one page (nice for cmd + f searches).

如果您想要为文档内容做出贡献， 您可以在 Electron 仓库中获取文档。 We fetch them for each minor release and add them to the Electron site repository, which is made with Jekyll.

If you're interested in learning more about how we pull the docs from one repository to another continue reading below. Otherwise, enjoy the docs!

The Technical Bits​

We're preserving the documentation within the Electron core repository as is. This means that electron/electron will always have the latest version of the docs. When new versions of Electron are released, we duplicate them over on the Electron website repository, electron/electronjs.org.

script/docs​

To fetch the docs we run a script with a command line interface of script/docs vX.XX.X with or without the --latest option (depending on if the version you're importing is the latest version). Our script for fetching docs uses a few interesting Node modules:

• nugget 用于 获取正式版本的压缩包 并将其保存到临时目录。
• gunzip-maybe to unzip the tarball.
• tar-fs for streaming just the /docs directory from the tarball and filtering and processing the files (with the help of through2) so that they work nicely with our Jekyll site (more on that below).

Tests help us know that all the bits and pieces landed as expected.

Jekyll​

The Electron website is a Jekyll site and we make use of the Collections feature for the docs with a structure like this:

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

前页附属资料​

For Jekyll to render each page it needs at least empty front matter. We're going to make use of front matter on all of our pages so while we're streaming out the /docs directory we check to see if a file is the README.md file (in which case it receives one front matter configuration) or if it is any other file with a markdown extension (in which case it receives slightly different front matter).

Each page receives this set of front matter variables:

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

The README.md gets an additional permalink so that has a URL has a common root of index.html rather than an awkward /readme/.

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

Config and Redirects​

In the site's _config.yml file a variable latest_version is set every time the --latest flag is used when fetching docs. We also add a list of all the versions that have been added to the site as well as the permalink we'd like for the entire docs collection.

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

The file latest.md in our site root is empty except for this front matter which allows users to see the index (aka README) of the latest version of docs by visiting this URL, electron.atom.io/docs/latest, rather than using the latest version number specifically (though you can do that, too).

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

布局​

In the docs.html layout template we use conditionals to either show or hide information in the header and breadcrumb.

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

To create a page showing the versions that are available we just loop through the list in our config on a file, versions.md, in the site's root. Also we give this page a permalink: /docs/

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

Hope you enjoyed these technical bits! If you're interested in more information on using Jekyll for documentation sites, checkout how GitHub's docs team publishes GitHub's docs on Jekyll.