5 постов с тегом "Веб-сайт"

The Electron website has a new search engine that delivers instant results for API docs, tutorials, Electron-related npm packages, and more.

Learning a new technology or framework like Electron can be intimidating. Once you get past the quick-start phase, it can be difficult to learn best practices, find the right APIs, or discover the tools that will help you build the app of your dreams. We want the Electron website to be a better tool for finding the resources you need to build apps faster and more easily.

Visit any page on electronjs.org and you'll find the new search input at the top of the page.

The Search Engine​

When we first set about adding search to the website, we rolled our own search engine using GraphQL as a backend. GraphQL was fun to work with and the search engine was performant, but we quickly realized that building a search engine is not a trivial task. Things like multi-word search and typo detection require a lot of work to get right. Rather than reinventing the wheel, we decided to use an existing search solution: Algolia.

Algolia is a hosted search service that has quickly become the search engine of choice among popular open source projects like React, Vue, Bootstrap, Yarn, and many others.

Here are some of the features that made Algolia a good fit for the Electron project:

• InstantSearch.js provides results as you type, usually in about 1ms.
• Typo tolerance означает, что вы все равно получите результаты, даже когда вы вводите [widnow].
• Advanced query syntax enables "exact quoted matches" and -exclusion.
• API clients are open source and with well-documented.
• Analytics tell us what people are searching for most, as well as what they're searching for but not finding. This will give us valuable insight into how Electron's documentation can be improved.
• Algolia is free for open source projects.

API Docs​

Sometimes you know what you want to accomplish, but you don't know exactly how to do it. Electron имеет более 750 API методов, событий и свойств. Ни один человек не может легко запомнить их все, но компьютеры хороши в этом деле. Using Electron's JSON API docs, we indexed all of this data in Algolia, and now you can easily find the exact API you're looking for.

Trying to resize a window? Поиск [resize] и прыжок прямо к нужному методу.

Инструкции​

Electron has an ever-growing collection of tutorials to complement its API documentation. Now you can more easily find tutorials on a given topic, right alongside related API documentation.

Looking for security best practices? Поиск [security].

npm Packages​

There are now over 700,000 packages in the npm registry and it's not always easy to find the one you need. To make it easier to discover these modules, we've created electron-npm-packages, a collection of the 3400+ modules in the registry that are built specifically for use with Electron.

Люди в библиотеках. o создал SourceRank, система для оценки проектов программного обеспечения на основе сочетания таких метрик, как код, сообщество, документация и использование. Мы создали [исходные тексты] модуль, который включает оценку каждого модуля в реестре npm, и мы используем эти результаты для сортировки результатов.

Want alternatives to Electron's built-in IPC modules? Поиск is:package ipc.

Приложения Electron​

It's easy to index data with Algolia, so we added the existing apps list from electron/apps.

Попробуйте найти [музыку] или [homebrew].

Filtering Results​

If you've used GitHub's code search before, you're probably aware of its colon-separated key-value filters like extension:js or user:defunkt. We think this filtering technique is pretty powerful, so we've added an is: keyword to Electron's search that lets you filter results to only show a single type:

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

Keyboard Navigation​

People love keyboard shortcuts! The new search can be used without taking your fingers off the keyboard:

• / focuses the search input
• esc focuses the search input and clears it
• down moves to the next result
• up moves to the previous result, or the search input
• enter opens a result

We also open-sourced the module that enables this keyboard interaction. It's designed for use with Algolia InstantSearch, but is generalized to enable compatibility with different search implementations.

We want your feedback​

If you encounter any issues with the new search tool, we want to hear about it!

The best way to submit your feedback is by filing an issue on GitHub in the appropriate repository:

• electron/electronjs.org is the Electron website. If you don't know where to file an issue, this your best bet.
• electron/algolia-indices is where all the searchable Electron data is compiled.
• electron/search-with-your-keyboard makes the search interface navigable by keyboard.
• algolia/instantsearch.js is the browser-side client that enables find-as-you-type search.
• algolia/algoliasearch-client-javascript is the Node.js client for uploading data to Algolia's servers.

Thanks​

Special thanks to Emily Jordan and Vanessa Yuen for building these new search capabilities, to Libraries.io for providing SourceRank scores, and to the team at Algolia for helping us get started. 🍹

С момента запуска нового локализованного сайта Electron мы прилагаем все усилия для того, чтобы сделать опыт разработки Electron еще более доступным для разработчиков за пределами англоязычного мира.

Итак, мы представляем вашему вниманию несколько интересных обновлений i18n!

Переключение языка​

Знаете ли вы, что многие люди, которые читают переведенную документацию, часто перекрестно ссылаются на оригинальную английскую документацию? Они делают это для ознакомления с английской документацией и избежания устаревшего или некорректного перевода, что является одной из особенностей локализованной документации.

Чтобы облегчить работу с англоязычной документацией, мы недавно добавили функцию, позволяющую плавно переключать раздел документации Electron между английским и тем языком, на котором вы просматриваете сайт. Переключатель языка будет отображаться до тех пор, пока на сайте выбрана неанглийская локаль.

⚡️ Быстрый доступ к странице перевода​

Заметили опечатку или неправильный перевод при чтении документации? Вам больше не нужно входить в Crowdin, выбирать локаль, находить файл, который вы хотите исправить, и т.д. и т.п. Вместо этого можно просто прокрутить страницу до самого низа указанного документа и нажать кнопку "Перевести этот документ" (или ее эквивалент на вашем языке). Вуаля! Вы переходите на страницу перевода Crowdin. Примените вашу магию перевода!

📈 Некоторая статистика​

С тех пор как мы обнародовали информацию о работе над i18n-документацией Electron, мы наблюдаем огромный рост вклада в перевод со стороны участников сообщества Electron со всего мира. На сегодняшний день переведено 1 719 029 строк, от 1 066 переводчиков сообщества и на 25 языках.

Вот забавный график, показывающий примерное количество времени, необходимое для перевода проекта на каждый язык при сохранении существующего темпа (по активности проекта за последние 14 дней на момент написания статьи).

📃 Опрос переводчиков​

Мы хотели бы выразить огромную ❤️ благодарность ❤️ всем, кто посвятил свое время улучшению Electron! Для того чтобы должным образом оценить труд наших переводчиков, мы создали опросник, в котором собрали некоторую информацию (в частности, соответствие между их именами пользователей Crowdin и Github) о наших переводчиках.

Если вы являетесь одним из наших замечательных переводчиков, пожалуйста, потратьте несколько минут, чтобы заполнить эту форму: 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.

🌍 Translations​

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. Каждый новый релиз теперь включает в себя файл JSON, который описывает всё об публичных API Electron в деталях. Мы создали этот файл, чтобы разработчики могли использовать документацию Electron API новыми интересными способами.

Обзор схемы​

Каждое API - это объект со свойствами по типу имени, описания, типа и т.д. Такие классы, как BrowserWindow и Menu имеют дополнительные свойства, описывающие методы, свойства, события и т.п. их экземпляра.

Вот пример из схемы, которая описывает класс BrowserWindow:

{
  имя: 'BrowserWindow',
  описание: 'Создание и управление окнами браузера. ,
  процесс: {
    main: true,
    renderer: false
  },
  тип: 'Класс',
  exanceName: 'win',
  слаг: 'browser-window',
  websiteUrl: 'https://electronjs. rg/docs/api/browser-window',
  repoUrl: 'https://github.com/electron/electron/blob/v1.4.0/docs/api/browser-window. d',
  staticMethods: [...],
  instanceMethods: [...],
  instanceProperties: [...],
  instanceEvents: [...]
}
}

И вот пример описания метода, в данном случае метод apis.BrowserWindow.instanceMethods.setMaximumSize экземпляра:

{
  name: 'setMaximumSize',
  signature: '(width, height)',
  description: 'Устанавливает максимальный размер окна по ширине и высоте.',
  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, поэтому его содержимое может быть автоматически обработан.

The electron-docs-linter is a new development dependency of the electron/electron repository. It is a command-line tool that lints all the markdown files and enforces the rules of the styleguide. If errors are found, they are listed and the release process is halted. If the API docs are valid, the electron-json.api file is created and uploaded to GitHub as part of the Electron release.

Standard Javascript and Standard Markdown​

Earlier this year, Electron's codebase was updated to use the standard linter for all JavaScript. Standard's README sums up the reasoning behind this choice:

Adopting standard style means ranking the importance of code clarity and community conventions higher than personal style. This might not make sense for 100% of projects and development cultures, however open source can be a hostile place for newbies. Setting up clear, automated contributor expectations makes a project healthier.

We also recently created standard-markdown to verify that all the JavaScript code snippets in our documentation are valid and consistent with the style in the codebase itself.

Together these tools help us use continuous integration (CI) to automatically find errors in pull requests. This reduces the burden placed on humans doing code review, and gives us more confidence about the accuracy of our documentation.

A community effort​

Electron's documentation is constantly improving, and we have our awesome open-source community to thank for it. As of this writing, nearly 300 people have contributed to the docs.

We're excited to see what people do with this new structured data. Possible uses include:

• Improvements to https://electronjs.org/docs/
• A TypeScript definition file for more streamlined Electron development in projects using TypeScript.
• Searchable offline documentation for tools like Dash.app and 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 for getting the release tarball and saving it to a temporay directory.
• 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

Front matter​

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 }}
---

Layouts​

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.