Primeros Pasos

Instala el módulo, crea un proyecto y construye tu primer sitio.

Primeros Pasos

Instalación

BX Sites depende de bx-markdown para el renderizado de Markdown, de bx-esapi para la codificación HTML, y de bx-yaml para leer bxsites.yaml. Con CommandBox instalado:

box install bx-sites
box install bx-markdown
box install bx-esapi
box install bx-yaml

O, sin CommandBox, el propio instalador de BoxLang toma los cuatro en un solo comando:

install-bx-module bx-sites bx-markdown bx-esapi bx-yaml

box install/install-bx-module lee boxlang.executable de box.json y coloca un script bxSites en tu PATH (en ~/.boxlang/bin), de modo que cada comando de abajo funciona tanto en su forma corta e independiente:

bxSites <verb> [options]

como, en cualquier lugar donde BoxLang esté disponible pero ese atajo del PATH no lo esté (un ejecutor de CI, un módulo registrado a mano en lugar de instalado) - ambas formas ejecutan exactamente lo mismo:

boxlang bxSites <verb> [options]

El resto de esta guía usa la forma corta.

Crear la estructura de un proyecto

bxSites new my-docs
cd my-docs

Esto crea:

my-docs/
├── docs/
│   ├── assets/
│   └── index.md
└── bxsites.yaml

Pasa --theme=material o --theme=tailwind para generar la estructura con un tema predeterminado diferente, y --name="My Project Docs" para establecer el nombre del sitio de antemano - de lo contrario new lo deriva del nombre del directorio de destino.

Formato del archivo de configuración

bxsites.yaml es el formato por defecto y preferido - es lo que new genera a menos que se indique lo contrario, y cada ejemplo de esta guía y de Configuración lo muestra primero. bxsites.json también es totalmente compatible, para un proyecto que lo prefiera: pasa --format=json para generar uno en su lugar, o simplemente escríbelo o renómbralo tú mismo - ConfigLoader resuelve el que esté realmente presente entre bxsites.yaml/.yml/.json, en ese orden, sin necesitar ninguna otra configuración para cambiar. Consulta Configuración para la referencia completa de claves en ambos formatos.

¿Ya tienes contenido en GitBook? bxSites migrate --source=/path/to/export convierte una exportación de GitBook directamente en docs/ - consulta Migrar desde GitBook - y puedes pasar directamente a Construcción.

Añadir páginas

Cada archivo .md bajo docs/ se convierte en una página. El anidamiento de carpetas se convierte automáticamente en anidamiento de navegación:

docs/
├── index.md              -> /
├── guides/
│   ├── index.md          -> /guides/
│   └── deployment.md     -> /guides/deployment/

(Un sitio grande puede sobrescribir por completo este orden/agrupamiento inferido con una navegación explícita - consulta nav).

Enlazar entre páginas

Enlaza a otra página de la manera habitual de mkdocs - una ruta relativa al archivo hasta su fuente .md, exactamente como si los dos archivos estuvieran uno junto al otro en el disco (porque lo están):

See [Deployment](guides/deployment.md) or, from that same guide,
[back to Getting Started](../getting-started.md#add-pages).

BX Sites reescribe cada enlace de este tipo a su URL amigable generada en el momento de la construcción (guides/deployment.md -> /guides/deployment/index.html, conservando anclas y cadenas de consulta), resuelto respecto a la propia carpeta de la página que enlaza - ../ y las referencias a archivos hermanos funcionan exactamente igual que al resolver cualquier otra ruta relativa. Esta es también la razón por la que el enlace sigue funcionando si lees el archivo directamente en GitHub en lugar del sitio construido: es una ruta relativa real y válida a un archivo real de cualquiera de las dos formas. Las URL absolutas, los enlaces mailto: y los enlaces que ya empiezan con / se dejan intactos.

Descargar una página como Markdown

Cada página construida también publica su propia fuente .md original junto a ella - docs/guides/deployment.md termina copiado en site/guides/deployment.md, justo al lado de site/guides/deployment/index.html - con un enlace "Download Markdown" en la propia página, junto a "Edit this page". No requiere configuración, siempre está activo.

Esta es la misma motivación que llms.txt - una persona (o un LLM) puede obtener el Markdown en bruto de una página directamente en lugar de raspar el HTML renderizado - y dado que todo el árbol docs/ se refleja 1:1, los enlaces relativos propios de una página también siguen funcionando leídos de esta manera.

Cada página puede comenzar con un pequeño bloque de frontmatter:

---
title: Deployment
order: 2
hidden: false
description: How to deploy a built BX Sites site.
tags: [guides, deployment]
icon: 🚀
summary: Everything you need to publish a built site.
ogImage: assets/deployment-card.png
---

# Deployment

Your content here.

• title - sobrescribe el título de navegación/página (que de lo contrario se deriva del nombre del archivo)
• order - controla el orden entre páginas hermanas en la navegación (un número más bajo aparece primero; las páginas omitidas se ordenan al final, alfabéticamente)
• hidden - true excluye la página de la navegación (y de la búsqueda) sin excluirla de la construcción
• description - la descripción de tarjeta social/meta de esta página (consulta ogImage); recurre a la description general del sitio en la configuración del sitio cuando se omite
• tags - un array de etiquetas para esta página, renderizadas como insignias clicables debajo del título y recopiladas en una página de índice /tags/ de todo el sitio (solo se construye una vez que al menos una página tenga etiquetas); también aumenta la relevancia en la búsqueda para las consultas coincidentes
• icon - se muestra junto al título de la página y junto a su entrada en la navegación - un emoji sencillo, o un icono con nombre de una biblioteca incluida (rocket, lucide:rocket, tabler:rocket, o el custom:my-icon propio de un proyecto) - consulta Temas: Iconos
• summary - una frase introductoria de una línea mostrada debajo del título (distinta de description, que es solo para la etiqueta meta y nunca se renderiza en la propia página)
• ogImage - sobrescribe la imagen de tarjeta social de esta página en particular - consulta ogImage

Los valores del frontmatter pueden ser listas en línea (tags: [a, b, c]), listas de bloque al estilo YAML (tags: seguido de líneas - item sangradas), o escalares de bloque con >/| para un valor de varias líneas - aunque es un analizador pequeño escrito a mano, no YAML completo, así que los objetos/mapas anidados no son compatibles.

Construcción

bxSites build

Renderiza cada página de docs/ en un sitio estático en site/, listo para alojarse en cualquier lugar que sirva archivos estáticos.

Servir localmente

bxSites serve

Construye el proyecto, sirve site/ en http://127.0.0.1:8080/, y reconstruye automáticamente cada vez que guardas un cambio bajo docs/, tu configuración de sitio bxsites.yaml/.json, o una sobrescritura de theme/ a nivel de proyecto - tu navegador se recarga por sí solo. Pasa --port=3000 o --host=0.0.0.0 para cambiar cómo se enlaza.

Limpieza

bxSites clean

Elimina site/ y cualquier caché de construcción, sin tocar tu fuente docs/.