Escribe guías y el changelog

El centro de ayuda en /help, las páginas de características en /features y las páginas legales son todos archivos de tu repositorio: Markdown para las guías y el changelog, Blade para las características. Nada se guarda en la base de datos y no hay editor. Esta guía te da los formatos exactos, las rutas que los muestran, los comandos que mantienen las traducciones al paso del inglés y lo que hace que una guía valga la pena leerse.

Dónde viven esas carpetas y por qué llevan el nombre de tu proyecto se explica en /help/make-it-your-own. Todo lo que sigue asume que config/app.php → project ya está definido, your-project en los ejemplos.

Dónde viven los archivos

docs/your-project/help/
├── guides/
│   ├── get-it-running.md          # fuente en inglés
│   └── es/
│       └── get-it-running.md      # español, mismo nombre de archivo
└── changelog/
    ├── 2026-09.md                 # un archivo por mes
    └── es/
        └── 2026-09.md

App\Classes\HelpDocuments los lee en cada petición, directo del disco, sin caché: guarda el archivo y recarga la página. Sólo se lee el primer nivel de cada carpeta; las carpetas de idioma guardan traducciones y nunca entran al listado por sí solas. Hay una carpeta de idioma por cada lengua en config/app.php → languages distinta de en, que de fábrica es es.

Una guía

El nombre del archivo es el slug: get-it-running.md es /help/get-it-running. Abre con un bloque de front matter y sigue en Markdown:

---
title: Get it running
summary: From a clone to a signed-in admin on your machine in one sitting.
category: getting-started
order: 10
---

The first sentence says what the guide covers and when you need it.

## First section

Un archivo sin bloque de front matter se ignora por completo. Los comentarios HTML del cuerpo se quitan antes de mostrarlo, que es como el comentario de huella se mantiene invisible.

Categorías

config/help.php lista las categorías que una guía puede declarar, con sus etiquetas en inglés; las vistas pasan las etiquetas por __(). El kit trae diez:

Una categoría sin guías se deja fuera de la página de guías, así que recortar la lista a lo que tu lector necesita nunca muestra un encabezado vacío. Una guía cuya category no está en la lista no aparece en la página de guías, aunque su URL sí abre. config/ es tuyo, así que la lista sobrevive a cada merge de la base.

Qué se muestra

El cuerpo pasa por help_markdown() en app/Helpers/base.php, que convierte el Markdown y pone las clases de Tailwind del centro de ayuda en cada elemento. Párrafos, encabezados ## y ###, listas con viñetas y numeradas, enlaces, negritas y cursivas, código en línea, bloques de código, citas, imágenes y líneas horizontales salen con estilo. No escribas un encabezado #: el título sale del front matter. Enlaza otras guías por su ruta pública, [Despliega tu proyecto](/help/deploy-your-project), y nunca por una ruta de archivo: el lector no tiene el repositorio abierto.

El changelog

Un archivo por mes, llamado YYYY-MM.md. Su front matter es una sola clave month — sin bloque de front matter el archivo se ignora — y cada entrada es un encabezado ## con la fecha y la hora en UTC, seguido de su Markdown:

---
month: 2026-09
---

## 2026-09-03 01:33

- The help centre is open. You can search the guides and read them in English
  or in Spanish. [Registration and access](/features/registration-and-access)

## 2026-09-01 15:10

- Web push notifications reach your phone with the site closed.

/help/changelog muestra primero el mes más reciente, ordenado por nombre de archivo, y dentro de él la entrada más reciente primero. Las entradas se agrupan por día y la hora se imprime como HH:mm, ambas después de convertir la marca UTC a la zona horaria del lector: la de la cuenta con sesión, o config/app.php → timezone para un visitante. Una entrada escrita a las 23:30 UTC cae en el día siguiente para un lector al este de Greenwich, a propósito. Un encabezado que no empieza con una fecha se salta, y un archivo de mes sin ninguna entrada válida también. La página carga un mes y ofrece Mostrar meses anteriores mientras haya más archivos.

Traduce un mes igual que una guía: changelog/es/2026-09.md, mismo front matter, las entradas traducidas, las marcas de tiempo sin tocar.

Traducciones

El archivo traducido tiene el mismo nombre dentro de la carpeta de idioma. Traduce title y summary; copia category y order tal cual. La traducción se fusiona sobre el documento en inglés clave por clave, así que una clave que la traducción omite conserva su valor en inglés. Una guía sin traducción al idioma del lector se muestra en inglés con un aviso sobre el cuerpo que lo dice, en lugar de esconderse.

Cada traducción lleva una huella del inglés desde el que se escribió, como comentario HTML bajo el front matter:

source es el hash del título, resumen y cuerpo en inglés; translated el de los propios de la traducción. Dos comandos la mantienen:

php artisan help:stamp           # reescribe el comentario en cada traducción
php artisan help:stamp --check   # reporta problemas y termina con error

Corre help:stamp después de escribir o actualizar una traducción. Nunca escribas el comentario a mano. --check reporta:

Cuando una traducción se corrigió a mano después de sellarla, help:stamp la vuelve a sellar y avisa que fue editada a mano; la corrección se conserva.

composer install corre git config core.hooksPath scripts/git-hooks, y el hook pre-push de ahí corre php artisan help:stamp --check, así que un push que enviaría una traducción faltante o desactualizada se detiene en tu máquina. Sáltalo una vez con git push --no-verify.

Las rutas

Las cuatro son públicas: quedan fuera del grupo guest, así que un usuario con sesión también las lee. El slug se compara contra los documentos encontrados, nunca se convierte en ruta de archivo, así que un ../ en la URL no alcanza nada. Las páginas usan resources/views/layouts/help.blade.php, un encabezado con el enlace al centro de ayuda, un enlace al sitio, un enlace al panel de usuario para un lector con sesión y el selector de idioma.

Páginas de características

/features es el lado de venta: lo que hace tu producto, una página por característica, escrita en Blade y no en Markdown. La lista es resources/views/landing/your-project/features.php:

return [
    [
        'slug' => 'your-account',
        'title' => 'Your account',
        'summary' => 'Keep your details, your alerts and your preferences the way you want them.',
        'icon' => 'user-circle',
        'order' => 20,
    ],
];

Cada entrada necesita una vista en resources/views/landing/your-project/features/{slug}.blade.php. Una entrada cuya vista no existe se deja fuera, así que puedes declarar la lista primero y escribir las páginas una por una. /features las lista (App\Livewire\Web\Features) y /features/{section} muestra una dentro de layouts/web.blade.php; una sección desconocida es un 404.

Construye una página con tres componentes:

<div>
    <x-landing.hero
        :title="__('Your account, the way you want it')"
        :promise="__('Your details and your preferences stay where you put them.')" />

    <section class="max-w-6xl mx-auto px-6 pb-8 space-y-24">
        <x-landing.block
            :title="__('Put a face to your account')"
            image="images/landing/your-project/features/your-account/profile.png"
            guide="/help/your-account-area"
            :guide-label="__('How to change your picture')">
            {{ __('Upload a picture from your profile and it appears everywhere your account does.') }}
        </x-landing.block>

        <x-landing.block :title="__('Keep the number where your codes arrive')" :reverse="true">
            {{ __('Change your phone whenever you switch lines.') }}
        </x-landing.block>
    </section>

    <x-landing.cta :title="__('Create your account and see for yourself')" />
</div>

Otros dos archivos en la misma carpeta pertenecen a la landing. home.blade.php es la página de inicio en /, obligatoria: mientras no exista, la página de inicio responde con un error que nombra el archivo a crear. nav-links.blade.php es opcional e imprime los enlaces de producto del menú público después de las entradas fijas Características y Ayuda; el pie de página público también enlaza Privacidad y Términos. Esas dos son resources/views/pages/privacy.blade.php y resources/views/pages/terms.blade.php, servidas en /privacy y /terms, públicas, con tu propio texto por escribir.

Escribe las páginas de características como páginas de venta, no como documentación: empieza por lo que la persona obtiene, una o dos frases cada una, en segunda persona y en presente. Cada cadena pasa por __() para poder traducirse en lang/. Mira /help/languages-and-translations.

Cómo escribir una buena guía

El lector es un desarrollador con prisa que compró tu producto y lo está instalando, configurando o desplegando, leyendo en el sitio público sin el repositorio abierto.

• Abre con una o dos frases que digan qué cubre la guía y cuándo se necesita. Luego las secciones. Termina cuando termine el contenido: sin conclusión, sin lecturas adicionales.
• Segunda persona, presente, frases cortas. "Pon APP_URL en tu dominio", no "el desarrollador debería configurar la URL".
• Nombra lo que el lector va a escribir: la ruta del archivo, la clave de configuración, la variable de entorno, la clase, el comando. Pon los comandos en bloques de código con lenguaje.
• Nunca mandes al lector a otro documento del repositorio. Si el dato importa, escribe el dato. Enlaza otra guía por su ruta pública cuando ayude.
• Documenta sólo lo que hace el código. Una opción que existe pero nada lee se escribe como tal. Usa datos inventados en los ejemplos: [email protected], your-project.test.
• Escribe primero el inglés, luego la traducción, y tradúcela completa: una traducción con párrafos en inglés adentro es peor que el aviso que el centro de ayuda muestra cuando falta. Corre php artisan help:stamp cuando las dos estén listas.
• Cada cambio que un usuario puede ver recibe su entrada en el changelog el mismo día que sale, en el idioma de quien la va a leer, con la hora en UTC.