arminazimi/slipway-content

Escribe páginas y publicaciones en un sitio Slipway

Un sitio Slipway consiste en archivos Markdown con un bloque de front matter. Los diseños se encargan del resto: el título, el encabezado, la tabla de contenido, la fecha y el selector de idioma. Escribe el front matter siguiendo el esquema y las palabras en Markdown plano. Si el sitio tiene un AGENTS.md, léelo primero; prevalece donde difiera de esta habilidad.

1. Toma una línea base

Obtén las comprobaciones del tema una vez, en una carpeta fuera del sitio:

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

Ejecuta la sección 6 antes de cambiar cualquier cosa y conserva la salida. Tu edición estará completa cuando no añada ningún problema ni hallazgo a la línea base.

2. Elige el diseño y el archivo

Estás escribiendo	layout	Archivo
Una página plana (acerca de, contacto)	page	<carpeta>/<pagina>.md, servida en /<carpeta>/<pagina>.html
Una página de documentación con barra lateral	doc	cualquier carpeta, a menudo docs/<pagina>.md, con un permalink
Una publicación con fecha	post	_posts/<fecha>-<slug>.md, donde <fecha> es YYYY-MM-DD
La página de inicio	home	index.md

El nombre de archivo de una publicación es su fecha y su dirección; para cambiar el título, establece title, nunca renombres el archivo. Una página doc se muestra en la barra lateral solo cuando la lista docs en _data/navigation.yml enlaza su permalink; agrégala allí en orden de lectura. No crees search.json, feed.xml, sitemap.xml, 404.md, tags.md o archive.md: ya existen, y tienen front matter y ningún texto a propósito.

Borradores, publicaciones programadas y ediciones de una publicación: un borrador va en _drafts/<slug>.md, sin fecha en su nombre — GitHub Pages nunca compila _drafts/, y jekyll serve --drafts lo previsualiza con la fecha de hoy. Una publicación programada es una publicación normal cuyo nombre de archivo YYYY-MM-DD está en el futuro: GitHub Pages la publica automáticamente en esa fecha, y jekyll serve --future la previsualiza antes, marcada como Programada en la página. Después de una edición sustancial a una publicación publicada, añade updated: YYYY-MM-DD (con el mismo formato que la fecha del nombre del archivo): la publicación muestra "editado el", y el feed, el mapa del sitio y los datos estructurados lo reportan como la fecha de última modificación.

3. Completa el front matter según el esquema

Cada clave, su tipo y sus valores permitidos están en reference/front-matter.md, generado a partir de los esquemas que usan las comprobaciones. Usa solo las claves que lista para tu diseño.

• title es obligatorio y no debe estar vacío. El diseño lo imprime como encabezado de la página.
• Añade description: una oración para resultados de búsqueda y vistas previas de enlaces.
• tags y categories son una lista: tags: [release, notes].
• author en una publicación es una clave de _data/authors.yml, o una lista de claves para varios autores: author: [ada, sam]. Si la clave falta en ese archivo, añade primero al autor allí.
• series en una publicación la coloca en una serie: usa exactamente el mismo nombre en cada parte, series: Escribir para la web. Las partes se ordenan por fecha.
• permalink comienza con /. Déjalo fuera en una publicación en el idioma predeterminado; la configuración del sitio establece la dirección.
• Establece lang en una página que no esté en el idioma predeterminado del sitio (lang en _config.yml), y en cada página que tenga una traducción.
• Solo para home: cta_text y cta_url van juntos, o ninguno. variant elige la apariencia: editorial (predeterminado), landing (añade features, cada uno con un title), blog o docs (tarjetas de la lista docs de _data/navigation.yml).
• Pon entre comillas un valor que contenga : o que comience con un carácter que YAML trata de manera especial ([, {, *, &, !, #, |, >, @ o una comilla invertida).

4. Escribe el cuerpo

• Solo Markdown plano. Nunca Liquid: no {{ }} ni {% %}, ni siquiera dentro de un bloque de código. Los diseños ya añaden lo que Liquid añadiría.
• Comienza las secciones con ##. El h1 es el título; un encabezado # en el cuerpo crea un segundo.
• Mantén los niveles de encabezado en orden (##, luego ###), para que la tabla de contenido y el botón "Editar con tu agente" encuentren cada sección.
• Enlaza a otras páginas por dirección, no por archivo: [Instalar](/docs/install/), [Acerca de](/about.html).
• Las imágenes viven en assets/; dale a cada una texto alternativo: ![Gráfico de tiempos de compilación](/assets/build-times.png).
• Para una página más ancha, establece width: narrow, wide o full en el front matter. Para ensanchar un solo bloque (una tabla, una imagen, una figura), envuélvelo en un elemento HTML con la clase sl-wide (hasta 64 rem) o sl-bleed (de borde a borde): <figure class="sl-wide"><img src="/assets/map.png" alt="Mapa de la ruta"></figure>. El diseño doc mantiene las secciones en su columna.
• Pon a los bloques de código un lenguaje (```yaml) para que se resalten y se lean de izquierda a derecha en una página de derecha a izquierda.

Ejemplos que pasan los esquemas:

• examples/doc-page.md: una página doc.
• examples/post.md: una publicación con etiquetas.
• examples/post-fa.md: la misma publicación en persa.

El primer comentario en cada uno indica dónde va el archivo.

5. Añadir una traducción

1. El idioma debe estar en slipway.languages en _config.yml, con un code, un name y un prefix como /fa. Si falta, pregunta antes de añadir un idioma: cambia el selector de todas las páginas.
2. Dale al original un translation_key si no tiene ninguno, como plain-markdown, y su lang (lang: en) si no tiene ninguno: el selector encuentra una traducción mediante ambos. Dale a la traducción el mismo translation_key. Eso las enlaza en el selector de idioma y en el mapa del sitio.
3. Establece lang al código de idioma y permalink a una dirección bajo el prefijo: /fa/plain-markdown/.
4. Dónde va el archivo: una página va en la carpeta del prefijo (fa/about.md); una publicación permanece en _posts/ con su propio slug (_posts/2026-10-20-plain-markdown-fa.md).
5. Traduce title, description, tags y el cuerpo. Mantén layout, la fecha, el código, los comandos y las URLs como están.
6. Si el sitio tiene un menú de encabezado para ese idioma (main_fa en _data/navigation.yml), añade allí la página también.

Los idiomas de derecha a izquierda (fa, ar, he, ur) obtienen un diseño de derecha a izquierda desde lang; no establezcas direction ni dir. En texto persa, usa la ی y ک persas (no la ي y ك árabes), un separador de ancho cero en palabras como می‌شود, y puntuación persa (، y ؟). Pon comandos, nombres de archivo y código entre comillas invertidas: permanecen de izquierda a derecha dentro de la oración.

6. Verifica la edición

Desde la carpeta del sitio, verifica la configuración y el front matter de cada página contra los esquemas:

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

Cada problema se imprime como archivo:línea clave: mensaje (permitido: ...). Corrígelo en esa línea, usando los valores permitidos, y ejecútalo de nuevo. Luego compila el sitio, si tiene un Gemfile:

bundle exec jekyll build

Lee cada error y advertencia y corrígelo en el archivo que nombra. Luego ejecuta el doctor sobre el origen y la compilación. Verifica el sitio contra la especificación editable por el agente: AGENTS.md, content-schemas.json (cuando el sitio tiene uno, valida tu front matter contra los esquemas que nombra), el mapa de origen y las instrucciones de edición:

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

Compara sus hallazgos con tu línea base. Un hallazgo que nombre tu archivo es tuyo para corregir. Sin un Gemfile, ejecuta el doctor sin --build y lee el registro de la compilación de Pages después de enviar.

Nunca

• Nunca pongas Liquid ({{ }} o {% %}) en una página.
• Nunca añadas una clave de front matter que reference/front-matter.md no liste.
• Nunca cambies translation_key en una sola traducción; cambia cada página que lo comparte, o ninguna.
• Nunca renombres o muevas una página o publicación publicada para cambiar su título; establece title. Su dirección es su nombre de archivo o permalink, y los enlaces a ella se romperían.
• Nunca edites _site/, y nunca elimines una página que tenga front matter y ningún texto.
• Nunca edites diseños o includes del tema para cambiar cómo se ve una página.