Como usar Markdown rapidamente no GitHub e no Reddit

Informatec Digital » Recursos » Como usar Markdown rapidamente no GitHub e no Reddit

Se você escreve regularmente no GitHub ou passa muito tempo no Reddit, dominar... Redução de preço É uma daquelas coisas que economiza horas e facilita a vida. É uma linguagem de marcação muito leve que permite formatar texto simples rapidamente, sem se preocupar com menus ou botões, apenas com alguns símbolos colocados nos lugares certos.

No GitHub você encontrará isso em todos os lugares: nos arquivos README.md de repositórios, problemas, solicitações de pull, discussões e até mesmo do seu próprio perfil. O Reddit, por sua vez, usa uma variante chamada Snoomark (Markdown no estilo do Reddit) que herda grande parte da sintaxe do GitHub, com alguns recursos exclusivos e certas limitações. Vejamos, passo a passo e com muitos exemplos, Como usar Markdown rapidamente no GitHub e no Reddit e sem omitir nada importante.

O que é Markdown e por que é tão útil no GitHub e no Reddit?

Markdown é um linguagem de marcação leve Projetado para facilitar a leitura e a escrita de texto simples, permitindo também a conversão fácil para HTML. Na prática, isso significa que você pode escrever texto normal e adicionar caracteres especiais para criar títulos, listas, tabelas, citações, código formatado, links ou imagens.

No GitHub, a implementação utilizada é o GitHub Flavored Markdown (GFM), que estende a sintaxe clássica com tabelas, listas de tarefas, realce de código avançado, suporte a cores, alertas e algumas tags HTML permitidas. Tudo isso é renderizado automaticamente. nos arquivos .md e nos campos de comentários da plataforma.

O Reddit usa seu próprio processador chamado Snoomark, um derivado do GFM. Ele compartilha grande parte do comportamento básico (negrito, itálico, títulos, listas, citações, código embutido ou em bloco, links, etc.), mas possui características importantesPor exemplo, o suporte a imagens é mais limitado dependendo do contexto e adiciona elementos próprios, como spoilers.

A grande vantagem disso tudo é que, com uma única sintaxe, você pode escrever textos que ficam bem tanto no GitHub quanto no Reddit, adaptando apenas alguns detalhes onde cada plataforma funciona de forma diferente. Aprenda as regras básicas Isso permite que você se movimente livremente em ambas as plataformas sem precisar reaprender nada do zero.

Títulos e estrutura do conteúdo

Uma das primeiras coisas que você usará são as cabeçalhosTanto no GitHub quanto no Reddit, eles são usados ​​para estruturar o texto em seções e subseções.

Em Markdown, um título é criado precedendo o texto com um a seis símbolos de cerquilha (#): um para um título de nível 1, dois para nível 2 e assim por diante até o nível 6. Por exemplo, em um arquivo README.md do GitHub, você poderia ter algo como: # Título principal, ## Seção, ### Subseção, etc.

Quando o GitHub encontra dois ou mais cabeçalhos em um arquivo, ele gera automaticamente um tabela de conteúdo Acessível através do ícone "Estrutura de tópicos" na parte superior do arquivo. Cada título aparece como um link que leva você diretamente à respectiva seção, o que é ótimo para documentos longos.

Além disso, cada título se torna uma âncora interna que você pode vincular com um trecho de URL baseado no texto do título. Para gerar esse trecho, o GitHub aplica regras muito específicas: converte letras para minúsculas, substitui espaços por hífens, remove pontuação e caracteres de formatação (como itálico), elimina espaços em excesso e, se o resultado corresponder a outro título anterior, adicionar sufixo numérico (-1, -2, etc.) para torná-lo único.

Isso permite que você faça coisas como inserir uma seção. ## Seção de Amostra e depois crie um link para ele a partir de outro ponto do documento com um link como este: (#seção-de-exemplo)ou até mesmo criar links para seções com caracteres especiais no título, já que o GitHub gera o snippet seguindo essas regras e o torna acessível com o mesmo padrão.

Ênfase, texto destacado e citações.

O Markdown permite destacar texto usando vários métodos. ênfaseNegrito, itálico, tachado, subscrito, sobrescrito ou sublinhado. No GitHub, a tabela de estilos típica seria algo assim, embora a tenhamos resumido aqui com outras palavras:

Para inserir texto em negritoO texto em negrito é delimitado por dois asteriscos ou dois sublinhados; para itálico, usa-se um asterisco ou um sublinhado; para riscar algo, coloca-se um til duplo (dois tils) em cada lado do texto. Negrito e itálico aninhados também podem ser combinados, três asteriscos podem ser usados ​​para aplicar ambos a uma seção inteira do texto, ou tags HTML como <br> podem ser usadas. _{y ^{para subscritos e sobrescritos, e para sublinhar.}}

O GitHub também permite que você crie citações em estilo bloco Ao inserir o símbolo de maior que (>) no início da linha, o texto citado é exibido com uma barra vertical à esquerda e em cinza, destacando-se claramente. É possível incluir várias linhas no mesmo bloco de citação, e as citações podem até ser aninhadas adicionando mais símbolos > no início.

Uma forma avançada de citação que existe apenas no GitHub são as alertas ou advertênciasEles são baseados na mesma sintaxe de citação em bloco, mas a primeira linha inclui um marcador especial para indicar o tipo de alerta. Por exemplo, você pode especificar `<alert>` para informações úteis, `<helpful tips>` para conselhos práticos, `<key data>` para dados importantes, `<urgent notices>` para avisos urgentes e `<alert>` para avisos de riscos ou consequências negativas. O GitHub exibe cada tipo com uma cor e um ícone diferentes, ajudando a destacar informações críticas na documentação.

O Reddit também suporta citações simples com o mesmo símbolo >, embora não possua o sistema de alertas avançado do GitHub. Mesmo assim, continua sendo uma maneira muito útil de Responder a alguém citando parte da mensagem dessa pessoa. sem repeti-lo na íntegra.

Realce de código, blocos e cores.

Tanto o GitHub quanto o Reddit permitem destacar trechos de código dentro do texto usando crases (``). Para código embutido, você envolve a palavra ou o comando com uma crase de cada lado. Isso é ideal para destacar, por exemplo, um trecho de código. status git dentro de uma frase, deixando claro que se trata de uma ordem.

Quando você deseja um bloco de código independente, o Markdown usa três crases: você escreve uma linha com três crases, depois o código em linhas separadas e finaliza com mais três crases. No GitHub, se você também especificar o idioma logo após a primeira crase, ele será aplicado... realce de sintaxe com cores e formato específicos para esse idioma.

O GitHub também oferece um recurso específico para destacar valores de cor entre crases. Se você escrever uma cor em formato hexadecimal, RGB ou HSL entre crases, a plataforma inclui um pequeno indicador de cor ao lado do texto. Por exemplo, se o fundo no modo claro for #ffffff e no modo escuro for #000000, destacar esses códigos permite que você veja rapidamente qual é qual.

Em relação à visualização de código e tabelas, o GitHub permite ativar uma fonte monoespaçada fixa em todos os campos de comentários para tornar o trabalho com texto técnico mais confortável. Se você edita muitos trechos de código no navegador ou em editores como... Visual Studio CodeHabilitar essa opção facilita o alinhamento e a leitura. muito mais coerente.

O Reddit também suporta blocos de código com crases (``), tanto em linha quanto em bloco, embora seu uso lá seja mais focado em pequenos trechos ou pseudocódigo do que em documentação longa como a de um repositório.

Links, âncoras e navegação interna

Criar links em Markdown é muito simples: basta colocar o texto a ser exibido ao usuário entre colchetes e a URL entre parênteses. Isso funciona tanto no GitHub quanto no Reddit e pode ser aprimorado com atalhos de teclado no GitHub (por exemplo, usando combinações de teclas para converter rapidamente o texto selecionado em um link).

O GitHub adiciona alguns recursos extras relacionados à navegação. Por exemplo, ele permite link direto para os títulos utilizando as regras de geração de fragmentos discutidas anteriormente. Além disso, suporta links relativos dentro do próprio repositório, o que é crucial em documentação técnica.

Um link relativo é aquele calculado usando o arquivo atual como referência. Por exemplo, se o seu arquivo README estiver na raiz do projeto e você quiser criar um link para o arquivo docs/CONTRIBUTING.md, basta criar um link com o caminho docs/CONTRIBUTING.md. O GitHub lida com a tradução correta desse link relativo em qualquer branch em que você esteja, evitando que ele seja quebrado ao trocar de branch ou clonar o repositório.

A recomendação é sempre usar caminhos relativos Para navegar entre arquivos dentro do mesmo repositório, já que links absolutos podem parar de funcionar em clones ou forks, o GitHub permite o uso de operadores padrão como ./ ou ../ e caminhos que começam com / relativos à raiz do projeto.

Se você deseja criar pontos de ancoragem personalizados em um documento, além dos títulos, pode usar tags HTML com o atributo `name`. Isso permite posicionar um ponto de destino no meio de um parágrafo ou próximo a um texto sem título próprio e criar um link para ele usando a mesma sintaxe dos títulos gerados automaticamente.

Imagens no GitHub: Markdown, HTML e caminhos relativos

No GitHub, as imagens geralmente são incorporadas usando a mesma sintaxe dos links, mas precedidas por um ponto de exclamação. O texto alternativo (alt) é especificado entre colchetes e a URL ou o caminho para a imagem é colocado entre parênteses. Esse texto alternativo é importante para a acessibilidadePorque é isso que os leitores de tela vão ler e o que será exibido se a imagem não carregar.

As imagens podem vir de arquivos dentro do próprio repositório ou de URLs externas. O GitHub permite vários padrões de caminho relativo para o upload de imagens de diferentes branches, outros repositórios ou até mesmo issues e comentários, usando sufixos como ?raw=true Para forçar o download direto do arquivo quando necessário.

Além da sintaxe Markdown padrão, o GitHub suporta o uso do elemento HTML Este item é especialmente útil para carregar imagens responsivas Essas cores mudam de acordo com as preferências de tema do usuário (claro ou escuro). Usando a media query `prefers-color-scheme`, você pode definir diferentes fontes de imagem para cada modo e uma imagem padrão para navegadores que não suportam esse recurso.

O padrão típico envolve incluir dentro de vários elementos com seus atributos media e srcset e, finalmente, um Utilizando o atributo alt e uma URL genérica, os usuários no modo escuro veem uma imagem adaptada, enquanto aqueles no modo claro recebem uma diferente, sem a necessidade de duplicar o conteúdo no arquivo README.

O GitHub também oferece suporte a comentários HTML em arquivos Markdown, permitindo adicionar lembretes invisíveis ao leitor, por exemplo, para lembrá-lo de atualizar uma seção de imagens ou adicionar novos exemplos posteriormente.

Tabelas, seções desdobráveis ​​e separação de conteúdo.

Uma das melhorias mais úteis no GitHub Flavored Markdown é o seu suporte para desenharVocê pode organizar os dados em linhas e colunas usando barras verticais para separar as células e uma linha tracejada para marcar o cabeçalho. Você também pode alinhar as colunas à direita, à esquerda ou ao centro usando dois pontos na linha separadora.

As tabelas são muito úteis para apresentar listas de linguagens de programação, frameworks utilizados, tarefas planejadas, comparações de recursos ou qualquer outra informação que se beneficie de uma estrutura matricial. O GitHub renderiza essas tabelas com um estilo limpo e legível.

Para manter um arquivo README longo organizado, você pode usar a tag HTML para criar seções recolhíveis. Essas seções exibem um resumo dentro do rótulo. e permitir que o usuário expanda ou contraia Conteúdo adicional conforme necessário. É comum incluir tabelas ou blocos de informações secundárias dentro de Para evitar sobrecarregar a visão.

Se você deseja que a seção apareça expandida por padrão, basta adicionar o atributo open ao Essa técnica é muito prática para agrupar rankings, listas extensas ou conteúdo que não é essencial para uma primeira leitura, mas que é conveniente ter à mão.

Outra ferramenta simples para organizar informações é a régua horizontal. Ela é criada desenhando três ou mais traços em uma linha e serve para traçar uma linha divisória entre seções, permitindo separar claramente, por exemplo, uma seção descritiva de uma seção de referências ou notas adicionais.

Essas regras podem ser combinadas com citações no final do documento para destacar frases inspiradoras, lembretes ou mensagens-chave. Um exemplo típico seria inserir uma citação motivacional no final do seu arquivo README de perfil, formatada com uma citação em bloco após uma linha separadora.

Comentários ocultos e controle de formatação

O GitHub permite que você introduza Comentários HTML dentro do Markdown usando a sintaxe Tudo o que você colocar dentro desse comentário não será exibido no conteúdo renderizado, mas ficará visível no código-fonte, sendo ideal para anotações internas ou listas de tarefas.

Por exemplo, no arquivo README de um perfil, você pode adicionar um comentário dizendo algo como "você precisa expandir a seção 'Sobre mim' mais tarde" ou "você precisa revisar uma tabela de tecnologias obsoletas", sem que ninguém que visite o perfil veja isso diretamente.

Outra função útil é personagens de fuga que normalmente seria interpretado como Markdown. Se você precisar exibir asteriscos, símbolos de cerquilha (#) ou outros símbolos literalmente, sem formatação, basta preceder cada um com uma barra invertida (\). Isso permite, por exemplo, escrever expressões que incluem símbolos de lista sem convertê-los em listas propriamente ditas.

Ao visualizar um arquivo de marcação no GitHub, você tem a opção de alternar entre a visualização renderizada e o código-fonte com um botão na parte superior (ou abri-lo em editores como o Git). SuportesDesativar a interpretação de Markdown permite acessar recursos típicos de visualização de código, como: vincular linhas específicasIsso é muito útil quando você deseja apontar para uma parte exata de um arquivo README ou qualquer arquivo .md.

Por fim, lembre-se de que o GitHub lida com quebras de linha de forma diferente em comentários (issues, PRs, etc.) e em arquivos .md. Em comentários, as quebras de linha são respeitadas diretamente, enquanto em arquivos Markdown você precisa adicionar dois espaços no final da linha, uma barra invertida ou um ponto. Para forçar a mudança de parágrafo dentro do mesmo parágrafo.

Listas, listas aninhadas e listas de tarefas.

Listas são um dos elementos mais usados ​​em Markdown, tanto no GitHub quanto no Reddit. Você pode criar listas. desordenado Adicionando um hífen, asterisco ou sinal de mais antes de cada item da lista. Todas essas marcas são exibidas da mesma forma que os marcadores.

Para gerar listas ordenouCada linha é numerada com um número seguido de um ponto e um espaço. Embora a ordem dos números não precise ser perfeita (o GitHub geralmente recalcula), é uma boa prática manter uma numeração consistente para facilitar a leitura do código-fonte.

Listas aninhadas são criadas simplesmente adicionando recuo aos itens abaixo delas. Em editores monoespaçados como Texto SublimeBasta alinhar visualmente os marcadores da lista aninhada abaixo do primeiro caractere do texto no elemento pai. Em contextos como o editor de comentários do GitHub, onde a fonte não é monoespaçada, conte o número de caracteres antes do texto e use esse número de espaços para o recuo.

Você também pode criar vários níveis de aninhamento, desde que mantenha a consistência no número de espaços. Para listas muito complexas, esse sistema requer um pouco de prática, mas depois que você pega o jeito, é muito rápido de aplicar.

O GitHub também oferece o listas de tarefasEssas listas são muito úteis para problemas, solicitações de pull e documentação. Elas são criadas precedendo um hífen, um espaço e um par de colchetes com um espaço ou um "x" dentro: para tarefas pendentes e para tarefas concluídas. Essas listas são exibidas com caixas de seleção que podem ser marcadas ou desmarcadas na interface.

Se o texto de um item da lista de tarefas começar com parênteses, é necessário usar uma barra invertida para escapar os caracteres especiais e evitar confusão no analisador sintático. É um detalhe pequeno, mas importante ao escrever descrições que começam com algo como "(Opcional)" ou similar.

Menções, referências e emojis no GitHub

Uma das vantagens de escrever em Markdown no GitHub é poder usar menções Envie mensagens diretas para usuários e equipes na plataforma. Basta digitar @ seguido do nome de usuário ou nome da equipe, e o GitHub enviará uma notificação para essa conta, chamando a atenção dela para a conversa.

Ao digitar o símbolo @, o GitHub exibe uma lista de usuários e equipes associados ao repositório ou tópico, e você pode filtrar essa lista enquanto digita. Use as teclas de seta e pressione Enter ou Tab para aceitar as sugestões. Para equipes, use o formato @organização/nome-da-equipe, e todos os membros da equipe serão inscritos no tópico.

Além das menções, o GitHub facilita problemas de referência e solicitações de pull Basta digitar # seguido de um número ou parte do título. Uma lista de resultados sugeridos aparecerá, que você pode completar da mesma forma que com as menções. Isso agiliza bastante a navegação entre conversas relacionadas.

Se o seu repositório tiver referências com links automáticos personalizados configuradas, certas notações externas (como IDs de tickets do JIRA ou Zendesk) também podem ser convertidas automaticamente em links curtos. Essa configuração requer privilégios de administrador, mas, uma vez ativada, permite o compartilhamento de dados entre sistemas com o mínimo de esforço.

Por fim, o GitHub oferece suporte a emojis via código: digite dois pontos, seguidos pelo nome do emoji e finalize com outros dois pontos. Conforme você digita, uma lista de sugestões aparece, que você pode aceitar com a tecla Tab ou Enter. Incorporar emojis aos seus comentários ajuda a dar um toque mais humano a eles, desde que você não os utilize em excesso em documentação formal.

Notas de rodapé e conteúdo avançado

O GitHub também oferece suporte. Notas de rodapé Utilizando uma sintaxe baseada em colchetes e um identificador com um caractere intercalado. No ponto onde você deseja a referência, você insere algo como , e no final do documento você define o texto dessa nota com a mesma tag, seguida por dois pontos e o conteúdo.

As notas de rodapé podem abranger várias linhas e, para forçar quebras de linha dentro de uma nota de rodapé, são usados ​​espaços duplos no final da linha, assim como no corpo principal do Markdown. Ao renderizar, o GitHub exibe um sobrescrito no texto e uma lista de notas de rodapé no final, com links para navegar entre as referências e as notas de rodapé.

Outra funcionalidade avançada que o GitHub oferece é... alertas Esses elementos já foram discutidos (NOTA, DICA, IMPORTANTE, AVISO e CUIDADO). É aconselhável usá-los apenas quando realmente necessário e evitar encadeá-los em excesso para não sobrecarregar o leitor. Eles não podem ser aninhados dentro de outros elementos complexos, portanto, um planejamento cuidadoso de sua disposição é essencial.

Por fim, você pode solicitar ao GitHub que oculte temporariamente seções do Markdown renderizado, envolvendo-as em comentários HTML, ou que ignore o processamento de determinados caracteres com barras invertidas. Isso é especialmente útil ao documentar... Sintaxe própria do Markdown E você precisa mostrar os exemplos como eles são, sem interpretação.

Markdown no Reddit: Snoomark e modo de edição

O Reddit é uma plataforma de discussão onde quase qualquer tópico é bem-vindo, organizado em subreddits. Em termos de formatação, oferece dois editores: um para texto formatado, mais visual, e outro para texto simples baseado em Markdown. Se você quer trabalhar rapidamente e ter controle preciso sobre o resultado, a opção Markdown é a ideal.

Por padrão, o Reddit geralmente ativa o editor de texto rico, então para alternar para o modo de marcação você precisa clicar na opção. Modo Markdown dentro da caixa de texto de uma publicação ou comentário. A partir daí, você pode usar a sintaxe do Snoomark diretamente.

Se preferir que o editor Markdown seja sempre carregado, acesse as configurações do usuário, entre na seção Configurações do Feed e ative a opção. Usar Markdown por padrãoDessa forma, sempre que você começar a escrever uma postagem ou um comentário, o editor Markdown será aberto automaticamente, sem que você precise alterá-lo manualmente.

O Reddit suporta a maioria dos recursos básicos e avançados do Markdown: títulos, negrito e itálico, listas, citações, blocos de código, links e alguns recursos extras próprios, como spoilers. No entanto, apresenta deficiências significativas em comparação com o GitHub, especialmente em relação à formatação. gerenciamento de imagensO que depende bastante do contexto e do tipo de editor.

Sintaxe suportada pelo Reddit e spoilers

A variante do Snoomark usada pelo Reddit inclui muitos elementos em comum com o GitHub, então, se você já domina o Markdown para repositórios, transferir esse conhecimento para o ambiente do Reddit é bastante simples. Você pode usar títulos para estruturar posts longos, listas numeradas ou com marcadores, citações para responder a outros usuários e blocos de código quando quiser exibir comandos ou trechos técnicos.

Uma das diferenças notáveis ​​é a forma como o Reddit lida com o imagensEmbora em muitos casos as imagens sejam carregadas através da interface gráfica e não diretamente com a sintaxe Markdown, o mecanismo que processa o conteúdo de texto ainda é o Snoomark, portanto a formatação em torno dessas imagens é baseada em Markdown.

O Reddit, por outro lado, acrescenta itens adicionais que não fazem parte da especificação padrão, como spoilers. Estes permitem ocultar texto por trás de uma camada que o usuário pode revelar com um clique. Tecnicamente, quando o Reddit processa um spoiler, ele o transforma em uma combinação de HTML, classes CSS e JavaScript específico da plataforma.

A representação HTML resultante de um spoiler inclui manipuladores que controlam quando mostrar ou ocultar o conteúdo e, embora teoricamente algo semelhante pudesse ser escrito com HTML puro, no Reddit isso depende de sua implementação interna. O importante para você, como usuário, é que, ao escrever, você só precisa usar a sintaxe específica de spoiler fornecida pelo editor. Snoomark é o responsável pela tradução. à estrutura apropriada.

Em resumo, o Snoomark herda muitos comportamentos do GitHub Flavored Markdown, mas é voltado para as necessidades de uma comunidade de discussão em vez de documentação de projetos. Mesmo assim, a essência permanece a mesma: texto simples com símbolos básicos transformado em conteúdo estruturado e legível.

Dominar a sintaxe Markdown no GitHub e no Reddit torna a escrita de documentação técnica, a abertura de issues bem explicadas, a publicação de comentários claros em pull requests e a participação em discussões no Reddit muito mais eficientes. Com algumas regras-chave — títulos, ênfase, listas, citações, blocos de código, links, imagens e truques específicos como tabelas, detalhes recolhíveis, alertas, notas de rodapé e spoilers — você pode passar de escrever texto simples para criar Conteúdo limpo, fácil de consultar e profissional Sem tocar em um único botão do mouse.