byteTuto/website

Site amigável para agentes

Princípio: cada página HTML tem um gêmeo Markdown com conteúdo idêntico, e os agentes sabem como encontrá-lo. python3 scripts/check_seo_agents.py verifica todos os itens abaixo.

1. O gêmeo .md de cada página

Página HTML	Arquivo	URL do Markdown
site/index.html → /	site/index.md	/index.md
site/tutos/git-rebase/index.html → /tutos/git-rebase/	site/tutos/git-rebase/index.md	/tutos/git-rebase/index.md

Exceção: 404.html (sem gêmeo).

Ao criar ou modificar uma página, modifique os dois arquivos no mesmo commit. O .md não é um resumo: ele contém todo o conteúdo útil da página (texto, etapas, código, links), sem decoração.

Formato do .md:

---
title: Git rebase interativo em 3 minutos
description: Reescreva seus commits de forma limpa com git rebase -i, sem quebrar nada.
url: https://bytetuto.com/tutos/git-rebase/
lang: pt
updated: 2026-10-16
---

# Git rebase interativo em 3 minutos

> Resposta direta em 1-2 frases: o que a página ensina.

## Etapas
1. …

```bash
git rebase -i HEAD~3
```

## Veja também
- [Desfazer um commit](https://bytetuto.com/tutos/desfazer-commit/index.md)

Vídeo: https://www.youtube.com/watch?v=…

Regras:

• Front matter YAML com title, description, url (= canônico HTML), lang, updated (mesmos valores da página).
• Um único # título = o <h1>. Hierarquia ##/### idêntica ao HTML.
• Links absolutos (https://bytetuto.com/…), e para o .md quando o destino tiver um.
• Código em blocos ``` com a linguagem. Sem HTML bruto, sem emoji decorativo, sem imagem sem texto (![texto alternativo](url)).
• No HTML: <link rel="alternate" type="text/markdown" href="…/index.md"> dentro do <head>.

2. /llms.txt — o sumário para agentes

site/llms.txt, no formato llmstxt.org: # byteTuto, uma citação > que resume o site, depois seções ## com uma lista de links para os .md:

## Tutoriais
- [Git rebase interativo](https://bytetuto.com/tutos/git-rebase/index.md): reescrever seus commits de forma limpa.

Adicionar/remover a linha a cada página criada/excluída. Seção ## Optional para conteúdo secundário. Quando houver mais de ~10 tutoriais: gerar também site/llms-full.txt (todos os .md concatenados).

3. Servidor (já configurado em nginx/)

• .md servido como text/markdown; charset=utf-8, com X-Robots-Tag: noindex (sem conteúdo duplicado no Google — a versão HTML permanece a única indexada).
• Negociação de conteúdo: uma requisição com Accept: text/markdown em / ou /tutos/x/ recebe diretamente o .md (cabeçalho Vary: Accept no HTML).
• Teste:

  curl -s http://localhost:8088/index.md | head
  curl -s -H 'Accept: text/markdown' http://localhost:8088/ | head
  curl -sI http://localhost:8088/index.md | grep -i content-type   # text/markdown
  

4. HTML legível por um agente que navega

• Conteúdo presente no HTML inicial (não apenas renderizado em JS).
• Tags semânticas, <main> único, títulos hierárquicos, listas em <ol>/<ul>, código em <pre><code class="language-…">.
• Botões = <button>, links = <a href>; cada controle tem um nome acessível (texto visível ou aria-label).
• Formulários (newsletter): <label for> em cada campo, name e autocomplete explícitos, mensagem de resultado no DOM.
• Sem conteúdo atrás de interação obrigatória (abas ocultas: o conteúdo permanece no DOM).
• Dados estruturados JSON-LD atualizados (ver site-seo): os agentes também os utilizam.

5. Crawlers de IA (robots.txt)

Escolha do projeto: autorizamos crawlers de IA (visibilidade no ChatGPT, Claude, Perplexity, Google AI). Não adicionar Disallow para GPTBot, ClaudeBot, PerplexityBot, Google-Extended, etc. sem decisão explícita. Manter Sitemap: no final do arquivo.