GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown (GFM) é a versão aprimorada do Markdown do GitHub com recursos adicionais projetados especificamente para desenvolvimento de software e colaboração. Este guia cobre todas as extensões de sintaxe especiais disponíveis no GitHub.

O que é GitHub Flavored Markdown (GFM)?

GitHub Flavored Markdown estende a sintaxe básica do Markdown com recursos que o tornam mais útil para:

• Documentação (READMEs, wikis)
• Rastreamento de issues
• Pull requests
• Revisão de código
• Gerenciamento de projetos

Principais Recursos do GFM

1. Blocos de Código Delimitados

O GFM suporta blocos de código delimitados com destaque de sintaxe específico do idioma:

```javascript
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15
```

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15

2. Destaque de Sintaxe

O GitHub suporta destaque de sintaxe para centenas de idiomas. Alguns comuns incluem:

# Script Bash
echo "Hello GitHub!"

# Script Python
def greet(name):
    return f"Hello, {name}!"

// Código Java
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello GitHub!");
    }
}

3. Listas de Tarefas

Crie listas de tarefas interativas com caixas de seleção:

- [x] Completar autenticação do usuário
- [x] Implementar endpoints da API
- [ ] Escrever testes unitários
  - [ ] Testes de backend
  - [ ] Testes de frontend
- [ ] Implantar em produção

• [x] Completar autenticação do usuário
• [x] Implementar endpoints da API
• [ ] Escrever testes unitários
  • [ ] Testes de backend
  • [ ] Testes de frontend
• [ ] Implantar em produção

4. Tabelas

O GFM fornece uma sintaxe simples para criar tabelas:

| Recurso           | Suportado | Descrição                        |
|-------------------|-----------|----------------------------------|
| Fenced Code       | ✅        | Destaque específico do idioma    |
| Task Lists        | ✅        | Caixas de seleção interativas    |
| Tables            | ✅        | Exibição de dados estruturados   |
| Mentions          | ✅        | Notificações de usuário e equipe |
| Emoji             | ✅        | Expressões visuais               |

Recurso	Suportado	Descrição
Fenced Code	✅	Destaque específico do idioma
Task Lists	✅	Caixas de seleção interativas
Tables	✅	Exibição de dados estruturados
Mentions	✅	Notificações de usuário e equipe
Emoji	✅	Expressões visuais

5. Menções

Mencione usuários ou equipes para notificá-los:

@username - Mencionar um usuário específico
@team-name - Mencionar uma equipe

6. Emoji

Adicione emoji usando shortcodes:

:smile: - 😊
:thumbsup: - 👍
:heart: - ❤️
:rocket: - 🚀
:warning: - ⚠️

😄 - 😊 👍 - 👍 ❤️ - ❤️ 🚀 - 🚀 ⚠️ - ⚠️

7. Link Automático

O GFM vincula automaticamente certos tipos de conteúdo:

Números de Issue e Pull Request

#123 - Links para issue 123
PR #456 - Links para pull request 456

Hashes SHA

a1b2c3d - Links para o commit com este SHA

Menções de Usuário em Issues/PRs

@username - Links automaticamente para o perfil do usuário

URLs

https://github.com - Automaticamente se torna um link

8. Tachado

O GFM suporta texto tachado:

~~Este texto está tachado~~

Este texto está tachado

9. Referências de Link Automático

O GFM cria links automaticamente para:

• URLs HTTP/HTTPS
• Endereços de e-mail
• Números de issue/PR do GitHub
• SHAs de commit

https://github.com/markdownlang/markdownlang.com
user@example.com
#123
PR #456
a1b2c3d4e5f6

10. Destaque de Linha em Blocos de Código

Destaque linhas específicas em blocos de código:

```javascript{2,4}
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);
```

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);

11. Destaque de Sintaxe Diff

Destaque alterações no código com sintaxe diff:

```diff
- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };
```

- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };

12. Marcação Específica do GitHub

Alertas

Use sintaxe especial para alertas na documentação do GitHub:

> [!NOTE]
> Este é um alerta de nota.

> [!TIP]
> Este é um alerta de dica.

> [!IMPORTANT]
> Este é um alerta importante.

> [!WARNING]
> Este é um alerta de aviso.

> [!CAUTION]
> Este é um alerta de cautela.

NOTE

Este é um alerta de nota.

TIP

Este é um alerta de dica.

IMPORTANT

Este é um alerta importante.

WARNING

Este é um alerta de aviso.

CAUTION

Este é um alerta de cautela.

Links Relativos

Use links relativos para navegar entre arquivos no mesmo repositório:

[README](/README.md)
[Diretrizes de Contribuição](/CONTRIBUTING.md)
[Documentação da API](/docs/api.md)

Links de Imagem com Texto de Passagem do Mouse

![GitHub Logo](/images/github-logo.png "GitHub Logo - Texto de Passagem do Mouse")

Uso Avançado do GFM

1. Listas Aninhadas com Listas de Tarefas

Combine listas aninhadas com listas de tarefas:

## Roadmap do Projeto

### Fase 1: Planejamento
- [x] Definir escopo do projeto
- [x] Identificar requisitos
  - [x] Requisitos funcionais
  - [x] Requisitos não funcionais
- [x] Criar cronograma

### Fase 2: Desenvolvimento
- [x] Configurar estrutura do projeto
- [ ] Implementar recursos principais
  - [x] Autenticação
  - [ ] Dashboard
  - [ ] Integração de API

2. Tabelas com Emoji e Links

Aprimore tabelas com emoji e links:

| Componente     | Status              | Mantenedor   |
|----------------|---------------------|--------------|
| Autenticação   | ✅ Estável          | @johndoe     |
| Banco de Dados | ⚠️ Precisa Atualizar | @janedoe     |
| API            | 🚧 Em Andamento     | @bobsmith    |
| UI             | ✅ Estável          | @alicesmith  |

Componente	Status	Mantenedor
Autenticação	✅ Estável	@johndoe
Banco de Dados	⚠️ Precisa Atualizar	@janedoe
API	🚧 Em Andamento	@bobsmith
UI	✅ Estável	@alicesmith

3. Blocos de Código em Listas

Inclua blocos de código em listas:

1. Instale as dependências:

   ```bash
   npm install

2. Execute o servidor de desenvolvimento:

   npm run dev

3. Build para produção:

   npm run build

### 4. Blocos de Citação com Código

Combine citações com blocos de código:

```markdown
> **Dica Profissional:** Use o seguinte comando para verificar rapidamente o status do Git:
>
> ```bash
> git status
> ```

Dica Profissional: Use o seguinte comando para verificar rapidamente o status do Git:

git status

GFM em Diferentes Contextos do GitHub

Arquivos README

Arquivos README suportam todos os recursos do GFM e são renderizados automaticamente nas páginas do repositório.

Issues e Pull Requests

• Use listas de tarefas para rastrear progresso
• Mencione membros da equipe para colaboração
• Inclua trechos de código com destaque de sintaxe
• Referencie issues/PRs relacionados usando a sintaxe #123

Comentários

• Use emoji para reações rápidas
• Referencie linhas no código com comentários de linha
• Use blocos de citação para responder a pontos específicos

Wikis

• Organize conteúdo com páginas aninhadas
• Use tabelas para dados estruturados
• Inclua exemplos de código com destaque de sintaxe

Melhores Práticas

1. Estilo de Código

<!-- ✅ Bom -->
```javascript
// Use nomes de função descritivos
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

function f(i){return i.reduce((a,b)=>a+b.p,0)}```

2. Design de Tabela

<!-- ✅ Bom -->
| Recurso | Descrição | Status |
|---------|-----------|--------|
| Recurso 1 | Breve descrição | ✅ |
| Recurso 2 | Outra descrição | 🚧 |

<!-- ❌ Evite -->
| Recurso | Descrição | Status | | | |
|---------|-----------|--------|---|---|---|
| Recurso 1 | Esta descrição é muito longa e torna a tabela difícil de ler em dispositivos móveis | ✅ | | | |

3. Uso de Lista de Tarefas

<!-- ✅ Bom -->
## Sprint Backlog
- [x] Completar página de perfil do usuário
- [ ] Implementar funcionalidade de busca
  - [x] API de Backend
  - [ ] Componente de Frontend
- [ ] Escrever documentação

<!-- ❌ Evite -->
- [ ] Tarefa 1
- [ ] Tarefa 2
- [ ] Tarefa 3
- [ ] Tarefa 4
- [ ] Tarefa 5
(Muitas tarefas sem organização)

GFM vs Markdown Padrão

Recurso	Markdown Padrão	GitHub Flavored Markdown
Blocos de Código Delimitados	❌	✅
Destaque de Sintaxe	❌	✅
Listas de Tarefas	❌	✅
Tabelas	❌	✅
Tachado	❌	✅
Emoji	❌	✅
Menções	❌	✅
Link Automático	Limitado	Extensivo

Ferramentas para Trabalhar com GFM

Editores Locais

• Visual Studio Code - Visualização GFM e extensões
• Typora - Renderização GFM em tempo real
• Mark Text - Suporte GFM

Ferramentas Online

• GitHub Gist - Crie e compartilhe trechos GFM
• Dillinger - Editor GFM online
• StackEdit - Suporte GFM com sincronização em nuvem

Ferramentas de Linha de Comando

• glow - Renderizador GFM de terminal
• pandoc - Converta GFM para outros formatos
• marked - Parser GFM para Node.js

Problemas Comuns e Correções

1. Bloco de Código Não Está Destacando

Problema: O bloco de código não está mostrando destaque de sintaxe

Correção: Certifique-se de especificar o idioma correto:

<!-- ✅ Correto -->
```javascript
console.log("Hello");

console.log("Hello"); // Usando jsx em vez de javascript para código não-JSX

### 2. Caixas de Seleção de Lista de Tarefas Não Funcionam

**Problema:** As caixas de seleção de lista de tarefas não são interativas

**Correção:** Certifique-se de usar a sintaxe correta (espaço entre `-` e `[ ]`):

```markdown
<!-- ✅ Correto -->
- [ ] Tarefa

<!-- ❌ Incorreto -->
-[ ] Tarefa (sem espaço)
-[x] Tarefa (sem espaço)

3. Tabela Não Está Sendo Renderizada Corretamente

Problema: As colunas da tabela estão desalinhadas

Correção: Certifique-se de que os pipes estão alinhados corretamente:

<!-- ✅ Correto -->
| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

<!-- ❌ Incorreto -->
|Column 1|Column 2|
|--|--|
|Data 1|Data 2|

Próximos Passos

• Aprenda sintaxe básica do Markdown
• Veja a folha de referência de sintaxe
• Pratique com GitHub Gist
• Leia a documentação oficial do GitHub GFM

---

GitHub Flavored Markdown é uma ferramenta poderosa para comunicação e colaboração no desenvolvimento de software. Ao dominar esses recursos, você pode criar documentação mais eficaz, rastrear melhor as issues e colaborar de forma mais eficiente com sua equipe.