arminazimi/slipway-content

Escreva páginas e postagens em um site Slipway

Um site Slipway consiste em arquivos Markdown com um bloco de front matter. Os layouts cuidam do resto: o título, o cabeçalho, o sumário, a data e o seletor de idioma. Você escreve o front matter a partir do esquema e as palavras em Markdown puro. Se o site tiver um arquivo AGENTS.md, leia-o primeiro; ele tem precedência onde diferir desta skill.

1. Faça uma linha de base

Obtenha as verificações do tema uma vez, em uma pasta fora do site:

git clone --depth 1 https://github.com/arminazimi/slipway "$HOME/.slipway"
cd "$HOME/.slipway" && npm ci && cd -

Execute a seção 6 antes de alterar qualquer coisa e mantenha a saída. Sua edição estará concluída quando ela não adicionar nenhum problema e nenhuma constatação a ela.

2. Escolha o layout e o arquivo

Você está escrevendo	layout	Arquivo
Uma página simples (sobre, contato)	page	<pasta>/<pagina>.md, servida em /<pasta>/<pagina>.html
Uma página de documentação com a barra lateral	doc	qualquer pasta, geralmente docs/<pagina>.md, com um permalink
Uma postagem com data	post	_posts/<data>-<slug>.md, onde <data> é AAAA-MM-DD
A página inicial	home	index.md

O nome do arquivo de uma postagem é sua data e seu endereço; para alterar o título, defina title, nunca renomeie o arquivo. Uma página doc aparece na barra lateral apenas quando a lista docs em _data/navigation.yml vincula seu permalink; adicione-a lá na ordem de leitura. Não crie search.json, feed.xml, sitemap.xml, 404.md, tags.md ou archive.md: eles já existem, e têm front matter e nenhum texto propositalmente.

Rascunhos, postagens agendadas e edições em uma postagem: um rascunho vai em _drafts/<slug>.md, sem data em seu nome — o GitHub Pages nunca compila _drafts/, e jekyll serve --drafts o pré-visualiza com a data de hoje. Uma postagem agendada é uma postagem normal cujo nome de arquivo AAAA-MM-DD está no futuro: o GitHub Pages a publica automaticamente nessa data, e jekyll serve --future a pré-visualiza antecipadamente, marcada como "Agendada" na página. Após uma edição substancial em uma postagem publicada, adicione updated: AAAA-MM-DD (no mesmo formato da data no nome do arquivo): a postagem mostra isso como "editado em", e o feed, o sitemap e os dados estruturados o relatam como a data da última modificação.

3. Preencha o front matter a partir do esquema

Cada chave, seu tipo e seus valores permitidos estão em reference/front-matter.md, gerado a partir dos esquemas que as verificações usam. Use apenas as chaves que ele lista para seu layout.

• title é obrigatório e não pode estar vazio. O layout o imprime como o cabeçalho da página.
• Adicione description: uma frase para resultados de busca e pré-visualizações de links.
• tags e categories são uma lista: tags: [release, notes].
• author em uma postagem é uma chave de _data/authors.yml, ou uma lista de chaves para vários autores: author: [ada, sam]. Se a chave estiver faltando nesse arquivo, adicione o autor lá primeiro.
• series em uma postagem a coloca em uma série: use o mesmo nome exato em todas as partes, series: Writing for the web. As partes são ordenadas por data.
• permalink começa com /. Deixe-o de fora em uma postagem no idioma padrão; a configuração do site define o endereço.
• Defina lang em uma página que não está no idioma padrão do site (lang em _config.yml), e em todas as páginas que têm uma tradução.
• Apenas home: cta_text e cta_url andam juntos, ou nada. variant escolhe a aparência: editorial (padrão), landing (adicione features, cada uma com um title), blog ou docs (cards da lista docs de _data/navigation.yml).
• Coloque entre aspas um valor que contenha : ou comece com um caractere que o YAML trate de forma especial ([, {, *, &, !, #, |, >, @, ou uma crase).

4. Escreva o corpo

• Apenas Markdown puro. Nunca Liquid: sem {{ }} e sem {% %}, nem mesmo em um bloco de código. Os layouts já adicionam o que o Liquid faria.
• Comece as seções em ##. O h1 é o título; um cabeçalho # no corpo cria um segundo.
• Mantenha os níveis de cabeçalho em ordem (##, depois ###), para que o sumário e o botão "Editar com seu agente" encontrem cada seção.
• Vincule a outras páginas pelo endereço, não pelo arquivo: [Instalação](/docs/install/), [Sobre](/about.html).
• As imagens ficam em assets/; dê a cada uma um texto alternativo: ![Um gráfico de tempos de compilação](/assets/build-times.png).
• Para uma página mais larga, defina width: narrow, wide ou full no front matter. Para alargar apenas um bloco (uma tabela, uma imagem, uma figura), envolva-o em um elemento HTML com a classe sl-wide (até 64rem) ou sl-bleed (borda a borda): <figure class="sl-wide"><img src="/assets/map.png" alt="Um mapa da rota"></figure>. O layout doc mantém as seções em sua coluna.
• Dê aos blocos de código uma linguagem (```yaml), para que sejam destacados e lidos da esquerda para a direita em uma página da direita para a esquerda.

Exemplos que passam nos esquemas:

• examples/doc-page.md: uma página doc.
• examples/post.md: uma postagem com tags.
• examples/post-fa.md: a mesma postagem em persa.

O primeiro comentário em cada um diz onde o arquivo vai.

5. Adicione uma tradução

1. O idioma deve estar em slipway.languages em _config.yml, com um code, um name e um prefix como /fa. Se estiver faltando, pergunte antes de adicionar um idioma: isso altera o seletor de todas as páginas.
2. Dê ao original uma translation_key se ele não tiver nenhuma, como plain-markdown, e seu lang (lang: en) se ele não tiver: o seletor encontra uma tradução por ambos. Dê à tradução a mesma translation_key. Isso vincula as duas no seletor de idioma e no sitemap.
3. Defina lang como o código do idioma, e permalink como um endereço sob o prefixo: /fa/plain-markdown/.
4. Onde o arquivo vai: uma página vai na pasta do prefixo (fa/about.md); uma postagem permanece em _posts/ com seu próprio slug (_posts/2026-10-20-plain-markdown-fa.md).
5. Traduza title, description, tags e o corpo. Mantenha layout, a data, o código, os comandos e as URLs como estão.
6. Se o site tiver um menu de cabeçalho para esse idioma (main_fa em _data/navigation.yml), adicione a página lá também.

Idiomas da direita para a esquerda (fa, ar, he, ur) recebem um layout da direita para a esquerda a partir de lang; não defina direction ou dir. Em texto persa, use o ی e ک persas (não o ي e ك árabes), um não separador de largura zero em palavras como می‌شود, e pontuação persa (، e ؟). Coloque comandos, nomes de arquivos e código entre crases: eles permanecem da esquerda para a direita dentro da frase.

6. Verifique a edição

A partir da pasta do site, verifique a configuração e o front matter de cada página em relação aos esquemas:

node "$HOME/.slipway/tools/theme/validate.mjs" .

Cada problema é impresso como arquivo:linha chave: mensagem (permitidos: ...). Corrija-o nessa linha, usando os valores permitidos, e execute novamente. Em seguida, compile o site, se ele tiver um Gemfile:

bundle exec jekyll build

Leia cada erro e aviso e corrija-o no arquivo que ele nomeia. Em seguida, execute o doctor na origem e na compilação. Ele verifica o site em relação à especificação editável pelo agente: AGENTS.md, content-schemas.json (quando o site tem um, ele valida seu front matter em relação aos esquemas que nomeia), o mapa de origem e os prompts de edição:

node "$HOME/.slipway/packages/doctor/bin/slipway.mjs" doctor . --build _site

Compare suas constatações com sua linha de base. Uma constatação que nomeie seu arquivo é sua para corrigir. Sem um Gemfile, execute o doctor sem --build e leia o log da compilação do Pages após o push.

Nunca

• Nunca coloque Liquid ({{ }} ou {% %}) em uma página.
• Nunca adicione uma chave de front matter que reference/front-matter.md não liste.
• Nunca altere translation_key em apenas uma tradução; altere todas as páginas que a compartilham, ou nenhuma.
• Nunca renomeie ou mova uma página ou postagem publicada para alterar seu título; defina title. Seu endereço é seu nome de arquivo ou permalink, e links para ele seriam quebrados.
• Nunca edite _site/, e nunca exclua uma página que tenha front matter e nenhum texto.
• Nunca edite layouts ou includes do tema para alterar a aparência de uma página.