Carregando
0x20Lição 3 de 14

Markdown e ótimos READMEs

Escreva GitHub Flavored Markdown - títulos, listas de tarefas, tabelas, código, alertas e links para issues - e um README que as pessoas realmente leiam.

22 min Questionário com 7 perguntas 2 exercícios de código
Ao final desta lição, você saberá
  • Escrever GitHub Flavored Markdown, incluindo tabelas, listas de tarefas e alertas
  • Criar links para issues, pull requests, commits e pessoas com referências automáticas
  • Estruturar um README que faça novos usuários e contribuidores começarem rápido

Quase tudo o que você escreve no GitHub - READMEs, issues, pull requests, comentários, wikis - é Markdown: texto simples com um pouco de pontuação que é renderizado como texto formatado. O dialeto do GitHub, o GitHub Flavored Markdown (GFM), acrescenta tabelas, listas de tarefas e mais.

README.md
1# Dungeon Dash 🗡️
2
3A retro dungeon crawler with procedurally generated levels.
4
5## Quick start
6
71. Install Python 3.12
82. Run `pip install -r requirements.txt`
93. Start the game with `python -m dungeon_dash`
10
11## Roadmap
12
13- [x] Procedural dungeons
14- [x] Pixel-art hero
15- [ ] Boss battles (see #42)
16- [ ] Co-op mode
17
18| Key | Action |
19| --- | ------ |
20| WASD | Move |
21| Space | Attack |
22
23> [!WARNING]
24> Save files from 0.x won't load in 1.0.
25
26Made with ❤️ by @mira and @sam-sprites.

Destaques do GFM:

SintaxeVira
# Title, ## Sectiontítulos (o GitHub monta um sumário a partir deles)
**bold**, *italic*, `code`formatação inline
Três crases mais o nome de uma linguagemum bloco de código destacado
- [ ] / - [x]caixas de seleção de listas de tarefas - clicáveis em issues e contadas em barras de progresso
linhas | a | b |tabelas
> [!NOTE], > [!TIP], > [!WARNING]caixas de alerta coloridas
#42, mira/pixel-heroes#7, o SHA de um commitlinks automáticos para issues, PRs e commits
@mira, @dungeon-dash/artistsmenções que notificam uma pessoa ou uma equipe inteira
:tada:🎉 atalhos de emoji

Um README que funciona

Um README responde, em ordem, às perguntas de um visitante:

  1. O que é isto? Uma ou duas frases, mais uma captura de tela ou um GIF se for algo visual.
  2. Como eu uso? A instalação e um exemplo mínimo que funcione quando copiado.
  3. Onde tem mais? Links para a documentação, o changelog, uma demonstração.
  4. Como eu ajudo? Uma indicação do CONTRIBUTING.md, a licença e onde fazer perguntas.

Badges de status (pequenas imagens de status do build, versão, licença) no topo são opcionais, mas populares. Mantenha o README atualizado - um comando de instalação que não funciona é o jeito mais rápido de perder um novo usuário.

task_progress.py
1import re
2
3issue_body = """Boss battle checklist
4- [x] Design the dragon sprite
5- [x] Attack patterns
6- [ ] Victory music
7- [ ] Balance testing (see #57)
8"""
9tasks = re.findall(r"^\s*- \[( |x)\] (.+)$", issue_body, flags=re.MULTILINE)
10done = sum(1 for mark, _ in tasks if mark == "x")
11print(f"{done} of {len(tasks)} tasks complete")
12print("referenced issues:", re.findall(r"#(\d+)", issue_body))
Saída
2 of 4 tasks complete
referenced issues: ['57']

Principais conclusões

  • O GitHub Flavored Markdown move READMEs, issues, PRs e comentários.

  • Listas de tarefas, tabelas, alertas e blocos de código cercados são extras do GFM.

  • #42, owner/repo#7, SHAs de commits e @menções criam links e notificam automaticamente.

  • Um bom README diz o que o projeto é, como usá-lo, onde aprender mais e como ajudar.

Quiz da aula

7 perguntas · aprovação com 5 acertos · até 50 XP

Ao passar, você conclui a aula e mantém sua sequência. As perguntas erradas voltarão em sessões de revisão.

Pratique: automatize tarefas do GitHub com Python

O trabalho real no GitHub envolve muita automação pequena: conferir CODEOWNERS, expandir matrizes de build, atualizar versões, ler a API. Escreva esses utilitários em Python e execute-os com entradas de exemplo, localmente no navegador e sem precisar de conta no GitHub.

Exercício 1

De CSV para uma tabela Markdown

+25 XP

Os controles do jogo estão num arquivo CSV; o README precisa deles como uma tabela GFM. A primeira linha de entrada é o cabeçalho. Imprima uma tabela Markdown com cada coluna preenchida até a largura da célula mais larga (alinhada à esquerda) e uma linha separadora de traços com a mesma largura:

| Key   | Action |
| ----- | ------ |
| WASD  | Move   |
  • Controles
  • Vírgulas entre aspas
main.py
Carregando editor…

O Python é executado em um ambiente isolado no navegador, com limite de 60 segundos. O runtime é carregado pelo CDN do Pyodide; seu código permanece neste navegador.

Exercício 2

Progresso da lista de tarefas

+25 XP

A entrada é o corpo de uma issue em Markdown. Encontre os itens da lista de tarefas dela (linhas como - [ ] task ou - [x] task, possivelmente indentadas). Imprima progress: 2/5 (40%) (porcentagem arredondada para um número inteiro), depois cada tarefa não concluída como todo: task text e depois mentions: @a, @b - cada @menção distinta, na ordem em que aparece pela primeira vez - ou mentions: none.

  • Batalha contra o chefe
  • Tudo concluído
main.py
Carregando editor…

O Python é executado em um ambiente isolado no navegador, com limite de 60 segundos. O runtime é carregado pelo CDN do Pyodide; seu código permanece neste navegador.

Dúvidas sobre esta lição

Travou em algum ponto? Pergunte. Descobriu algo? Compartilhe. Explicar também é uma ótima forma de aprender.

Carregando publicações…