5 publicaciones etiquetados con "Sitio web"

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.
• Tolerancia tipográfica significa que todavía obtendrás resultados incluso cuando escribas 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 has over 750 API methods, events, and properties. No human can easily remember all of them, but computers are good at this stuff. 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? Busca [redimensionar] y salta directamente al método que necesitas.

Tutoriales​

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? Search for 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.

La gente de Bibliotecas. o han creado SourceRank, un sistema para anotar proyectos de software basado en una combinación de métricas como código, comunidad, documentación y uso. Hemos creado un módulo [sourceranks] que incluye la puntuación de cada módulo en el registro npm, y nosotros usamos estas puntuaciones para ordenar los resultados del paquete.

Want alternatives to Electron's built-in IPC modules? Buscar [es:paquete ipc].

Aplicaciones de Electron​

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

Prueba a buscar [music] o [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. 🍹

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.

🌍 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!

Hoy presentamos algunas mejoras en la documentación de Electron. Cada nuevo lanzamiento ahora incluye un archivo JSON que describe todas las APIs públicas de Electron en detalle. Hemos creado este archivo para facilitar a los desarrolladores usar la documentación de la API de Electron de maneras nuevas e interesantes.

Resumen del esquema​

Cada API es un objeto con propiedades como nombre, descripción, tipo, etc. Las clases como BrowserWindow y Menu tienen propiedades adicionales que describen sus métodos de instancia, propiedades de instancia, eventos de instancia, etc.

Aquí hay un fragmento del esquema que describe la clase BrowserWindow:

{
  name: 'BrowserWindow',
  description: 'Crear y controlar ventanas del navegador. ,
  process: {
    main: true,
    renderer: false
  },
  type: 'Class',
  instanceName: 'win',
  slug: '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: [...]
}
}

Y aquí hay un ejemplo de la descripción de un método, en este caso el método de instancia apis.BrowserWindow.instanceMethods.setMaximumSize:

{
  name: 'setMaximumSize',
  signature: '(width, height)', 
  description: 'Establece el tamaño máximo de la ventana a anchura y altura. ,
  parameters: [{
    name: 'width',
    type: 'Integer'
  }, {
    name: 'height',
    type: 'Integer'
  }]
}

Usando los nuevos datos​

Para facilitar a los desarrolladores el uso de estos datos estructurados en sus proyectos, hemos creado electron-docs-api, un pequeño paquete npm que se publica automáticamente cada vez que hay una nueva versión de Electron.

npm install electron-api-docs --save

Para una gratificación instantánea, pruebe el módulo en su REPL de Node.js:

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

Qué datos se recopilan​

La documentación de la API de Electron se adhiere al Estilo de codificación de Electrón y al Estilo de Electrón, para que su contenido pueda ser analizado programáticamente.

El repositorio electron-docs-linter es una nueva dependencia de desarrollo del repositorio electron/electron. Es una herramienta de línea de comandos que muestra todos los archivos de markdown e impone la reglas del styleguide. Si se encuentran errores, se listan y el proceso de liberación se detiene. Si los documentos de la API son válidos, el archivo electron-json.api se crea y se sube a GitHub como parte de la versión de Electron.

Javascript estándar y Markdown estándar​

A principios de este año, el código base de Electron fue actualizado para usar el linter standard para todos los JavaScript. El README de standard resume el razonamiento detrás de esta elección:

Adoptar el estilo standard significa clasificar la importancia de la claridad del código y las convenciones comunitarias por encima del estilo personal. Esto podría no tener sentido para el 100% de los proyectos y las culturas de desarrollo, sin embargo el código abierto puede ser un lugar hostil para los novatos. Establecer expectativas claras y automatizadas de los colaboradores hace que un proyecto sea más saludable.

También recientemente creamos standard markdown para verificar que todos los fragmentos de código JavaScript en nuestra documentación son válidos y consistentes con el estilo en la base de código.

Juntas, estas herramientas nos ayudan a utilizar la integración continua (IC) para encontrar automáticamente errores en las solicitudes PR para añadir actualizaciones al repositorio (Pull Requests). Esto reduce la carga impuesta a los humanos haciendo revisión del código, y nos da más confianza sobre la precisión de nuestra documentación.

Un esfuerzo de la comunidad​

La documentación de Electron está mejorando constantemente, y tenemos a nuestra increíble comunidad de código abierto a la que darle las gracias por ello. Cerca de 300 personas han contribuido a la documentación, que incluye este texto.

Estamos encantados de ver qué hacen las personas con estos nuevos datos estructurados. Las usos posibles incluyen:

• Mejoras a https://electronjs.org/docs/
• Un archivo de definición de TypeScript para un desarrollo de Electron más alineado con proyectos usando TypeScript.
• Documentación que se pueda encontrar fuera de línea para herramientas como Dash.app y devdocs.io

Esta semana hemos proporcionado la documentación de Electron un lugar en electronjs.org. Puedes visitar /docs/latest para el último conjunto de documentos. También, mantendremos versiones antiguas de documentos, así que podrás visitar /docs/vX.XX.X para los documentos que se corresponden con la versión que estás usando.

Puedes visitar /docs para ver qué versiones están disponibles o /docs/all para ver la última versión de los documentos en una sola página (perfecto para búsquedas cmd + f).

Si le gustaría contribuir con el contenido de los documentos, puede hacerlo en el repositorio de Electron, desde donde los documentos son obtenidos. Los obtenemos para cada lanzamiento menor y los añadimos al repositorio del sitio Electron, el cual es realizado con Jekyll.

Si está interesado en aprender más sobre cómo obtenemos los documentos de un repositorio a otro sigue leyendo a continuación. En otro caso, ¡disfrute de los documentos!

Los bit técnicos​

Estamos preservando la documentación dentro del repositorio núcleo de Electron tal como está. Esto significa que electron/electron siempre tendrá la última versión de los documentos. Cuando se liberan las versiones nuevas de Electron, las duplicamos en el repositorio del sitio web de Electron electron/electronjs.org.

script/docs​

Para obtener los documentos ejecutamos un guion con un interfaz de línea de instrucción del script/docs v.X.XX.X con o sin la opción --latest (dependiendo de si la versión que ha importado es la última versión). Nuestro guion para obtener los documentos utiliza unos módulos de Node interesantes:

• nugget para obtener el tarball de lanzamiento y guardándolo en un directorio temporal.
• gunzip-maybe para ejecutar el unzip del tarball.
• tar-fs para transmitir tan solo el directorio /docs desde el tarball y filtrando y procesando los archivos (con la ayuda de through2) para que funcionen perfectamente con nuestro sitio Jekyll (más sobre eso a continuación).

Las pruebas nos ayudan a conocer que todos los bit y las piezas se comporten como se esperaba.

Jekyll​

El sitio web Electron es un sitio Jekyll y hacemos uso de la función Collections para los documentos con una estructura como ésta:

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

Texto preliminar​

Para que Jekyll renderice cada página necesita al menos un asunto frontal vacío. Vamos a hacer uso de la materia frontal en todas nuestras páginas, así que mientras estamos transmitiendo el directorio /docs comprobamos si un archivo es el archivo README.md (en cuyo caso recibe una configuración de materia frontal) o si es cualquier otro archivo con una extensión markdown (en cuyo caso recibe una materia frontal ligeramente diferente).

Cada página recibe este conjunto de variables de la materia principal:

---
version: v0.27.0
category: Tutorial
title: 'Inicio rápido'
source_url: 'https://github.com/electron/electron/blob/master/docs/tutorial/quick-start.md'
---

El README.md obtiene un permalink adicional por lo que tiene una URL que tiene una raíz común de index.html en lugar de una /readme/ incómoda.

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

Configuración y redirecciones​

En el archivo _config.yml del sitio se establece una variable latest_version cada vez que se utiliza el indicador --latest al recuperar documentos. También añadimos una lista de todas las versiones que han sido añadidas al sitio así como el enlace permanente que nos gustaría para toda la colección de documentos.

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

El archivo latest.md en nuestra raíz del sitio está en blanco excepto para este suceso frontal el cual concede a los usuarios ver el índice (como README) de la versión más última de los documentos visitando esta URL, electron.atom.io/docs/latest, en vez de utilizar el número de la última versión específicamente (a través del cual puede hacer eso, también).

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

Diseños​

En la plantilla de diseño docs.html utilizamos condicionales para mostrar u ocultar información en el encabezado y migaja.

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

Para crear una página mostrando las versiones que están disponibles, tan solo hacemos un bucle a través de la lista en nuestra configuración de un archivo, versions.md, en la raíz del sitio. También proporcionamos a esta página un enlace permanente: /docs/

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

¡Espero que hayas disfrutado de estos trazos técnicos! Si estás interesado en más información sobre el uso de Jekyll para sitios de documentación, revisa cómo el equipo de documentación pública de GitHub en los documentos de GitHub en Jekyll.