Extensiones de Markdown

Extensiones de Markdown

Más allá del Markdown estándar, BX Sites activa por defecto tres de las extensiones nativas de Flexmark de bx-markdown - admoniciones, notas al pie y listas de definiciones - más una integración de diagramas Mermaid propia. Las cuatro son configurables mediante las claves markdown/mermaid de bxsites.json.

Además de esas, BX Sites implementa tres extensiones propias más de las que Flexmark no tiene ningún concepto en absoluto - pestañas de contenido, matemáticas, y anotaciones de código con fence hl_lines/linenums/title. Dado que bx-sites no puede bifurcar el analizador de bx-markdown, cada una funciona como un paso de preprocesamiento/postprocesamiento alrededor de la conversión de markdown normal en su lugar - consulta las secciones de abajo.

flowchart LR
    A["Raw markdown"] --> B["Pre-process:\nextract tabs, protect math,\nstrip code annotations"]
    B --> C["Markdown()\n(bx-markdown)"]
    C --> D["Post-process:\nrestore tabs, restore math,\napply code annotations"]
    D --> E["Final page HTML"]

Admoniciones

Un cuadro de aviso/nota - activo por defecto, sin necesidad de configuración en bxsites.json:

!!! note "Heads Up"
    This is an admonition. Its content is regular markdown - **bold**,
    `code`, [links](../index.md) and lists all work exactly as normal.

Lo que se renderiza como:

El tipo (note arriba) se convierte en el icono/color del cuadro y, si no proporcionas un "Title" explícito, se usa su propio nombre en mayúscula inicial en su lugar. Muchos sinónimos comunes se resuelven en los mismos 12 tipos canónicos, cada uno con su propio color de acento:

El cuerpo debe mantenerse sangrado 4 espacios (o un tabulador); el bloque termina en la primera línea no sangrada y no vacía. Las líneas en blanco están permitidas dentro del bloque - simplemente inician un nuevo párrafo, igual que en cualquier otra parte de markdown.

Admoniciones colapsables

Antepón ??? en lugar de !!! al tipo para hacer el bloque colapsable - ??? empieza colapsado, ???+ empieza abierto. En cualquier caso, el encabezado se puede pulsar para alternarlo:

??? tip "Click to expand"
    This starts collapsed.

???+ tip "Click to collapse"
    This starts open.

Desactiva las admoniciones por completo con {"markdown":{"enableAdmonition":false}}.

Notas al pie

Haz referencia a una nota al pie en línea con [^label] y define su texto en cualquier parte del documento con [^label]: text:

Here's a claim that needs backing up[^1].

[^1]: Here's the backup.

Aquí hay una afirmación que necesita respaldo¹.

Las definiciones de notas al pie se recopilan y renderizan como una lista numerada al final de la página, sin importar en qué parte del origen estén escritas. Desactivadas por defecto - actívalas con {"markdown":{"enableFootnotes":true}}.

Listas de Definiciones

Una línea de término seguida de una o más líneas de descripción : se convierte en un <dl>:

Term
:   Its definition.

Second term
:   First definition.
:   Second definition.

Término

Su definición.

Segundo término

Primera definición.

Segunda definición.

Desactivadas por defecto - actívalas con {"markdown":{"enableDefinitionLists":true}}.

Pestañas de Contenido

Agrupa contenido alternativo - diferentes lenguajes, diferentes plataformas - detrás de un conjunto de pestañas clicables con === "Title", sangradas de la misma forma que el cuerpo de una admonición (4 espacios o un tabulador):

=== "Java"
    ```java
    System.out.println( "Hi" );
    ```

=== "BoxLang"
    ```bx
    println( "Hi" )
    ```

Lo que se renderiza como:

System.out.println( "Hi" );

println( "Hi" )

Los bloques === "..." consecutivos (separados por como máximo una línea en blanco) forman un único grupo de pestañas; el contenido propio de una pestaña es markdown completo, así que fences de código, listas, admoniciones, lo que sea que escribirías en cualquier otra parte. Sin necesidad de configuración en bxsites.json - siempre activo.

Bloques de Código

Los bloques de código con fence se resaltan sintácticamente del lado del cliente (highlight.js), sin necesidad de configuración - el identificador de lenguaje después del ``` de apertura selecciona la gramática, por ejemplo ```json. Además de los propios lenguajes incluidos con highlight.js, BX Sites registra su propia gramática ligera de BoxLang bajo bx/boxlang/bxs/bxm/cfscript:

class {

	numeric function add( required numeric a, required numeric b ) {
		var result = a + b
		var message = "The sum is #result#"
		return result
	}

}

Números de línea, líneas resaltadas y títulos

Añade linenums, hl_lines y/o title a la cadena de información de un fence - cualquier combinación, todos opcionales:

```bx hl_lines="2" linenums="1" title="add.bx"
numeric function add( required numeric a, required numeric b ) {
	return a + b
}
```

Lo que se renderiza como:

numeric function add( required numeric a, required numeric b ) {
	return a + b
}

linenums="N" inicia el margen de numeración en N; hl_lines acepta números de línea separados por espacios y/o rangos ("2 4-6") para resaltar, contados desde la parte superior del bloque independientemente de dónde empiece linenums; title añade una pequeña barra de título encima del bloque. Sin necesidad de configuración en bxsites.json - siempre disponible.

Marcadores de diff y marcos de terminal

Añade insert/delete para señalar líneas añadidas/eliminadas - los mismos números de línea/rangos separados por espacios que hl_lines ya usa - como una línea resaltada más un marcador de margen +/–:

```bx title="add.bx" insert="3-4" delete="7"
numeric function add( required numeric a, required numeric b ) {
	var sum = a + b
	var total = a + b
	log.info( "computed sum", total )
	return sum
}
```

Lo que se renderiza como:

numeric function add( required numeric a, required numeric b ) {
	var sum = a + b
	var total = a + b
	log.info( "computed sum", total )
	return sum
}

Escrito deliberadamente sin abreviar - no ins/del - y como atributos en lugar de prefijos literales +/- en las líneas (como hacen algunas herramientas), de modo que el contenido propio del fence permanezca como código fuente real, sin modificar y copiable; no hay que eliminar nada para el botón de copiar ya existente. insert/delete se combinan bien con linenums - el marcador de margen se desplaza para dejar libre la columna de numeración cuando ambos están activos.

Añade frame="terminal" para sustituir la barra de título simple por una ventana de terminal al estilo macOS - tres puntos de estado, título centrado:

```bash frame="terminal" title="user@boxlang"
box install bx-sites
```

Lo que se renderiza como:

box install bx-sites

frame="code" es el nombre explícito de la barra simple de hoy - el valor por defecto; nadie necesita escribirlo. Ni insert/delete ni frame necesitan configuración en bxsites.json, igual que hl_lines/linenums/title.

Diffs reales de git

Etiqueta un fence como diff y pega directamente la salida real de git diff/git show - esto no es sintaxis específica de bx-sites en absoluto, es simplemente la propia gramática diff de highlight.js reconociendo por sí sola la sintaxis de diff unificado (líneas +/-/@@):

```diff
--- a/add.bx
+++ b/add.bx
@@ -1,4 +1,5 @@
 numeric function add( required numeric a, required numeric b ) {
-	var sum = a + b
-	return sum
+	var total = a + b
+	log.info( "computed", total )
+	return total
 }
```

Lo que se renderiza como:

--- a/add.bx
+++ b/add.bx
@@ -1,4 +1,5 @@
 numeric function add( required numeric a, required numeric b ) {
-	var sum = a + b
-	return sum
+	var total = a + b
+	log.info( "computed", total )
+	return total
 }

Pruébalo en vivo (try.boxlang.io)

Etiqueta un fence como tryboxlang en lugar de un nombre de lenguaje y se renderiza como un editor de try.boxlang.io incrustado en vivo, en lugar de un listado de código estático - los lectores pueden ejecutar y experimentar con el ejemplo directamente en la página, sin necesidad de configuración:

```tryboxlang title="Closures"
user = { name: "Luis", getFullName: () => "Luis Majano" }
println( user.getFullName() )
```

Lo que se renderiza como:

Atributos opcionales, todos en la misma línea que tryboxlang:

El contenido propio del fence es el código fuente inicial de BoxLang - se comprime y se pasa al editor de try.boxlang.io mediante su propio parámetro de URL code, de la misma forma que ya funciona un enlace "share" del propio try.boxlang.io, así que abrir el enlace "Open in try.boxlang.io ↗" de la incrustación retoma exactamente donde empieza esta.

Diagramas

Opcional mediante la clave mermaid de bxsites.json:

{ "mermaid": true }

Una vez activado, cualquier bloque de código con fence ```mermaid se renderiza como un diagrama Mermaid en vivo en lugar de un listado de código:

flowchart LR
    A[docs/*.md] --> B[bx-markdown]
    B --> C[Theme]
    C --> D[site/*.html]

Mermaid admite diagramas de flujo, diagramas de secuencia, diagramas de clases, diagramas de Gantt y más - consulta la propia referencia de sintaxis de Mermaid para todo lo que puede dibujar.

Matemáticas

Opcional mediante la clave math de bxsites.json:

{ "math": true }

Una vez activado, KaTeX compone $...$ para matemáticas en línea y $$...$$ para un bloque centrado, ambos escritos directamente en el cuerpo del markdown:

Euler's identity, $e^{i\pi} + 1 = 0$, relates five constants in one line.

$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$

La identidad de Euler, $e^{i\pi} + 1 = 0$, relaciona cinco constantes en una sola línea.

$$ \int_0^1 x^2 \, dx = \frac{1}{3} $$

Un $ inmediatamente seguido o precedido de un espacio en blanco se deja tal cual (para que "$5 y $10" no se interprete erróneamente como una fórmula) - las matemáticas compuestas siempre se sitúan pegadas a ambos delimitadores.

Consulta Bloques de Contenido para una familia de bloques ::: name ... ::: al estilo GitBook por encima de todo lo anterior - expandibles, tarjetas, columnas, un stepper, tarjetas de archivo/incrustación/enlace de página, un bloque de registro de cambios, y contenido reutilizable incluible.

Consulta Imágenes Responsivas para leyendas, alineación y marcos (HTML simple a nivel de bloque - sin necesidad de ninguna sintaxis específica de bx-sites en absoluto).

Extensiones de plugins

Las admoniciones, notas al pie y listas de definiciones cubren los casos comunes, pero bx-markdown en sí mismo no tiene opinión más allá de esas tres - cualquier otra extensión de Flexmark se puede registrar directamente contra él con markdownRegisterExtension(), de forma independiente a BX Sites. Consulta el propio readme de bx-markdown para más detalles.