New translation: remark-plugin-tutorial.md

docs/docs/remark-plugin-tutorial.md

@@ -1,37 +1,37 @@
 ---
-title: Remark Plugin Tutorial
+title: Criando sub-plugins do Remark
 ---
 
-[`gatsby-transformer-remark`](/packages/gatsby-transformer-remark) empowers developers to translate Markdown into HTML to be consumed via Gatsby's GraphQL API. Blogs and other content based sites can highly benefit from functionality enabled with this plugin. With this plugin, authors of content for the site don't need to worry about how the site is written or structured but can rather focus on writing engaging posts and content!
+[`gatsby-transformer-remark`](/packages/gatsby-transformer-remark) permite que desenvolvedores transformem arquivos Markdown em HTML que pode ser consumido através da API GraphQL do Gatsby. Blogs e outros sites baseados em exibição de conteúdo podem se beneficiar drasticamente das funcionalidades oferecidas por este plugin. Com ele, autores de conteúdo para o site não precisam se preocupar sobre como o site é escrito ou estruturado, concentrando-se ao invés disso em escrever conteúdo e posts engajadores!
 
-In certain instances, a developer may want to customize the content of the Markdown file and extend it functionally in useful ways; for example, use cases such as [adding syntax highlighting](/packages/gatsby-remark-prismjs/), [parsing and creating responsive images](/packages/gatsby-remark-images), [embedding videos](/packages/gatsby-remark-embed-video), and many others. In each of these examples, a plugin will be injected with the Markdown Abstract Syntax Tree (AST) and manipulate content based on certain node types or content in particular nodes.
+Em certas instâncias, o desenvolvedor pode querer customizar o conteúdo de um arquivo Markdown e extender sua funcionalidade de algumas maneiras úteis; por exemplo, em casos como a adição de [realce da sintaxe em trechos de código](/packages/gatsby-remark-prismjs/), [interpretação e criação de imagens responsivas](/packages/gatsby-remark-images), [inserção de vídeos](/packages/gatsby-remark-embed-video), e muitos outros. Em cada um destes exemplos, um plugin será injetado através da Árvore de Sintaxe Abstrata do Markdown (na sigla em inglês, AST) e manipular conteúdo baseado em certos tipos de nó ou conteúdos de um nó em particular.
 
-## What you will learn in this tutorial
+## O que você aprenderá nesse tutorial
 
-- Further understanding of the remark Abstract Syntax Tree (AST)
-- How to create a plugin that is injected with an AST via `gatsby-transformer-remark`
-- How to manipulate the remark AST to add additional functionality
+- Conhecer de maneira aprofundada a Árvore de Sintaxe Abstrata do Markdown (AST)
+- Como criar um plugin que é injetado com a AST através do `gatsby-transformer-remark`
+- Como manipular o AST do remark a fim de adicionar funcionalidades
 
-## Prerequisites
+## Pré-requisitos
 
-There a few things that you should have some understanding with:
+Há algumas coisas com a qual você deve ter certa familiaridade:
 
-- How to work with Remark in Gatsby as described in [Part Six](/tutorial/part-six/) and [Part Seven](/tutorial/part-seven/) of the Gatsby Tutorial.
-- Understanding of the Markdown Syntax.
+- Como trabalhar com o Remark no Gatsby, como descrito na [Parte Seis](/tutorial/part-six/) e [Parte Sete](/tutorial/part-seven/) do tutorial do Gatsby.
+- Entendimento da Sintaxe do Markdown.
 
-## Understanding the Abstract Syntax Tree
+## Entendendo a Árvore de Sintaxe Abstrata:
 
-To get an understanding at what is available in the Markdown AST, take a look at the Markdown AST spec that is used in remark and other unist projects: [syntax-tree/mdast](https://github.com/syntax-tree/mdast).
+Para entender o que está disponível na AST do Markdown, dê uma olhada nas especificações da AST do Markdown que é usada no remark e em outros projetos `unist`: [syntax-tree/mdast](https://github.com/syntax-tree/mdast).
 
-Starting out with a Markdown file as below:
+Começando com um arquivo Markdown como abaixo:
 
 ```markdown
 # Hello World!
 
 This is a [Real page](https://google.com)
 ```
 
-Remark would translate this into an AST made available to `gatsby-transformer-remark` plugins. The AST would appear as the following:
+O Remark irá traduzir isso em uma AST que estará disponível para os plugins do `gatsby-transformer-remark`. A AST irá aparecer desta forma:
 
 ```json
 {
@@ -105,33 +105,33 @@ Remark would translate this into an AST made available to `gatsby-transformer-re
 }
 ```
 
-As well, [AST Explorer](https://astexplorer.net/#/gist/d9029a2e8827265fbb9b190083b59d4d/3384f3ce6a3084e50043d0c8ce34628ed7477603) is a site that gives you a side-by-side view of the markdown and the outputted AST.
+Adicionalmente, o [AST Explorer](https://astexplorer.net/#/gist/d9029a2e8827265fbb9b190083b59d4d/3384f3ce6a3084e50043d0c8ce34628ed7477603) é um site que lhe fornece uma visão lado-a-lado do Markdown e sua saída correspondente no formato AST.
 
-## Setting up a plugin
+## Configurando um plugin
 
-You are going to create a plugin that colors all top-level headings in the markdown with the color purple.
+Você irá criar um plugin que fará com que todos os cabeçalhos de alto nível no Markdown tenham a cor roxa.
 
-First create a local plugin by adding a `plugins` folder in your site and generating a `package.json` file for it. As well, create an `index.js` file. In this file, we export a function that will be invoked by `gatsby-transformer-remark`:
+Primeiro, crie um plugin local adicionando um diretório `plugins` ao seu site e gerando um arquivo `package.json` para ele. Crie também um arquivo `index.js`. Nesse arquivo, exportaremos uma função que irá ser invocada pelo `gatsby-transformer-remark`:
 
 ```js:title=plugins/gatsby-remark-purple-headers/index.js
 module.exports = ({ markdownAST }, pluginOptions) => {
-  // Manipulate AST
+  // Manipulação do AST
 
   return markdownAST
 }
 ```
 
-The first parameter is all of the default properties that can be used in plugins (actions, store, getNodes, schema, etc.) plus a couple just for gatsby-transformer-remark plugins. The most relevant field for our purposes is the `markdownAST` field which is destructured in the code snippet above.
+O primeiro parâmetro refere-se à todas as propriedades padrão que podem ser usadas em plugins (actions, store, getNodes, schema, etc.), e, adicionalmente, alguns usados apenas para plugins do `gatsby-transformer-remark`. O campo mais relevante para os nossos propósitos é o `markdownAST`, que foi desestruturado no trecho de código acima.
 
-As with other Gatsby plugins, the 2nd parameter is the `pluginOptions` which is obtained from the definition in `gatsby-config.js` file.
+Similarmente à outros plugins do Gatsby, o segundo parâmetro é o `pluginOptions` que é obtido da definição no arquivo `gatsby-config.js`.
 
-Finally, the function will return the `markdownAST` after the fields you wish to be edited are transformed.
+Finalmente, a função irá retornar o `markdownAST` após os campos que você deseja que sejam editados serem transformados.
 
-## Adding the plugin to your site
+## Adicionando o plugin ao seu site
 
-You likely will want to grab `gatsby-source-filesystem` to inject the file nodes into Gatsby's GraphQL schema. In this example it is assumed that the Markdown files exist in a `src/data/` directory.
+Você provavelmente irá querer usar `gatsby-source-filesystem` para injetar os nós de arquivos no schema do GraphQL do Gatsby. Nesse exemplo, assumimos que os arquivos Markdown existam em um diretório `src/data/`.
 
-The plugin is now initially set so you can add it as a sub-plugin inside `gatsby-transformer-remark`
+O plugin agora está inicialmente configurado para que você possa adicioná-lo como um sub-plugin dentro do `gatsby-transformer-remark`.
 
 ```js:title=gatsby-config.js
 module.exports = {
@@ -153,24 +153,24 @@ module.exports = {
 }
 ```
 
-If you want to add some options, you could switch to the object syntax:
+Caso queira adicionar mais opções, você poderá mudar para a sintaxe de objeto:
 
 ```js
 {
   resolve: `gatsby-remark-purple-headers`,
   options: {
-    // Options here
+    // Opções aqui
   }
 }
 ```
 
-## Find and Modify Markdown Nodes
+## Encontrando e Modificando Nós do Markdown
 
-When modifying nodes, you'll want to walk the tree and then implement new functionality on specific nodes.
+Quando estiver modificando nós, você irá querer navegar pela árvore e então implementar novas funcionalidades em nós específicos.
 
-A node module to help with is [unist-util-visit](https://github.com/syntax-tree/unist-util-visit), a walker for `unist` nodes. For reference, Unist (Unified Syntax Tree) is a standard for Markdown syntax trees and parsers that include well known parsers in the Gatsby world like Remark and MDX.
+Um node module que pode lhe ajudar é o [unist-util-visit](https://github.com/syntax-tree/unist-util-visit), um navegador para nós `unist`. Para referência, Unist (Unified Syntax Tree) é um padrão adotado por árvores de sintaxe Markdown e interpretadores que inclui interpretadores já bem conhecidos no mundo do Gatsby como Remark e MDX.
 
-As an example from `unist-util-visit`'s README file, it allows for an interface to visit particular nodes based on a particular type:
+Como exemplificado no arquivo README do `unist-util-visit`, isso permite que uma interface visite nós particulares baseados em uma tipagem particular:
 
 ```js
 var remark = require("remark")
@@ -185,26 +185,26 @@ function visitor(node) {
 }
 ```
 
-Here, it finds all text nodes and will `console.log` the nodes. The second argument can be replaced with any type described in Unist's [Markdown AST (mdast) specification](https://github.com/syntax-tree/mdast#nodes) including types such as `paragraph`, `blockquote`, `link`, `image` or in our usecase, `heading`.
+Aqui, ele encontrará todos os nós de texto e irá logar todos com um `console.log`. O segundo argumento pode ser substituído com qualquer tipagem descrita na [especificação Markdown AST (mdast)](https://github.com/syntax-tree/mdast#nodes) do Unist, incluindo tipagens como `paragraph`, `blockquote`, `link`, `image` ou, em nosso caso, `heading`.
 
-With this technique in mind, you can similarly traverse the AST from your plugin and add additional functionality, like so:
+Com essa técnica em mente, você pode atravessar a AST similarmente com o seu plugin e adicionar uma funcionalidade adicional desta forma:
 
 ```js:title=plugins/gatsby-remark-purple-headers/index.js
 const visit = require("unist-util-visit")
 
 module.exports = ({ markdownAST }, pluginOptions) => {
-  // highlight-next-line
+  // destaque-próxima-linha
   visit(markdownAST, "heading", node => {
-    // Do stuff with heading nodes
+    // Faz alguma coisa com os nós do cabeçalho
   })
 
   return markdownAST
 }
 ```
 
-Next, by visiting all heading nodes and passing them into a transformer function, you can manipulate the particular nodes to match your use case.
+Em seguida, visitando todos os nós de cabeçalho e passando-os por uma função do transformer, você pode manipular nós particulares que estejam alinhados ao seu caso de uso.
 
-Looking again at the AST node for heading:
+Olhando novamente para o nó da AST para o cabeçalho:
 
 ```json
 {
@@ -229,9 +229,9 @@ Looking again at the AST node for heading:
 },
 ```
 
-You have context about the text as well as what depth the heading is (for instance here you have a depth of 1 which would equate to an `h1` element)
+Você agora tem contexto sobre o texto, assim como a profundidade em que o cabeçalho encontra-se (por exemplo, aqui há uma profundidade de valor 1, o que corresponde à um elemento `h1`).
 
-With the inner function of the `visit` call, you parse out all of the text and if it will map to a h1, you set the type of the node to `html` and set the node's value to be some custom HTML.
+Com a função interna da chamada `visit`, você pode interpretar todo o texto, e se ele for mapeado para um elemento `h1`, configurar o tipo do nó para `html`, atribuindo seu valor à algum HTML customizado.
 
 ```js
 const visit = require("unist-util-visit")
@@ -241,10 +241,10 @@ module.exports = ({ markdownAST }, pluginOptions) => {
   visit(markdownAST, "heading", node => {
     let { depth } = node
 
-    // Skip if not an h1
+    // Ignora caso não seja um h1
     if (depth !== 1) return
 
-    // Grab the innerText of the heading node
+    // Pega o innerText do nó do cabeçalho
     let text = toString(node)
 
     const html = `
@@ -262,22 +262,22 @@ module.exports = ({ markdownAST }, pluginOptions) => {
 }
 ```
 
-A small library [mdast-util-to-string](https://github.com/syntax-tree/mdast-util-to-string) by Unified was used to extract the plain text of the inner nodes. This would remove links or other types of nodes inside the heading, but given you have full access to the markdown AST, you can modify it however you wish.
+A pequena biblioteca [mdast-util-to-string](https://github.com/syntax-tree/mdast-util-to-string) da Unified foi usada para extrair o texto sem formatação dos nós internos. Isso removeria links ou outros tipos de nós dentro do cabeçalho, mas visto que você possui acesso completo à AST do markdown, você pode modificá-lo da maneira que desejar.
 
-## Loading in changes and seeing effect
+## Carregando mudanças e vendo efeito
 
-At this point, our plugin is now ready to be used. To see the resulting functionality, it is helpful to re-visit [Part 7 of the Gatsby Tutorial](/tutorial/part-seven/) to programmatically create pages from Markdown data. Once this is set up, you can examine that your plugin works as seen below based on the markdown you wrote earlier.
+À essa altura, nosso plugin está pronto para ser utilizado. Para ver o resultado da funcionalidade, é recomendável revisitar a [Parte 7 do Tutorial do Gatsby](/tutorial/part-seven/) para criar páginas programaticamente através dos dados Markdown. Quando isso estiver configurado, você pode observar que seu plugin funciona como visto abaixo baseado no Markdown que foi escrito anteriormente.
 
 ![Output](./images/remark-ast-output.png)
 
-## Publishing the plugin
+## Publicando o plugin
 
-To share this plugin with others, you can extract the plugin to its own directory outside of this site and then publish it to NPM so it can be accessed both on NPM and [Submitted to the Plugin Library](/contributing/submit-to-plugin-library).
+Para compartilhar esse plugin com outros, você pode extraí-lo em seu próprio diretório fora do site e então publicá-lo no NPM para que ele possa ser acessado tanto do NPM, quanto [Submetido à Biblioteca de Plugins](/contributing/submit-to-plugin-library).
 
-## Summary
+## Sumário
 
-You just wrote a local Gatsby plugin that is a sub-plugin for `gatsby-transformer-remark` that manipulates the Remark AST. You should now have a further understanding about the structure of Markdown Abstract Syntax Trees! Yay!
+Você acabou de escrever um plugin local do Gatsby que opera como um sub-plugin para o `gatsby-transformer-remark` manipulando a AST do Remark. Agora você deve possuir um melhor entendimento da estrutura das Árvores de Sintaxe Abstrata do Markdown! Yay!
 
-## What's next?
+## Qual o próximo passo?
 
-If you wish to see other plugins that manipulate the Remark AST, search for `gatsby-remark-` in the [plugin library](/plugins).
+Se você gostaria de ver outros plugins que manipulam a AST do Remark, pesquise por `gatsby-remark-` na [biblioteca de plugins](/plugins).