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.
- 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.
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:
| Sintaxe | Vira |
|---|---|
# Title, ## Section | títulos (o GitHub monta um sumário a partir deles) |
**bold**, *italic*, `code` | formatação inline |
| Três crases mais o nome de uma linguagem | um 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 commit | links automáticos para issues, PRs e commits |
@mira, @dungeon-dash/artists | mençõ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:
- O que é isto? Uma ou duas frases, mais uma captura de tela ou um GIF se for algo visual.
- Como eu uso? A instalação e um exemplo mínimo que funcione quando copiado.
- Onde tem mais? Links para a documentação, o changelog, uma demonstração.
- 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.
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))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.
De CSV para uma tabela Markdown
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
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.
Progresso da lista de tarefas
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
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…