Importar un tema

Importar un tema

bxSites theme:import convierte un tema del ecosistema de otro generador de sitios estáticos en un scaffold de tema bx-sites bajo themes/<name>/

• un punto de partida de mejor esfuerzo, no una migración sin pérdidas en un solo comando. Maneja los tres ecosistemas cuya estructura de tema se corresponde con el propio contrato layout.bxm+page.bxm de bx-sites (consulta Temas):

• mkdocs - plantillas Jinja2 (tanto mkdocs nativo como mkdocs-material usan base.html+main.html)

• jekyll - plantillas Liquid (_layouts/default.html+ _layouts/page.html)

• hugo - plantillas Go (layouts/_default/baseof.html+ layouts/_default/single.html)

Un tema basado en componentes React/Vue (Docusaurus, VuePress, Gatsby, ...) no tiene equivalente aquí - no hay ningún archivo de plantilla que traducir mecánicamente, ya que el tema son componentes de interfaz compilados en lugar de marcado renderizado en el servidor. Portar uno de esos significa reescribirlo como un tema bx-sites desde cero (consulta Escribir un tema desde cero), no convertirlo.

bxSites theme:import --source=mkdocs --path=/path/to/mkdocs-theme --name=my-imported-theme

• --source (obligatorio) - mkdocs, jekyll o hugo
• --path (obligatorio) - la propia carpeta raíz del tema de origen (la que contiene su plantilla de layout, no todo el proyecto mkdocs/jekyll/hugo - consulta Migrar desde mkdocs/ Migrar desde GitBook para convertir el contenido de un proyecto, una tarea distinta de convertir su tema)
• --name (obligatorio) - el nombre de destino, escrito en themes/<name>/ (la misma convención de tema instalado que usa install:theme) - establece el theme.name de bxsites.yaml una vez que estés satisfecho con el resultado

Volver a ejecutarlo contra el mismo --name es seguro - layout.bxm/ page.bxm se sobrescriben y cualquier carpeta de recursos recién encontrada se combina, así que iterar (ajustar el origen, o el mapeo, volver a ejecutar) es el flujo de trabajo normal, no una operación de un solo uso.

Qué se convierte realmente

La salida del comando informa exactamente qué ocurrió - qué archivo de origen se convirtió en layout.bxm/page.bxm (o una nota indicando que no se encontró ninguno, si el tema de origen no usa uno de los nombres de archivo convencionales de arriba), qué carpetas de recursos (css/, js/, static/, ...) se copiaron tal cual en themes/<name>/assets/, y una lista numerada de todo lo que necesita revisión manual.

Dentro de un archivo de plantilla, esto es un traductor mecánico de mejor esfuerzo (JinjaLikeTranslator.bx para la sintaxis Jinja2/Liquid compartida de mkdocs/jekyll, GoTemplateTranslator.bx para las plantillas Go de hugo) - no un analizador real de ninguno de los dos lenguajes. Lo que maneja:

• Salida de variables ({{ page.title }} / el {{ .Title }} de Hugo), mapeada contra una tabla pequeña y fija de los campos comunes (título/ contenido/descripción de la página, nombre/descripción del sitio, URL base, navegación) - cualquier cosa fuera de esa tabla se deja como un marcador <!--- TODO: ... ---> en lugar de adivinarse.
• if/elif/else/endif (mkdocs/jekyll) o if/else if/else/end (hugo), traducido a una estructura <bx:if>/<bx:elseif>/<bx:else> real - siempre estructuralmente válida incluso cuando la propia condición referencia algo fuera de la tabla de mapeo (marcada como advertencia en su lugar, ya que dejar el if circundante roto sería peor que una condición que un humano todavía necesita revisar).
• for x in list/endfor (mkdocs/jekyll) o range/end (hugo), traducido a <bx:loop> de la misma forma. El range de Hugo reasigna . a cada elemento sin ninguna variable de bucle con nombre en el caso común - el <bx:loop> generado siempre usa un nombre sintético item, y una advertencia permanente señala que un .Field suelto dentro del cuerpo del bucle significa el propio campo del elemento del range en Go, que no puede redirigirse automáticamente a item.Field.
• Comentarios ({# ... #}/{% comment %} para Jinja2/Liquid, {{/* ... */}} para Go), eliminados por completo.

Lo que deliberadamente no se traduce, siempre dejado como un marcador TODO (o, dentro de una condición donde dejar la sintaxis sin traducir en bruto produciría BoxLang inválido, sustituido por un marcador de posición sintácticamente seguro - false para una condición, [] para la expresión de lista de un bucle - marcado de la misma forma):

• Un filtro/pipeline ({{ page.title | upper }}, {{ .Title | truncate 100 }})
  • la semántica de los filtros varía demasiado como para adivinarla con seguridad - de todos modos vale la pena verificarlo manualmente, ya que un filtro con un equivalente BoxLang claramente seguro (upper → ucase()) es lo bastante común como para ser un arreglo manual rápido.
• La herencia de plantillas ({% extends %}/{% block %} de Jinja2, {{ block }}/{{ define }} de Hugo) e includes/parciales ({% include %}) - no hay forma automática de mapear esto al propio contrato de archivo único layout.bxm+page.bxm de bx-sites.
• El {{ with .X }} de Hugo - reasigna . a un nuevo contexto para su propio cuerpo, sin ningún equivalente en bx-sites en absoluto, así que se deja sin traducir en lugar de emitirse como un <bx:if> estructuralmente válido pero semánticamente incorrecto.
• Una condición de Go que no es una única referencia a un campo (Go escribe la lógica booleana como llamadas a función en notación prefija
  • {{ if and .A .B }}, {{ if eq .Type "post" }} - que no tienen un equivalente infijo en BoxLang; sustituir solo los tokens .Field dentro de una de ellas seguiría dejando texto BoxLang inválido detrás, así que toda la condición se reemplaza por el marcador de posición en su lugar).
• Cualquier referencia de variable que no esté en la tabla de mapeo fija.

Después de importar

El scaffold es un punto de partida, no un tema terminado - trabaja los marcadores TODO y las advertencias reportados, y luego verifícalo contra el contrato de ThemeProvider de la misma forma en que lo necesita un tema escrito a mano (layout.bxm+ page.bxm obligatorios, search.bxm opcional). Ninguna de las convenciones de funciones de página que implementa cada tema incorporado (modo oscuro, migas de pan, anterior/siguiente, el cuadro de búsqueda, ...) viene incluida automáticamente - el propio marcado del tema de origen para esas, si lo tenía, pasó por la misma traducción mecánica que todo lo demás y necesita la misma revisión.