Markdown, YAML e README

Este capítulo ensina três textos que convivem com o HTML da Oficina Costeira: Markdown, YAML e o README. A Oficina Costeira é um coletivo fictício de design em João Pessoa. Este volume tem 52 capítulos. Esta é a 45.

O exemplo está em exemplos/45-markdown-yaml-readme/. Você já escreve HTML. Agora escreve um arquivo que pessoas e ferramentas leem sem abrir o navegador. Ciclo: ler, copiar, mudar uma coisa, prever, recarregar, conferir.

O que você vai aprender

• Distinguir Markdown (texto com marcas leves) de HTML (documento da página).
• Escrever título, lista, link e código em Markdown.
• Ler um bloco YAML como lista de nomes e valores.
• Montar um README.md útil, sem dado pessoal.
• Entender front-matter como capa do arquivo, não como página publicada.
• Abrir o README no editor e no GitHub sem publicar o exercício.

Markdown não substitui o HTML da página

Markdown é um jeito de escrever texto com poucos sinais: # no título, - na lista, ` no código. Ferramentas convertem isso em HTML. Issues, wikis e README usam muito.

A página da Oficina Costeira continua em HTML. index.html não vira .md neste volume. Markdown entra nos arquivos que explicam o projeto para quem abre a pasta.

No editor, um README curto parece com isto (o # no começo da linha vira título só no Markdown, não no HTML da home):

• uma linha de título da Oficina Costeira;
• um parágrafo chamando o coletivo de fictício;
• uma lista com Início, Projetos e Equipe.

Isso não é um site. É um recado. Se você precisa de lang="pt-BR", skip-link e aria-current, volte para o HTML.

Mude só a linha do título para # Oficina Costeira — estudo. Preveja o título maior quando o Markdown for visto como prévia. Recarregue a prévia no editor, se houver. Confira. A home index.html não muda, porque são arquivos diferentes.

Erro comum: salvar a home como index.md e esperar que o navegador desenhe o site. O navegador abre HTML. Markdown cru aparece como texto.

Sintaxe que você vai usar de verdade

Parágrafos: linhas de texto com uma linha em branco no meio.

Títulos: # no começo. Um # é o título do documento. ## é seção. Não pule de # para ### sem motivo.

Títulos de seção no Markdown usam dois # e um espaço. Listas numeradas usam 1. como no HTML do capítulo. Ênfase forte usa dois asteriscos. Exemplo de recado:

1. Abra index.html no navegador.
2. Ou sirva a pasta em 127.0.0.1.

O formulário de contato não envia mensagem.

Ênfase: *itálico* ou _itálico_. Forte: **negrito**.

Link: [texto](https://exemplo.invalid). Imagem: ![texto alternativo](/g/III-a-web-aberta/o1-marca.png).

Código na frase fica entre crases: o nome index.html assim. Bloco de código usa três crases numa linha, o nome da linguagem (html ou css), o código, e três crases para fechar. Não cole HTML longo no README se uma lista resolve. O README se lê em um minuto.

Se precisar mostrar um documento, cite só a linha que importa: html lang="pt-BR" no index.html, não o arquivo inteiro.

Mude só um item da lista para incluir Agenda. Preveja quatro itens. Recarregue a prévia. Confira.

Erro comum: título com #Titulo colado na palavra. Precisa de espaço: # Título.

YAML é nome: valor

YAML é um formato de dados em texto. Linhas chave: valor. Recuo com espaços, nunca com tab, quando há aninhamento. Comentário começa com #.

A Oficina Costeira pode descrever o projeto assim, só para estudo:

projeto: Oficina Costeira
cidade: João Pessoa
ficticio: true
paginas:
  - index.html
  - projetos.html
  - equipe.html
  - agenda.html
  - contato.html
servidor:
  host: 127.0.0.1
  porta: 8769

Isso não vai para o navegador sozinho. Geradores estáticos (próximo volume) leem YAML para título, idioma e lista de arquivos. Você precisa reconhecer a forma, não decorar um programa.

Mude só porta: 8769 para 8770. Preveja: o recado do README e o comando do servidor precisam combinar, senão você abre a porta errada. Recarregue o texto. Confira. Não ligue o servidor ainda.

Erro comum: misturar tab e espaço no recuo. O arquivo vira erro silencioso ou rejeitado pela ferramenta.

O README é a porta da pasta

O arquivo se chama README.md, em maiúsculas. A convenção é antiga e deixa o arquivo no topo de muita listagem. GitHub mostra esse arquivo na capa do repositório.

O que entra no README da Oficina Costeira:

• título do projeto fictício;
• uma frase dizendo que o conteúdo é de estudo;
• como abrir (index.html ou 127.0.0.1);
• o que não fazer (publicar, 0.0.0.0, dado real);
• lista das páginas;
• licença, se o zip do volume já trouxer uma.

O que não entra:

• seu nome, telefone, e-mail pessoal;
• senha, token, chave;
• endereço de casa;
• print de conversa privada.

Personagens da equipe (Lina, Rui, Nara) já são fictícios. Não troque por colegas reais.

Oficina Costeira

Site de estudo. Coletivo fictício de design em João Pessoa.

Abrir

- Arquivo: index.html
- Teste local: python -m http.server 8769 --bind 127.0.0.1

Não publique. Não envie o formulário para a rede.

Na versão que você guarda de verdade, o título leva um # e a seção Abrir leva ##. Aqui o exemplo evita esses sinais na coluna zero para não confundir o sumário do capítulo.

Mude só a porta no README para a que você realmente usa. Preveja: quem ler o arquivo acerta o endereço. Recarregue a prévia. Confira se o comando ainda tem --bind 127.0.0.1.

Erro comum: README só com “em construção”. Quem abre a pasta não sabe o que clicar.

Front-matter: capa no topo do arquivo

Alguns geradores aceitam um bloco YAML no começo de um Markdown, entre três hífens. Isso se chama front-matter. É metadado: título, idioma, layout. Não é o texto visível da home.

---
title: Projetos da Oficina Costeira
lang: pt-BR
---

Três trabalhos inventados para treinar marcação.

Neste volume você não precisa de gerador para escrever o bloco. Só precisa reconhecê-lo. Se copiar um arquivo da internet e vir YAML no topo, não apague sem ler: pode ser a capa que a ferramenta espera.

O HTML publicado da Oficina Costeira continua com title no head. Front-matter não substitui lang="pt-BR" no documento da página.

Mude só lang: pt-BR para lang: en no rascunho do Markdown. Preveja: uma ferramenta poderia marcar o texto como inglês. Recarregue a prévia. Confira. Devolva pt-BR. O site em HTML não deve seguir o erro.

Erro comum: colar front-matter no index.html. HTML não é Markdown. O navegador mostra os hífens na página.

Conferir sem publicar

Abra exemplos/45-markdown-yaml-readme/README.md no editor. Leia em voz alta o primeiro parágrafo. Se uma pessoa estranha não souber abrir o exemplo, reescreva.

No Windows, a extensão precisa ser .md, não .md.txt. Ative extensões no Explorador.

Você pode ver o HTML do exemplo no navegador e o README no editor ao mesmo tempo. São camadas diferentes: página versus documentação.

python -m http.server 8769 --bind 127.0.0.1 --directory curso

http://127.0.0.1:8769/exemplos/45-markdown-yaml-readme/ mostra o site. O README não vira página sozinho nesse servidor simples, a menos que você abra o arquivo bruto. Isso é esperado.

Não publique o exercício. Não coloque URL pública no README como se o coletivo existisse de verdade.

Atividades

1. A home da Oficina Costeira deve ser um .md ou um .html neste volume? Por quê?
2. Corrija: #Projetos em Markdown. O que faltava?
3. No YAML, o recuo deve usar tab? Por quê?
4. Liste duas informações que um README da Oficina Costeira não deve trazer.
5. Front-matter no topo de um Markdown substitui o title do index.html?

Respostas comentadas

1. .html. A página precisa de documento HTML com lang="pt-BR". Markdown documenta a pasta e o repositório.
2. O espaço depois de #. Sem espaço muitos processadores não veem título.
3. Não. Recuo com espaços. Tab costuma quebrar o arquivo.
4. Dado pessoal do aluno, senha, telefone, endereço real. Também não invente o coletivo como empresa verdadeira.
5. Não. O title da aba vem do HTML da página. Front-matter é capa para ferramenta, não para o navegador deste exemplo.

Referências

• Markdown
• YAML
• Escrever documentação
• Elemento title

O arquivo completo

Referência do exemplo 45-markdown-yaml-readme, reproduzida aqui para que você possa conferir sem sair da página.

assets/javascript/simulacao.js

const form=document.querySelector("#simulacao");if(form){form.querySelector("button[type=submit]").disabled=false;form.addEventListener("submit",event=>{event.preventDefault();document.querySelector("#retorno").textContent="Simulação concluída. Nada foi enviado ou guardado.";});}