O que você vai aprender#
- a estrutura que toda página segue;
- como adicionar uma página e onde ela aparece;
- as verificações que rodam no site, e as páginas que você não deve editar.
A ideia#
Um recurso não está terminado até a sua página existir. As páginas são arquivos MDX em site/content/docs/en/<dir>/<slug>.mdx; o arquivo em inglês é a fonte de verdade, e o arquivo em português do Brasil com o mesmo caminho é a sua tradução. A referência de comandos, as referências da CLI e da API HTTP, os códigos de erro e as variáveis de configuração são geradas a partir do código, então não podem divergir.
Início rápido#
- Crie
site/content/docs/en/<dir>/<slug>.mdxcom umtitlee umadescriptionno front matter. - Escreva as seções nesta ordem:
You will learn(páginas de guia e de primeiros passos),The idea(de duas a cinco frases, nas palavras do glossário),Quick start(passos numerados com o comando exato e o resultado),Common mistakes(cada um com o seu código de erro quando houver) eNext steps. - Mostre uma ação para cada superfície que a tem: a interface, o comando da CLI, a ferramenta MCP e os argumentos, e a chamada HTTP. Use os nomes das definições compartilhadas.
- Adicione o slug a
site/content/navigation.ts, na categoria da sua pasta. - Execute as verificações a partir de
site/:
npm run check:mdx
npm run build
npm run check:built
npm run lint
npm run check:command-mentions
npm run last-updatedAs regras de uma página#
- Os links são relativos à raiz, como
/docs/guide/exporting. Ocheck:mdxfalha em um link para uma página que não existe, e em um link para um título que não existe. - Nenhum
{ou<solto em prosa, nenhum HTML fora dos componentes MDX, linhas de código de no máximo 100 caracteres, e uma linguagem em todo bloco de código. - Código, nomes de comandos, opções, códigos de erro e identificadores ficam em inglês nos dois idiomas.
- Uma página de guia nomeia o comando que faz o que ela ensina, e todo comando que ela nomeia precisa existir (
check:command-mentions). - Nenhum texto de marketing e nenhuma afirmação de desempenho sem uma medição e a sua fonte.
- Um recurso que não está na versão publicada leva um aviso, que o pull request que o entrega remove.
Erros comuns#
- Editar uma página em
site/content/generated/: ela é sobrescrita pornpm run reference, e oreference:checkfalha em uma diferença. Mude o registro Go, o esquema ousite/scripts/generate-reference.ts, depois regenere. - Esquecer o
npm run last-updated: a verificação "Last updated" falha quando uma página é mais nova que a sua data registrada. - Linkar a página pt-BR pelo seu próprio caminho. Escreva o mesmo link
/docs/...nos dois idiomas; o site o reescreve para o português. - Descrever um recurso de memória. Confira a página contra o código e a especificação, e diga o que você não conseguiu verificar.