Guia de início rápido de gravação no GitHub

Aprenda os recursos avançados de formatação criando um README para seu perfil do GitHub.

Quem pode usar esse recurso?

O Markdown pode ser usado na interface Web do GitHub.

Neste artigo

Introdução

O Markdown é uma linguagem fácil de ler e de gravar para formatar texto sem formatação. Você pode usar a sintaxe Markdown, juntamente com algumas marcas HTML adicionais, para formatar a gravação em GitHub, em locais como LEIAMEs do repositório e comentários sobre pull requests e issues. Neste guia, você aprenderá alguns recursos avançados de formatação ao criar ou editar um README do seu perfil do GitHub.

Se você é novo no Markdown, talvez queira começar com Sintaxe básica de escrita e formatação ou o curso Comunicar usando Markdown do GitHub Skills.

Se você já tiver um README do perfil, poderá seguir este guia adicionando alguns recursos ao README existente ou criando um gist com um arquivo Markdown chamado algo como about-me.md. Para saber mais, confira Criar gists.

Como criar ou editar seu perfil README

Seu perfil no README permite compartilhar informações sobre você com a comunidade em GitHub. O README é exibido na parte superior da página de perfil.

Se você ainda não tem um README de perfil, pode adicionar um.

  1. Crie um repositório com o mesmo nome que o do usuário do GitHub, inicializando o repositório com um arquivo README.md. Para saber mais, confira Gerenciar o README do seu perfil.
  2. Edite o arquivo README.md e exclua o texto do modelo (começando com ### Hi there) que é adicionado automaticamente quando você cria o arquivo.

Se você já tem um LEIAME de perfil, edite-o na página de perfil.

  1. No canto superior direito de qualquer página, clique na imagem do seu perfil e em Your profile.

  2. Clique no ao lado do LEIAME do perfil.

    Captura de tela do LEIAME do perfil de @octocat. Um ícone de lápis contornado com laranja escuro.

Como adicionar uma imagem adequada para os visitantes

Você pode incluir imagens em sua comunicação no GitHub. Aqui, você adicionará uma imagem responsiva, como um banner, à parte superior do README do perfil.

Usando o elemento HTML <picture> com o recurso de mídia prefers-color-scheme, você pode adicionar uma imagem que muda de acordo com o modo claro ou escuro usado pelo visitante. Para saber mais, confira Gerenciar as configurações de temas.

  1. Copie e cole a seguinte marcação no seu arquivo README.md.

    HTML
    <picture>
 <source media="(prefers-color-scheme: dark)" srcset="YOUR-DARKMODE-IMAGE">
 <source media="(prefers-color-scheme: light)" srcset="YOUR-LIGHTMODE-IMAGE">
 <img alt="YOUR-ALT-TEXT" src="YOUR-DEFAULT-IMAGE">
</picture>

  2. Substitua os espaços reservados na marcação pelas URLs das imagens escolhidas. Como alternativa, para experimentar o recurso primeiro, copie as URLs do exemplo abaixo.

    • Substitua YOUR-DARKMODE-IMAGE pela URL de uma imagem a ser exibida para visitantes que usam o modo escuro.
    • Substitua YOUR-LIGHTMODE-IMAGE pela URL de uma imagem a ser exibida para visitantes que usam o modo claro.
    • Substitua YOUR-DEFAULT-IMAGE pela URL de uma imagem a ser exibida caso nenhuma das outras imagens seja correspondida, por exemplo, se o visitante estiver usando um navegador sem suporte ao recurso prefers-color-scheme.

  3. Para tornar a imagem acessível a visitantes que estejam usando um leitor de tela, substitua YOUR-ALT-TEXT por uma descrição da imagem.

  4. Para verificar se a imagem foi renderizada corretamente, clique na guia Visualização.

Para obter mais informações sobre como usar imagens no Markdown, confira Sintaxe básica de escrita e formatação.

Exemplo de uma imagem responsiva

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/25423296/163456776-7f95b81a-f1ed-45f7-b7ab-8fa810d529fa.png">
  <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
  <img alt="Shows an illustrated sun in light mode and a moon with stars in dark mode." src="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
</picture>

A aparência da imagem

Captura de tela da guia "Visualização" de um comentário do GitHub, no modo claro. Uma imagem de um sol sorridente preenchendo a caixa.

Como adicionar uma tabela

Você pode usar tabelas Markdown para organizar informações. Aqui, você usará uma tabela para se apresentar classificando algo, como as linguagens ou as estruturas de programação que você mais usa, o que está aprendendo no momento ou seus hobbies favoritos. Quando uma coluna de tabela contém números, é bom alinhar a coluna à direita usando a sintaxe --: abaixo da linha de cabeçalho.

  1. Retorne à guia Editar arquivo .

  2. Para se apresentar, duas linhas abaixo da tag </picture>, adicione um cabeçalho ## About me e um parágrafo curto sobre você, como o seguinte.

    ## About me

Hi, I'm Mona. You might recognize me as GitHub's mascot.

  3. Duas linhas abaixo desse parágrafo, insira uma tabela copiando e colando a marcação a seguir.

    Markdown
    | Rank | THING-TO-RANK |
|-----:|---------------|
|     1|               |
|     2|               |
|     3|               |

  4. Na coluna à direita, substitua THING-TO-RANK por "Idiomas", "Hobbies" ou qualquer outra coisa, e preencha a coluna com sua lista de itens.

  5. Para verificar se a tabela foi renderizada corretamente, clique na guia Visualização.

Para saber mais, confira Organizar informações com tabelas.

Exemplo de uma tabela

## About me

Hi, I'm Mona. You might recognize me as GitHub's mascot.

| Rank | Languages |
|-----:|-----------|
|     1| JavaScript|
|     2| Python    |
|     3| SQL       |

Aparência da tabela

Captura de tela da aba "Visualizar" de um comentário do GitHub. Sob o título "Sobre mim", há uma tabela renderizada com uma lista classificada de linguagens.

Com adicionar uma seção recolhida

Para manter o conteúdo organizado, você pode usar a tag <details> para criar uma seção recolhida expansível.

  1. Para criar uma seção recolhida na tabela que você criou, coloque-a entre tags <details>, como no exemplo a seguir.

    HTML
    <details>
<summary>My top THINGS-TO-RANK</summary>

YOUR TABLE

</details>

  2. Entre as tags <summary>, substitua THINGS-TO-RANK pelo item que você classificou na tabela.

  3. Opcionalmente, para que a seção seja exibida como aberta por padrão, adicione o atributo open à tag <details>.

    <details open>

  4. Para verificar se a seção recolhida foi renderizada corretamente, clique na guia Visualização.

Exemplo de uma seção recolhida

<details>
<summary>My top languages</summary>

| Rank | Languages |
|-----:|-----------|
|     1| JavaScript|
|     2| Python    |
|     3| SQL       |

</details>

Como a seção colapsada parece

Captura de tela da guia "Visualização" de um comentário. À esquerda das palavras "Principais linguagens" está uma seta indicando que a seção pode ser expandida.

Como adicionar uma citação

O Markdown tem muitas outras opções para formatar o conteúdo. Aqui, você adicionará uma linha horizontal para dividir a página e um blockquote para formatar sua citação favorita.

  1. Na parte inferior do arquivo, duas linhas abaixo da tag </details>, adicione uma regra horizontal digitando três ou mais traços.

    ---

  2. Abaixo da linha ---, adicione uma citação digitando a marcação como a seguir.

    > QUOTE

    Substitua QUOTE por uma citação da sua escolha. Como alternativa, copie a citação do exemplo abaixo.

  3. Para verificar se tudo foi renderizado corretamente, clique na guia Visualização.

Exemplo de uma citação

---
> If we pull together and commit ourselves, then we can push through anything.

— Mona the Octocat

Aparência da citação

Captura de tela da aba "Visualizar" de um comentário do GitHub. Uma aspa é recuada abaixo de uma linha horizontal grossa.

Como adicionar um comentário

Você pode usar a sintaxe de comentário HTML para adicionar um comentário que ficará oculto na saída. Aqui, você adicionará um comentário para se lembrar de atualizar o LEIAME mais tarde.

  1. Duas linhas abaixo do cabeçalho ## About me, insira um comentário usando a marcação a seguir.

    <!-- COMMENT -->

    Substitua COMMENT por um item "pendente" que você quer se lembrar de fazer mais tarde (por exemplo, adicionar mais itens à tabela).

  2. Para verificar se o comentário está oculto na saída, clique na guia Visualização.

Exemplo de um comentário

## About me

<!-- TO DO: add more details about me later -->

Salvando seu trabalho

Quando estiver satisfeito com as alterações, salve o README do seu perfil clicando em Commit changes.

Com a confirmação direta no branch main, suas alterações ficarão visíveis a qualquer visitante no perfil. Se você quiser salvar o trabalho, mas ainda não estiver pronto para deixá-lo visível no seu perfil, você pode selecionar Criar um novo branch para este commit e iniciar uma solicitação de pull.

Próximas etapas