Como a documentação do NextPDF é estruturada

Visão geral

O manual do NextPDF segue um contrato fixo. Cada página tem um tópico, um modo Diataxis e um tipo de página. Cada tipo de página tem um conjunto obrigatório de títulos de nível 2. Um pequeno conjunto de manifestos e gates mantém a estrutura consistente à medida que o manual cresce.

Esta página descreve esse sistema para que você posicione sua contribuição corretamente. O contrato normativo completo, incluindo as listas exatas de títulos, as regras de citação e o procedimento de conexão de gates, está no documento de governança interno docs/style/expansion-standard.md. Leia esta página primeiro. Ao escrever, consulte esse documento.

Como escolher um tipo de página

Aplique estas regras em ordem para decidir se você deve adicionar uma página ou estender uma existente:

1. Se o material for um tópico distinto que um leitor não esperaria na página existente, adicione uma nova página.
2. Se o material completar um tópico que a página existente já contém, estenda essa página.
3. Se o material for um detalhe aprofundado que inflaria uma página de instalação, de início rápido ou de tarefa, mova-o para uma página separada e crie um link para ela.
4. Caso contrário, estenda a página existente.

Depois de confirmar que a página deve existir, defina o modo Diataxis dela. O modo determina o tipo de página:

• Tutorial orienta quem está aprendendo. Use um guia de tarefa escrito como uma receita.
• How-to ajuda um leitor competente a concluir uma tarefa. Use um guia de tarefa, um guia de API de servidor ou um guia de software development kit.
• Reference apresenta fatos exatos. Use uma referência de API ou uma página de índice.
• Explanation constrói entendimento. Use um guia de desenvolvedor ou um guia de recurso premium.

A linguagem simples é a base de todos os modos, não um modo separado.

O catálogo de tipos de página

O contrato do manual reconhece estes tipos. Reutilize um tipo existente sempre que a página incluir uma tabela de API. Introduza um novo tipo apenas de rótulo exclusivamente para uma página sem tabela de API.

• Tipos de índice: section-index, api-index, extension-index.
• Tipo de referência: api-reference. Reutilize-o para qualquer página com a tabela de API padrão, incluindo referências de servidor e do SDK Python.
• Tipo de explicação: developer-guide. Reutilize-o para texto sobre arquitetura, ciclo de vida e pontos de extensão, incluindo guias de servidor e do SDK Python.
• Novos tipos apenas de rótulo: premium-feature-guide e task-guide, ambos para páginas sem uma tabela de API.

Toda página começa com ## At a glance. Toda página api-reference inclui a tabela de API compartilhada e o título Development notes. Os títulos obrigatórios são títulos de nível 2, cada um em sua própria linha. Você pode adicionar mais títulos abaixo deles.

Checklist de escrita

Ao escrever uma página, atenda aos dois checklists. O padrão interno declara cada item de forma normativa e inclui um link para o padrão que o sustenta.

Facilidade para desenvolvedores:

• Extraia exemplos executáveis de examples/ ou tests/Cookbook e atribua a cada bloco delimitado uma info string title=.
• Declare os pré-requisitos no front-matter e na abertura.
• Mostre a saída esperada para qualquer exemplo que produza uma.
• Mantenha os blocos prontos para copiar e colar: uma linguagem por bloco, nomes completos no primeiro uso e nenhum caractere de prompt no final.
• Mostre código seguro por padrão: os exemplos de produção usam try/catch com a exceção mais específica do NextPDF e nunca um catch vazio.
• Termine com links de continuação e defina related: no front-matter.

Prontidão para tradução:

• Escreva uma ideia por frase para que a tradução automática continue delimitada.
• Mantenha títulos e rótulos curtos, porque a maioria dos idiomas de destino tende a ocupar mais espaço.
• Evite expressões idiomáticas.
• Mantenha nomes de símbolos, chaves de configuração, flags de CLI e nomes de exceção em formatação de código; nomes de padrões como PDF/A-4, PAdES e eIDAS nunca são traduzidos.
• Defina i18n_ready e xliff_segments de forma honesta e escreva em Unicode NFC.

Para estilo de voz, exemplos de código, terminologia e citação, siga a folha ratificada de override de estilo referenciada pelo padrão interno.

Conexão de gates

Conecte uma nova página usando este procedimento ordenado:

1. Crie o esqueleto da página para que o front-matter dela corresponda ao schema do site.
2. Escreva o corpo de acordo com os títulos obrigatórios do tipo de página.
3. Adicione uma entrada { path, owner, kind, headings[] } em docs/manual-contract.json. O caminho é relativo a src/content/docs, usa barras normais e não contém barra inicial nem ...
4. Para uma referência de API, adicione os símbolos da página a docs/api-coverage-manifest.json; cada símbolo deve aparecer na página e existir no código-fonte.
5. Atualize docs/source-manifest.json somente quando a página vier de um novo repositório de origem.
6. Adicione a página ao grupo correto da barra lateral em astro.config.mjs como uma entrada explícita.
7. Adicione uma linha de cobertura de locale com todas as dezessete células de locale definidas como missing para uma página somente em inglês.
8. Execute os gates de documentação, o build e o orçamento de desempenho.

As páginas pertencentes ao site ficam em src/content/docs, definem owner como nextpdf-docs e nunca carregam um marcador de agregação. As páginas agregadas vêm de um repositório de origem. A flag de publicação delas fica no front-matter da origem, então você as edita lá, não aqui.

Veja também

• Integrations: o maior exemplo prático da estrutura do manual em múltiplos pacotes.
• O documento de governança interno docs/style/expansion-standard.md contém o contrato completo: as listas exatas de títulos para cada tipo de página, as regras de citação e o procedimento completo de conexão de gates.