Estensioni Markdown

Estensioni Markdown

Oltre al Markdown standard, BX Sites attiva di default tre estensioni Flexmark native di bx-markdown - ammonizioni, note a piè di pagina e liste di definizioni - più un'integrazione con i diagrammi Mermaid tutta sua. Tutte e quattro sono configurabili tramite le chiavi markdown/mermaid di bxsites.json.

Oltre a queste, BX Sites implementa altre tre estensioni proprie di cui Flexmark non ha alcun concetto - schede di contenuto, matematica, e annotazioni hl_lines/linenums/title sui blocchi di codice delimitati. Dato che bx-sites non può forkare il parser di bx-markdown, ognuna di queste funziona come un passaggio di pre/post-elaborazione intorno alla normale conversione del markdown - vedi le sezioni sotto.

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"]

Ammonizioni

Un box di richiamo/nota - attivo di default, nessuna configurazione di bxsites.json necessaria:

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

Che viene renderizzato così:

Il tipo (note sopra) diventa l'icona/colore del box e, se non fornisci un "Title" esplicito, viene usato invece il suo nome capitalizzato. Molti sinonimi comuni si risolvono negli stessi 12 tipi canonici, ognuno con il proprio colore d'accento:

Il corpo deve restare indentato di 4 spazi (o un tab); il blocco termina alla prima riga non indentata e non vuota. Le righe vuote vanno bene dentro il blocco - iniziano semplicemente un nuovo paragrafo, come ovunque altrove nel markdown.

Ammonizioni comprimibili

Anteponi al tipo ??? invece di !!! per rendere il blocco comprimibile

• ??? inizia compresso, ???+ inizia aperto. In entrambi i casi l'intestazione è cliccabile per attivarlo/disattivarlo:

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

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

Disattiva del tutto le ammonizioni con {"markdown":{"enableAdmonition":false}}.

Note a piè di pagina

Fai riferimento a una nota a piè di pagina in linea con [^label] e definiscine il testo in qualsiasi punto del documento con [^label]: text:

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

[^1]: Here's the backup.

Ecco un'affermazione che ha bisogno di una conferma¹.

Le definizioni delle note a piè di pagina vengono raccolte e renderizzate come una lista numerata in fondo alla pagina, indipendentemente da dove nel sorgente siano state scritte. Disattivate di default - attivale con {"markdown":{"enableFootnotes":true}}.

Liste di definizioni

Una riga di termine seguita da una o più righe di descrizione : diventa una <dl>:

Term
:   Its definition.

Second term
:   First definition.
:   Second definition.

Termine

La sua definizione.

Secondo termine

Prima definizione.

Seconda definizione.

Disattivate di default - attivale con {"markdown":{"enableDefinitionLists":true}}.

Schede di contenuto

Raggruppa contenuti alternativi - linguaggi diversi, piattaforme diverse - dietro un insieme di schede cliccabili con === "Title", indentate allo stesso modo del corpo di un'ammonizione (4 spazi o un tab):

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

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

Che viene renderizzato così:

System.out.println( "Hi" );

println( "Hi" )

Blocchi === "..." consecutivi (separati al massimo da una riga vuota) formano un unico gruppo di schede; il contenuto di una scheda è markdown completo, quindi blocchi di codice, liste, ammonizioni, qualsiasi cosa scriveresti altrove. Nessuna configurazione di bxsites.json necessaria - sempre attivo.

Blocchi di codice

I blocchi di codice delimitati vengono evidenziati lato client (highlight.js), nessuna configurazione necessaria - l'identificatore di linguaggio dopo l'apertura ``` seleziona la grammatica, ad es. ```json. Oltre ai linguaggi già inclusi in highlight.js, BX Sites registra una propria grammatica BoxLang leggera sotto 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
	}

}

Numeri di riga, righe evidenziate e titoli

Aggiungi linenums, hl_lines e/o title alla stringa info di un blocco delimitato - qualsiasi combinazione, tutti opzionali:

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

Che viene renderizzato così:

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

linenums="N" fa iniziare il conteggio nel margine da N; hl_lines accetta numeri di riga e/o intervalli separati da spazi ("2 4-6") da evidenziare, contati dall'inizio del blocco indipendentemente da dove parte linenums; title aggiunge una piccola barra del titolo sopra il blocco. Nessuna configurazione di bxsites.json necessaria - sempre disponibile.

Indicatori di diff e cornici terminale

Aggiungi insert/delete per segnalare righe aggiunte/rimosse - gli stessi numeri di riga/intervalli separati da spazi che hl_lines già usa - come riga evidenziata più un indicatore nel margine +/–:

```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
}
```

Che viene renderizzato così:

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

Scritto per intero deliberatamente - non abbreviato in ins/del - e come attributi invece di prefissi letterali +/- sulle righe (come fanno alcuni strumenti), così il contenuto del blocco resta codice sorgente reale, non modificato e copiabile; non c'è nulla da rimuovere per il pulsante di copia già esistente. insert/delete si combinano bene con linenums - l'indicatore nel margine si sposta per lasciare libera la colonna dei numeri di riga quando entrambi sono attivi.

Aggiungi frame="terminal" per sostituire la semplice barra del titolo con una finestra di terminale in stile macOS - tre pallini di stato, titolo centrato:

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

Che viene renderizzato così:

box install bx-sites

frame="code" è il nome esplicito per la barra semplice di oggi - il valore predefinito; nessuno ha bisogno di scriverlo. Né insert/delete né frame richiedono configurazione in bxsites.json, come hl_lines/linenums/title.

Diff git reali

Etichetta un blocco come diff e incolla direttamente l'output reale di git diff/git show - questa non è affatto sintassi specifica di bx-sites, è solo la grammatica diff di highlight.js che riconosce da sola la sintassi diff unificato (righe +/-/@@):

```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
 }
```

Che viene renderizzato così:

--- 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
 }

Provalo dal vivo (try.boxlang.io)

Etichetta un blocco tryboxlang invece di un nome di linguaggio e viene renderizzato come un editor try.boxlang.io dal vivo, incorporato, invece che come un listato di codice statico - i lettori possono eseguire e modificare l'esempio direttamente sulla pagina, nessuna configurazione necessaria:

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

Che viene renderizzato così:

Attributi opzionali, tutti sulla stessa riga di tryboxlang:

Il contenuto stesso del blocco è il sorgente BoxLang di partenza - viene compresso e passato all'editor di try.boxlang.io tramite il suo stesso parametro URL code, allo stesso modo in cui funziona già un link "share" da try.boxlang.io stesso, quindi aprire il link "Apri in try.boxlang.io ↗" dell'embed riprende esattamente da dove parte l'embed.

Diagrammi

Opzionale tramite la chiave mermaid di bxsites.json:

{ "mermaid": true }

Una volta attivato, qualsiasi blocco di codice delimitato ```mermaid viene renderizzato come un diagramma Mermaid dal vivo invece che come un listato di codice:

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

Mermaid supporta diagrammi di flusso, diagrammi di sequenza, diagrammi di classe, diagrammi di Gantt e altro - vedi il riferimento di sintassi ufficiale di Mermaid per tutto ciò che può disegnare.

Matematica

Opzionale tramite la chiave math di bxsites.json:

{ "math": true }

Una volta attivato, KaTeX compone $...$ per la matematica in linea e $$...$$ per un blocco centrato, entrambi scritti direttamente nel corpo 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}
$$

L'identità di Eulero, $e^{i\pi} + 1 = 0$, mette in relazione cinque costanti in un'unica riga.

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

Un $ immediatamente preceduto o seguito da uno spazio viene lasciato intatto (così "$5 e $10" non viene scambiato per una formula) - la matematica composta sta sempre accostata a entrambi i delimitatori.

Vedi Blocchi di contenuto per una famiglia di blocchi in stile GitBook ::: name ... ::: che si aggiunge a tutto quanto sopra - espandibili, card, colonne, uno stepper, card file/embed/link-a-pagina, un blocco changelog, e contenuto riutilizzabile tramite include.

Vedi Immagini Responsive per didascalie, allineamento e cornici (semplice HTML a livello di blocco - nessuna sintassi specifica di bx-sites necessaria).

Estensioni tramite plugin

Ammonizioni, note a piè di pagina e liste di definizioni coprono i casi comuni, ma bx-markdown stesso non ha opinioni oltre a queste tre - qualsiasi altra estensione Flexmark può essere registrata direttamente contro di esso con markdownRegisterExtension(), indipendentemente da BX Docs. Vedi il readme proprio di bx-markdown per i dettagli.