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 del disco y guarda en caché lo que analizó; la caché se renueva sola cada vez que cambia un archivo de ayuda, así que guardar el archivo y recargar la página sigue mostrando el cambio, sin correr ningún comando. 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.

Las guías genéricas

docs/project/help/ guarda un centro de ayuda escrito para el usuario de cualquier producto: guías sobre editar el perfil, qué cambia el país del perfil, planes, complementos y uso. Un proyecto sin carpeta docs/your-project/help/ lee esta en su lugar, sus guías y su changelog, sin nada que copiar ni configurar. Un proyecto con carpeta de ayuda propia lee sólo la suya, se llame como se llame, así que Weblabor Base, Weblabor Teams y Weblabor Builder nunca muestran estas. La carpeta sigue la misma estructura, con es/ para las traducciones, y un cambio en ella llega al centro de ayuda de la misma forma, sin caché que limpiar.

En cuanto creas tu propia carpeta de ayuda, las guías genéricas dejan de mostrarse. Copia a docs/your-project/help/guides/ las que quieras conservar, con sus traducciones, y edítalas como tuyas. Una guía genérica cuya categoría no declare tu config/help.php se comporta como lo haría una tuya: su URL abre y el índice la deja fuera.

Una guía

El nombre del archivo es el slug: get-it-running.md es /help/en/get-it-running. Cada página de ayuda lleva su idioma en la dirección, y cada traducción declara su propio slug, como explica Traducciones. Una guía 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, salvo dentro de un bloque de código, que es como el comentario de huella se mantiene invisible.

requires: plans es para una guía sobre suscripciones, que sólo confundiría al lector de un proyecto que no vende ninguna. La guía se muestra sólo mientras los planes están activos: FEATURE_PLANS_ENABLED encendido, una clave secreta de Stripe configurada y al menos un plan creado, como explica /help/turn-on-plans-and-billing. Mientras tanto no aparece en el índice de guías, ni en la página de su categoría, ni en la búsqueda, ni en el mapa del sitio, y su URL responde como un slug desconocido. Una categoría que se queda sin guías que mostrar desaparece con ella. La comprobación se hace en cada petición, así que encender los planes o crear el primer plan muestra la guía en la siguiente carga de la página, sin caché que limpiar.

requires: add-ons es para una guía sobre complementos. Se muestra sólo mientras FEATURE_ADDONS_ENABLED está encendido, el interruptor que abre la página Complementos, y se comprueba en cada petición de la misma forma. Una guía que necesita ambos escribe requires: plans, add-ons y se muestra sólo mientras se cumplen los dos. requires: tickets es para una guía sobre tickets de soporte, y se muestra sólo mientras FEATURE_TICKETS_ENABLED está encendido. requires: support-chat es para una guía sobre el chat de soporte en vivo, y se muestra sólo mientras el chat está encendido: los tickets, FEATURE_TICKETS_CHAT_ENABLED y el tiempo real. Cualquier otro valor esconde la guía para siempre, así que revisa cómo lo escribiste. El requisito se lee sólo del archivo en inglés: una traducción que declare uno no cambia nada.

Categorías

config/help.php lista las categorías que una guía puede declarar. Cada entrada es una clave con su etiqueta en inglés, o una clave con un arreglo que además nombra el ícono y la descripción que muestra su tarjeta:

'billing' => 'Plans and billing',
'admin' => [
    'name' => 'Admin panel',
    'icon' => 'squares-2x2',
    'description' => 'What ships under /admin and how to extend it.',
],

Las vistas pasan el nombre y la descripción por __(). Un proyecto que todavía usa la forma corta sigue funcionando. La tarjeta de una categoría muestra el ícono y la descripción cuando están declarados, y el número de guías siempre. El kit trae doce:

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.

help.guides_description es la frase debajo de las guías: la descripción de la tarjeta de Guías en /help/{locale} y la línea debajo del encabezado en /help/{locale}/guides. Viene como "Answers and step-by-step instructions for using it."; cámbiala por lo que tratan tus propias guías. Pasa por __() y lang:search la recoge, así que lang:update la traduce como cualquier otra cadena.

El subtítulo y las descripciones de las categorías vienen neutros, escritos para quien usa tu producto. El centro de ayuda del propio kit le habla a quien lo instala, así que sus textos viven aparte, en help.kit, y sólo los kits los leen. Tu proyecto ignora ese bloque: para escribir tus propios textos, edita guides_description y la description de cada categoría.

help.category_threshold, 20 por omisión, decide la forma de /help/{locale}/guides: con más guías que eso, la página muestra sólo las tarjetas de categoría, y cada una abre /help/{locale}/guides/{category}; con esa cantidad o menos, muestra cada categoría con sus guías.

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, tablas, 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 sin idioma, con el nombre de archivo en inglés, [Despliega tu proyecto](/help/deploy-your-project), y nunca por una ruta de archivo: el lector no tiene el repositorio abierto. El enlace abre la otra guía en el idioma del texto que se está leyendo, con el slug de ese idioma, así que la copia en español conserva la misma ruta.

Enlazar a una sección

Cada encabezado ## y ### de una guía se puede enlazar. Su ancla es el texto del encabezado en minúsculas, con los espacios convertidos en guiones y sin signos de puntuación; los acentos se quedan. ## For developers es #for-developers, ## Para desarrolladores es #para-desarrolladores, y ## Plans & prices es #plans--prices. Cuando el mismo encabezado aparece dos veces en una guía, el segundo es -1 y el tercero -2. En pantalla no se agrega nada al encabezado.

Dentro de una guía, enlaza una sección de la misma guía sólo con el ancla, y una sección de otra guía con su ruta y el ancla:

See [For developers](#for-developers) below.
See [Declare a meter](/help/plan-limits-and-usage#declare-a-meter).

El ancla sale del encabezado en el idioma de la propia guía, así que la copia en español usa su encabezado en español: [Para desarrolladores](#para-desarrolladores). Las entradas del changelog no tienen anclas.

El encabezado cambia con el idioma, así que un enlace desde Blade —el guide de una página de características, por ejemplo— no puede llevar un ancla fija. Constrúyelo con help_anchor() a partir del encabezado traducido:

<x-design::landing-block
    :title="__('Let your users browse and buy add-ons themselves')"
    :guide="'/help/sell-add-ons#' . help_anchor(__('When a change would leave the account over its quota'))"
    :guide-label="__('What happens when an add-on is cancelled')">
    {{ __('Free ones switch on with a click; paid ones join the subscription.') }}
</x-design::landing-block>

El valor en lang/ debe ser, palabra por palabra, el encabezado de la guía traducida. Si no lo es, el enlace sigue funcionando pero abre la guía al principio. help_anchor() no numera los encabezados repetidos, así que siempre llega al primero.

Ofrece el regreso

Un enlace a una guía desde otra página de tu sitio puede sumar back, la dirección a la que regresar, y back_label, el nombre de esa página. La guía muestra entonces Volver a {back_label} encima de Volver al centro de ayuda, y lleva a back:

<a href="{{ help_url('/help/sell-add-ons') . '?' . http_build_query(['back' => request()->getRequestUri(), 'back_label' => __('Add-ons')]) }}">
    {{ __('How add-ons work') }}
</a>

Solo se acepta una dirección de tu propio sitio: una ruta que empieza con una sola /, o una URL http o https del dominio con el que el visitante entra. Cualquier otra — otro dominio, una dirección que empieza con //, un enlace javascript: — se ignora. El enlace aparece solo cuando llegan los dos valores, la dirección se acepta y el nombre no está vacío; si no, la guía se ve como siempre. El nombre se muestra como texto plano.

Tablas

Una tabla se muestra dentro de un contenedor que se desplaza por su cuenta. Una tabla más ancha que la pantalla se arrastra de lado con el dedo o con el trackpad, y el resto de la página se queda quieto; una tabla que ya cabe se ve exactamente igual que siempre. Nada en la pantalla avisa de que la tabla se puede arrastrar: el gesto es el mismo al que responde cualquier tabla ancha en un teléfono, y no se agrega ninguna flecha, sombra ni aviso.

Dentro de una celda, un valor entre acentos graves nunca se parte en dos líneas. POST /api/stripe/webhook se queda como un solo valor en lugar de partirse después de la barra, y webhook-events en lugar de partirse después del guion — ese es el valor que el lector copia, así que se desplaza la tabla antes que partirse el valor. Fuera de una tabla, en un párrafo o en una lista, el código en línea sigue partiéndose como siempre: un fragmento largo ahí se reparte en dos líneas en lugar de empujar el párrafo más allá del borde de la página.

Así que escribe la tabla que la guía necesite, y pon las rutas, los archivos y las claves de configuración de sus celdas entre acentos graves. En un teléfono, una tabla ancha le cuesta al lector un deslizamiento; un valor partido a la mitad le cuesta el valor.

Imágenes

Una captura vive en public/images/help/{project}/{guide-slug}/, nombrada en minúsculas con guiones y con la extensión .png, y se escribe con la sintaxis de Markdown, con el texto alternativo en el idioma de la guía:

![El formulario de creación de un plan](/images/help/your-project/create-and-price-a-plan/create-form.png)

Es la única sintaxis que funciona: una etiqueta <img> cruda se escapa y se muestra como texto. Una ruta que no apunta a ningún archivo no muestra nada, ni una imagen rota, así que un error de dedo en la ruta esconde la imagen en lugar de romper la página; abre la guía después de agregar una. Las entradas del changelog no llevan imágenes.

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. Dentro de una entrada las viñetas se agrupan por tema, un encabezado ### por cada uno:

---
month: 2026-09
---

## 2026-09-03 01:33

### Help centre and guides

- 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)
- Several fixes were made to the help centre.

### Subscriptions

- Changing plan hands you the new plan's quota straight away, instead of leaving
  you on the quota of the plan you just left until the cycle turned.
  [Plan limits and usage](/help/plan-limits-and-usage)

### Corrections

- Several fixes were made to payments.
- Several fixes were made elsewhere in the product.

## 2026-09-01 15:10

### Notifications

- Web push notifications reach your phone with the site closed.
  [Notifications](/features/notifications)

La marca es el momento en que los cambios de esa entrada se publicaron a tus usuarios, no el momento en que se escribieron: varias sesiones de trabajo que salen juntas son una sola entrada.

Cada viñeta vive bajo un encabezado de tema, siempre: no hay una cantidad de viñetas por debajo de la cual se permita una lista plana. El encabezado es ### y nunca ## — un ## dentro de una entrada se lee como otra entrada, y se descarta por no llevar fecha. Una viñeta que no cabe en ningún tema propio va bajo un ### Other changes genérico, que es un tema como cualquier otro — incluida la regla de abajo sobre un tema que se queda sólo con arreglos.

Dentro de un tema, cada viñeta es de uno de tres tipos:

• Algo nuevo. Una línea corta que dice qué salió y para qué sirve, con un enlace a su guía o a su página de característica.
• Un arreglo o un ajuste que no cambia nada de lo que el lector daba por hecho. Todos los de un mismo tema se vuelven una sola línea genérica — "Several fixes were made to subscriptions." — sean cuantos sean y por distintos que sean entre sí. Sin desglose, sin detalle técnico, sin enlace.
• Un cambio a algo que ya existía y que puede afectar lo que el lector venía usando. Una línea de resumen en los términos del lector, con enlace. Enlaza una guía de actualización dedicada en la categoría updates, que cuente qué hacía antes, qué hace ahora y por qué cambió, cuando el cambio es lo bastante importante para merecerla; si no, enlaza la guía normal de esa característica, corregida para describir cómo se comporta ahora.

Un tema cuya única línea en una entrada es esa línea genérica de arreglos no conserva encabezado propio. Esas líneas se juntan en una sola sección al final de la entrada, ### Corrections, una línea por tema, y Other changes se pliega ahí como cualquier otro tema, con su línea "Several fixes were made elsewhere in the product." Un tema que sí tiene algo nuevo, o un cambio que afecta al lector, conserva su encabezado, y su línea de arreglos se queda dentro, al final.

En qué tema va una viñeta, si un cambio puede afectar al lector y si merece una guía de actualización propia lo decides tú al escribir. Nada se infiere y no hay ningún campo que llenar.

Las viñetas que describen el mismo cambio se vuelven una sola línea. Las viñetas sobre asuntos genuinamente distintos siguen separadas aunque compartan encabezado; sólo los arreglos menores de un tema se juntan siempre.

/help/{locale}/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, summary y el cuerpo: esos tres son todo lo que el centro de ayuda toma de la traducción. category, order y requires siempre salen del documento en inglés, así que lo que la traducción diga de ellos no cambia nada. Una traducción que omite title muestra el nombre del archivo en su lugar, y una que omite summary no muestra ninguno, así que escribe los dos.

Una guía traducida declara también slug, el nombre de su dirección en ese idioma, escrito con las palabras de su título, sin acentos, en minúsculas y unidas con guiones: la copia en español de what-weblabor-base-is.md declara slug: que-es-weblabor-base y se abre en /help/es/que-es-weblabor-base. Dos guías no pueden compartir un slug en el mismo idioma. Una traducción que no declara ninguno conserva en su dirección el nombre de archivo en inglés. Cambiar un slug cambia una dirección publicada, así que mantenlo una vez que la guía salió.

Una guía existe sólo en los idiomas en que está escrita. Sin traducción a un idioma no aparece en los listados, las categorías ni el mapa del sitio de ese idioma, y su dirección en ese idioma responde 404; lo mismo pasa con un mes del changelog. Las direcciones publicadas antes de que el centro de ayuda llevara idioma, como /help/get-it-running, redirigen a la misma página en el idioma del lector.

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

<!-- weblabor:doc source="ac37ca28c35b" translated="347cff9caa63" -->

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 --pushed, así que un push que enviaría una traducción faltante o desactualizada se detiene en tu máquina. Solo revisa los documentos de ayuda que el push cambia, con su par, tal como quedan en los commits que envía: un documento que ya venía roto en la rama no lo frena, y lo que no está en un commit no cuenta. Corre --check solo para revisar toda la carpeta de trabajo. Salta el hook una vez con git push --no-verify.

Anexos y otras carpetas

help:stamp revisa las carpetas listadas en translated_folders de config/help.php: guides y changelog por defecto. Un proyecto que guarda otros textos de ayuda, como anexos que se muestran dentro de una guía según el proyecto, agrega su carpeta a esa lista:

'translated_folders' => ['guides', 'changelog', 'annexes'],

Un archivo de una carpeta agregada sigue las mismas reglas que una guía: vive en docs/{project}/help/annexes/, necesita un front matter con al menos title, su traducción va en la carpeta de idioma a su lado, y --check reporta para él los mismos problemas. Una carpeta de la lista que todavía no existe se omite.

Para mostrar uno de esos textos dentro de una guía, léelo con HelpDocuments::text():

use App\Classes\HelpDocuments;

HelpDocuments::text('annexes', 'hotel-rooms');

Devuelve solo el cuerpo, sin el front matter ni el comentario de huella: en el idioma del lector cuando existe una traducción, en inglés si no. Busca en la carpeta de ayuda propia del proyecto, o en docs/project/help cuando el proyecto no tiene una, igual que las guías, y devuelve null cuando el archivo no existe o la carpeta no está en la lista.

Las rutas

{locale} es cada idioma de config('app.languages'), y las palabras fijas lo siguen: en español son /help/es/guias y /help/es/cambios, definidas en help.segments de config/help.php. El idioma de la dirección manda sobre el del perfil del lector y nunca se guarda, y cada página indica a los buscadores sus otros idiomas. Las direcciones viejas sin idioma, /help, /help/guides, /help/guides/{category}, /help/changelog y /help/{slug}, redirigen de forma permanente al idioma del lector. Arma un enlace con help_url('/help/sell-add-ons'): devuelve la dirección en el idioma del lector.

Todas 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, que lleva a cualquier lector a la misma página en el otro 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-design::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-design::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-design::landing-block>

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

    <x-design::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 en cuanto la carpeta existe: sin ella, la página de inicio responde con un error que nombra el archivo a crear, y un proyecto sin carpeta de landing muestra el inicio genérico de resources/views/landing/project/. 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, servidas en /privacy y /terms, públicas, y la casilla Acepto los Términos y Condiciones del formulario de registro abre la segunda. Su texto lo escribes tú, en lang/{codigo}/legal/{project}.php: un archivo por idioma, con el nombre de project en config/app.php, así que los textos legales propios de la base nunca chocan con los tuyos al fusionar. Mientras tu archivo no exista, las páginas muestran los textos genéricos de lang/{codigo}/legal/project.php, así que los enlaces siempre abren algo.

Cada archivo devuelve un documento terms y uno privacy. Un documento tiene un title, una fecha updated_on que cambias cada vez que reescribes el texto, y sus sections: cada una con un heading opcional y un body, en el que una cadena es un párrafo y una lista de cadenas es una lista con viñetas. :app se reemplaza por el nombre de la app y :account_url por la dirección de la página del perfil, donde un usuario borra su cuenta. Copia legal/project.php para empezar, y escribe tú cada idioma: lang:update no traduce estos archivos.

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.