Plugin de Gradle

Plugin de Gradle

Los desarrolladores de Java y Spring Boot no necesitan CommandBox ni una instalación de BoxLang a nivel de sistema para añadir un sitio bx-sites a su propio proyecto - el plugin de Gradle io.boxlang.bxsites descarga todo lo que necesita (el runtime de BoxLang y bx-sites mismo) a una caché local la primera vez que se ejecuta. El único requisito previo es un JDK 21.

Estado: pre-1.0, aún no publicado en el Gradle Plugin Portal - ver gradle-plugin/ en el repositorio de bx-sites para el código fuente y las instrucciones actuales de build/pruebas. Esta página documenta lo que hace una vez publicado; la mecánica descrita abajo ya es real y está verificada, solo que todavía no está disponible como una dependencia de una sola línea en plugins { }.

Inicio rápido

plugins {
    id("io.boxlang.bxsites") version "<version>"
}

./gradlew bxSitesNew    # crea docs/ + bxsites.yaml
./gradlew bxSitesBuild   # renderiza docs/**.md en site/
./gradlew bxSitesServe   # compila + sirve localmente con recarga en vivo

Una configuración por defecto no necesita nada más - el plugin detecta automáticamente el directorio de contenido (docs/, o src/ si no existe - salvo en un proyecto con el plugin de Java aplicado, donde src/ es tu propio directorio de fuentes Java y nunca se usa como contenido de bx-sites) y el directorio de salida (siempre <projectRoot>/site/). El aspecto, tema, navegación y cualquier otro ajuste de tu sitio se controla por completo mediante bxsites.yaml/.toml/.json en la raíz del proyecto, exactamente como se documenta en Configuración - el plugin nunca duplica ese esquema, solo gestiona cómo y cuándo se ejecuta bx-sites desde tu build.

Tasks

bxSitesBuild nunca se ejecuta automáticamente como parte de assemble a menos que lo habilites (ver hookIntoAssemble más abajo) - un build de documentación es una preocupación distinta, a menudo más lenta, que compilar tu propio código.

Configuración

bxSites {
    projectRoot.set(layout.projectDirectory)
    boxlangMiniserverVersion.set("1.18.0-snapshot")   // versión fijada del runtime de BoxLang
    bxSitesVersion.set("1.0.0-snapshot")               // versión fijada de bx-sites
    boxlangHomeDir.set(layout.buildDirectory.dir("bxsites/boxlang-home"))
    hookIntoAssemble.set(false)                        // opcional: ejecutar bxSitesBuild como parte de assemble
    hookIntoCheck.set(true)                            // vincula bxSitesLint a `check` por defecto
}

Cada propiedad tiene un valor por defecto razonable. El directorio de salida no es configurable aquí en absoluto - bx-sites mismo lo fija en <projectRoot>/site/, así que el plugin lo deriva en lugar de exponer un ajuste que de todos modos no se respetaría.

Lo que aún no está construido

• Generación de documentación para Spring Boot (OpenAPI, Javadoc, escaneo de controladores) - planificado.
• El streaming de salida en vivo de bxSitesServe - actualmente almacena en búfer la salida con un timeout de 30 minutos, ambas cosas incorrectas para una task pensada para ejecutarse indefinidamente.

Consulta la guía del Plugin de Maven para el equivalente del lado de Maven - ambos plugins envuelven la misma lógica subyacente, así que la cobertura de verbos y el comportamiento se mantienen idénticos entre ambas herramientas de build.

Generación de documentación BoxLang

bxSitesDocBoxDoc genera una referencia de API BoxLang/CFML desde DocBox, para un proyecto JVM cuyas fuentes incluyan clases .bx/.cfc. A diferencia de los generadores de Spring Boot, es una envoltura fina sobre el verbo docbox en lugar de un generador dentro de la JVM: la implementación vive en el lado BoxLang, y una sola implementación que ambas herramientas invocan no puede divergir. Solo se pasan las opciones que realmente configuras; el resto sigue lo que diga bxsites.yaml. Consulta Referencia de API con DocBox; el módulo bx-docbox debe estar instalado en el runtime de BoxLang aprovisionado.

No hay tarea de ColdBox, deliberadamente. Una aplicación ColdBox se construye y se ejecuta con CommandBox, nunca con Gradle, así que bxSites coldbox sigue siendo cosa de la CLI de bx-sites.