Documentazione Strata

Usa una mappa blog: nel primo blocco di metadati YAML per progettare un articolo pubblicato. Il pannello dell’aspetto modifica lo stesso testo e conserva le altre chiavi e i commenti.

L’anteprima segue la bozza. La pubblicazione salva il design completo, inclusi i valori ereditati dal tema della pubblicazione; le modifiche successive alla bozza o al tema del profilo non cambiano quella versione. Le presentazioni usano impostazioni proprie. I metadati sono nascosti nelle pagine pubbliche e nelle descrizioni.

Chiavi sconosciute in blog:, YAML non valido, valori errati, riferimenti mancanti o duplicati e contrasto insufficiente impediscono la pubblicazione. Correggi tutti gli errori; le modifiche degli agenti restituiscono risultati blogValidation. Reimposta un valore per ereditare quello predefinito. L’indice è nascosto e la superficie di lettura è opaca per impostazione predefinita.

Il riepilogo ammette 160 caratteri; i tag fino a 10 elementi di 32 caratteri. I nomi delle serie ammettono 80 caratteri e richiedono un ordine intero positivo. I nomi esatti raggruppano gli articoli; ordini duplicati producono avvisi. noindex mantiene l’articolo nel profilo e nei feed, ma lo rimuove dalla mappa del sito e chiede ai motori di non indicizzarlo. cover indica un’immagine del documento; assegnale un nome con <!-- strata:name=cover --> immediatamente prima dell’immagine.

I colori richiedono valori #RRGGBB tra virgolette per le modalità chiara e scura. background colora la superficie di lettura e, senza sfondo decorativo, la pagina. Testo e collegamenti accent devono raggiungere un contrasto di 4.5:1 sulla superficie effettiva in entrambe le modalità. I caratteri provengono dall’elenco seguente. Una superficie traslucida usa l’88% di opacità ed è consentita solo su colori o sfumature con contrasto sufficiente lungo tutta la sfumatura.

Scegli un solo tipo di sfondo. Le sfumature accettano 2–5 colori; i motivi usano i nomi seguenti. Lo sfondo immagine indica un’immagine del documento. Lo sfondo HTML indica un blocco html e richiede un colore o un’immagine statica di riserva. Funziona dietro l’articolo nell’ambiente isolato esistente, non riceve clic o focus e si arresta quando la scheda è nascosta. Movimento o dati ridotti, dispositivi limitati, anteprime HTML disattivate o errori attivano la riserva. Stampa e PDF omettono lo sfondo. HTML o CSS diretto nella pagina e articoli interamente HTML non sono supportati.

I blocchi HTML con uses="frontmatter" leggono strata.data.get("frontmatter").values. Le chiavi risolte sono blog.typography, blog.palette, blog.readingWidth, blog.blockControls, blog.tableOfContents, blog.readingSurface, blog.accent, blog.background, blog.fonts.heading e blog.fonts.body. I colori seguono la modalità corrente. I caratteri non impostati vengono omessi. I blocchi pubblicati ricevono solo questi valori; gli altri metadati scalari sono disponibili soltanto nell’editor. Uno sfondo riceve solo questi valori e la modalità colore, mai altri dati del documento.

Campi e valori consentiti

blog.typography

modern | editorial | expressive | technical

blog.palette

strata | paper

blog.readingWidth

focused | comfortable | wide | full

blog.blockControls

visible | hidden

blog.tableOfContents

visible | hidden

blog.accent

{ light: "#RRGGBB", dark: "#RRGGBB" }

blog.background

{ light: "#RRGGBB", dark: "#RRGGBB" }

blog.fonts.heading, blog.fonts.body

Manrope | Syne | Fira Code | Georgia | Times New Roman | Arial | Helvetica | Verdana | Trebuchet MS | Palatino | Courier New | IBM Plex Mono

blog.summary

string (1…160)

blog.cover

image.name

blog.tags

string[] (0…10 × 1…32)

blog.noindex

true | false

blog.series

{ name: string (1…80), order: integer (≥1) }

blog.wallpaper.color

{ light: "#RRGGBB", dark: "#RRGGBB" }

blog.wallpaper.gradient

{ type: linear | radial, stops: [{ light: "#RRGGBB", dark: "#RRGGBB" }, …] } (2…5)

blog.wallpaper.pattern

{ name: dots | grid | lines | paper | topographic | stars, tint: { light: "#RRGGBB", dark: "#RRGGBB" } }

blog.wallpaper.image

image.name

blog.wallpaper.html

codeBlock.name (language: html)

blog.wallpaper.fallback

{ color: { light: "#RRGGBB", dark: "#RRGGBB" } } | { image: image.name }

blog.readingSurface

opaque | translucent

Esempio completo di sfondo HTML

---
blog:
  typography: editorial
  palette: paper
  readingWidth: comfortable
  blockControls: hidden
  tableOfContents: visible
  accent: { light: "#8a3515", dark: "#ffb788" }
  background: { light: "#fffdf8", dark: "#272119" }
  fonts: { heading: Georgia, body: Georgia }
  summary: "An astronomy journal about the night sky."
  tags: [astronomy, observation]
  noindex: false
  series: { name: "Night notes", order: 1 }
  readingSurface: opaque
  wallpaper:
    html: starfield
    fallback:
      color: { light: "#e7e0d4", dark: "#111827" }
---

# Night notes

Our first observing session began at twilight.

## The northern sky

The article stays on an opaque reading surface above the animation.

```html name=starfield uses="frontmatter"
<style>
  html, body { margin: 0; width: 100%; height: 100%; overflow: hidden; }
  canvas { display: block; width: 100%; height: 100%; }
</style>
<canvas id="sky"></canvas>
<script>
  const canvas = document.getElementById('sky');
  const ctx = canvas.getContext('2d');
  let color = '#8a3515';
  function readDesign() {
    const source = strata.data.get('frontmatter');
    if (source?.kind === 'frontmatter') color = source.values['blog.accent'];
  }
  readDesign();
  window.addEventListener('strata:data', readDesign);
  function paint(time) {
    const width = canvas.clientWidth, height = canvas.clientHeight;
    if (canvas.width !== width || canvas.height !== height) {
      canvas.width = width;
      canvas.height = height;
    }
    ctx.clearRect(0, 0, width, height);
    ctx.fillStyle = color;
    for (let i = 0; i < 90; i++) {
      ctx.globalAlpha = 0.25 + 0.25 * Math.sin(time / 1800 + i);
      ctx.beginPath();
      ctx.arc((i * 137.508 % 100) / 100 * width,
        (i * 71.37 % 100) / 100 * height, 1 + i % 2, 0, Math.PI * 2);
      ctx.fill();
    }
    requestAnimationFrame(paint);
  }
  requestAnimationFrame(paint);
</script>
```

I blocchi di codice contrassegnati come html vengono resi come anteprime live e isolate nell'editor di Strata e nei PDF esportati: grafici, diagrammi, scene 3D e piccoli widget interattivi, scritti come normale codice delimitato.

Scrivi un blocco di codice delimitato con il tag di linguaggio html. Il suo markup, gli stili e gli script vengono eseguiti automaticamente in un'anteprima isolata; ogni modifica esegue di nuovo il rendering da uno stato pulito e i lettori possono passare dall'anteprima al sorgente e viceversa.

L'anteprima è completamente isolata: nessun cookie o storage, nessun accesso alla pagina circostante e nessun URL esterno. WebSocket, beacon e invii di form sono rimossi del tutto, e fetch raggiunge soltanto le risorse verificate in /sandbox/ elencate sotto, che è il modo in cui il motore di Doom carica i propri dati di gioco. Tutto ciò che viola questi vincoli fallisce all'interno della propria anteprima e in nessun altro punto.

I token di design di Strata sono precaricati: variabili CSS come var(--color-foreground), var(--color-muted-foreground), var(--color-primary) e var(--color-border) corrispondono al tema dell'app e l'anteprima segue automaticamente la modalità chiara o scura del lettore. I colori impostati da te vengono usati esattamente come li scrivi e non vengono mai adattati, quindi imposta sempre insieme sfondo e testo — un blocco che ne imposta solo uno dei due può risultare illeggibile nella modalità che non hai provato.

Un'anteprima parte da circa 360 pixel di altezza e poi segue il proprio contenuto: un contenuto più alto fa crescere il blocco, uno più corto lo fa rimpicciolire. Quell'altezza iniziale è anche il riferimento con cui vengono risolte le unità relative, quindi height: 100%, 100vh e window.innerHeight funzionano tutti — è proprio ciò che usano di solito le scene three.js e i grafici a tutta area.

Gli errori di script, i rifiuti di promise non gestiti e l'output di console.error/console.warn prodotti all'interno dell'anteprima vengono raccolti e mostrati sotto di essa, con i numeri di riga quando il browser li segnala. Un'anteprima non ha strumenti per sviluppatori propri, quindi è in questo pannello che un blocco spiega perché non è stato renderizzato.

Grafici dai dati del documento

Un blocco può leggere dati che si trovano già nello stesso documento, così un grafico resta allineato ai numeri che i suoi lettori vedono. Si possono nominare quattro tipi di sorgente. Un blocco di codice json, csv, tsv o yaml si nomina sulla propria riga di apertura, per esempio con name=sales. Una tabella si nomina con una riga di commento HTML collocata immediatamente sopra: <!-- strata:name=headcount -->. Il frontmatter del documento è sempre disponibile con il nome riservato frontmatter, solo per i campi scalari. Un'immagine del documento si nomina come una tabella, con una riga di commento HTML collocata immediatamente sopra: <!-- strata:name=hero -->. Nell'editor seleziona l'immagine e usa Nome per i dati. Questi quattro tipi sono gli unici dati a cui un blocco può collegarsi. Un nome inizia con una lettera, prosegue con lettere, cifre, trattini o trattini bassi, arriva al massimo a 64 caratteri e deve essere unico all'interno del documento.

Un blocco html dichiara ciò che consuma sulla propria riga di apertura, per esempio con uses="sales,headcount". Un blocco riceve soltanto le sorgenti che nomina e mai il resto del documento, non può raggiungere dati di un altro documento e non gli arriva nulla che il suo lettore non possa già vedere qui. Modificare il codice del blocco o la sua dichiarazione ricarica l'anteprima da uno stato pulito. Modificare solo i dati dietro un nome già dichiarato aggiorna l'anteprima in corso senza riavviarla. Un blocco dichiara al massimo otto nomi e ogni nome oltre l'ottavo arriva come unavailable con motivo oversize invece di essere scartato in silenzio.

Dentro l'anteprima i dati dichiarati vengono installati come strata.data prima che vengano eseguiti i tuoi script. strata.data.get(name) restituisce una sorgente e strata.data.names elenca i nomi dichiarati dal blocco, nell'ordine della dichiarazione. Una sorgente json, csv, tsv o yaml arriva non analizzata come { kind: 'text', format, text }, quindi è il blocco ad analizzarla con il parser che preferisce. Una tabella arriva come { kind: 'table', columns, rows } con ogni cella come testo semplice e senza conversioni numeriche o di data. Il frontmatter arriva come { kind: 'frontmatter', values }. Ogni valore consegnato è congelato in profondità. Quando una sorgente collegata cambia, Strata invia un nuovo snapshot e genera l'evento strata:data su window, il cui detail porta i nuovi dati. strata.data.get restituisce già quello snapshot nel momento in cui l'evento viene generato. L'anteprima non richiede mai dati da sé, quindi un blocco che ignora l'evento continua a funzionare con ciò che ha ricevuto all'inizio.

Un'immagine arriva come { kind: 'image', url, width, height, alt }, dove url è un URL di dati che porta i byte dell'immagine stessa, quindi un blocco può assegnarlo direttamente a un elemento img senza alcun accesso alla rete. Strata recupera quei byte con l'accesso del lettore e li incorpora prima che l'anteprima parta; l'anteprima non vede mai un collegamento da seguire e non richiede mai un'immagine per conto proprio. Le immagini hanno un budget separato: una singola immagine può consegnare fino a 3 MiB e tutte le immagini di un'anteprima fino a 12 MiB complessivi, scartando prima le più grandi se quel budget si esaurisce. Un'immagine i cui byte non sono stati recuperati arriva come unavailable con il motivo unreachable. Una presentazione può mostrare un'immagine nominata senza alcun codice: una riga di apertura di diapositiva scritta come layout=image uses="hero" la disegna a tutta pagina e legge la didascalia dal corpo della diapositiva.

Quale tipo scegliere dipende da chi altro deve leggere i numeri. Un blocco json o csv è compatto, si confronta bene tra una versione e l'altra e tiene una serie lunga fuori dal testo, ma arriva come testo grezzo ed è il blocco a doverlo analizzare; dividere una riga csv sulle virgole è l'errore classico, perché spezza qualsiasi campo tra virgolette che ne contenga una. Una tabella con nome rappresenta il compromesso opposto: i lettori vedono una tabella vera invece di un blocco di codice, e il blocco la riceve già suddivisa, con la prima riga come columns e ogni riga successiva in rows. Il frontmatter va bene per valori singoli, come un titolo o un obiettivo, non per una serie.

Un nome dichiarato che non può essere risolto arriva comunque, come { kind: 'unavailable', reason }, così un blocco può distinguere un insieme di dati vuoto da uno mancante. Il motivo è unknown quando nessuna sorgente del documento porta quel nome, duplicate quando due sorgenti rivendicano lo stesso nome, removed quando la sorgente è stata eliminata mentre l'anteprima era aperta, oversize quando la sorgente supera i limiti di consegna e unreachable quando non è stato possibile recuperare i byte di un'immagine. Viene scartata solo la sorgente interessata e le altre continuano ad arrivare, quindi controlla il tipo unavailable e mostra un messaggio invece di dare per scontato che i dati ci siano.

Librerie approvate

• /sandbox/libs/mermaid.min.js — <script src="/sandbox/libs/mermaid.min.js"></script> then mermaid.initialize({ startOnLoad: false }); mermaid.run()
• /sandbox/libs/d3.min.js — <script src="/sandbox/libs/d3.min.js"></script> — global `d3`
• /sandbox/libs/three.module.min.js — <script type="module">import * as THREE from '/sandbox/libs/three.module.min.js'</script>
• /sandbox/libs/doom.js — <script src="/sandbox/libs/doom.js"></script> is the whole block: it appends its own canvas and boots. Options go on the script tag: data-doom-warp="1,1", data-doom-skill="3", data-doom-manual (call Doom.start() yourself). To place the canvas, supply one with id="canvas". The reader clicks the preview once to give it keyboard focus; arrows move, Ctrl fires, Esc opens the menu. Music is off, sound effects work. First load pulls about 10 MB, then caches. Chocolate Doom compiled to WebAssembly (GPL-2.0-or-later, github.com/cloudflare/doom-wasm) with Freedoom game data (BSD-3-Clause, github.com/freedoom/freedoom). No commercial or shareware WAD is distributed.

Nessun altro URL esterno di script o stile viene caricato nell'anteprima. Per bloccare una versione, inserisci -<version> prima di .min.js (le versioni precedenti restano disponibili).

Esempio

<div id="chart"></div>
<script src="/sandbox/libs/d3.min.js"></script>
<script>
  const data = [4, 8, 15, 16, 23, 42];
  d3.select('#chart')
    .selectAll('div')
    .data(data)
    .join('div')
    .style('height', '18px')
    .style('margin', '2px 0')
    .style('background', 'var(--color-primary, #2c7cb0)')
    .style('width', (d) => d * 6 + 'px');
</script>

Esempio: un grafico collegato a un blocco json

```json name=sales
[
  { "quarter": "Q1", "revenue": 42 },
  { "quarter": "Q2", "revenue": 58 },
  { "quarter": "Q3", "revenue": 71 }
]
```

```html uses="sales"
<div id="chart"></div>
<script src="/sandbox/libs/d3.min.js"></script>
<script>
  function render() {
    const source = strata.data.get('sales');
    if (!source || source.kind !== 'text') return;
    d3.select('#chart')
      .selectAll('div')
      .data(JSON.parse(source.text))
      .join('div')
      .style('height', '18px')
      .style('margin', '2px 0')
      .style('background', 'var(--color-primary, #2c7cb0)')
      .style('width', (d) => d.revenue * 6 + 'px');
  }
  render();
  window.addEventListener('strata:data', render);
</script>
```

Esempio: un grafico collegato a un blocco csv

```csv name=signups
week,signups
"Jan 1, 2026",120
"Jan 8, 2026",148
"Jan 15, 2026",173
"Jan 22, 2026",162
```

```html uses="signups"
<div id="chart"></div>
<script src="/sandbox/libs/d3.min.js"></script>
<script>
  function render() {
    const chart = d3.select('#chart');
    chart.selectAll('*').remove();
    const source = strata.data.get('signups');
    if (!source || source.kind !== 'text') {
      chart.text('No signups data.');
      return;
    }
    // A csv source arrives as raw text. text.split(',') would tear
    // "Jan 1, 2026" in half; d3.csvParse honours the quotes.
    const rows = d3.csvParse(source.text, (row) => ({
      week: row.week,
      signups: Number(row.signups),
    }));
    const scale = d3
      .scaleLinear()
      .domain([0, Math.max(1, d3.max(rows, (d) => d.signups) || 0)])
      .range([0, 100]);
    const line = chart.selectAll('div').data(rows).join('div');
    line
      .style('display', 'flex')
      .style('align-items', 'center')
      .style('gap', '8px')
      .style('margin', '2px 0');
    line
      .append('span')
      .style('flex', '0 0 7rem')
      .style('color', 'var(--color-muted-foreground, #6b7280)')
      .text((d) => d.week);
    line
      .append('span')
      .style('height', '18px')
      .style('background', 'var(--color-primary, #2c7cb0)')
      .style('width', (d) => scale(d.signups) + '%');
    line.append('span').text((d) => d.signups);
  }
  render();
  // Edit a number in the csv block and this chart follows it.
  window.addEventListener('strata:data', render);
</script>
```

Esempio: un grafico collegato a una tabella del documento

<!-- strata:name=headcount -->

| Team | People |
| --- | --- |
| Growth | 12 |
| Platform | 27 |
| Support | 8 |

```html uses="headcount"
<div id="chart"></div>
<script>
  function render() {
    const chart = document.getElementById('chart');
    chart.textContent = '';
    const source = strata.data.get('headcount');
    if (!source || source.kind !== 'table') {
      chart.textContent = 'No headcount table.';
      return;
    }
    // columns is the table's first row; rows is everything under it, and
    // every cell is a string, so the numbers are yours to convert.
    const team = source.columns.indexOf('Team');
    const people = source.columns.indexOf('People');
    const counts = source.rows.map((row) => Number(row[people]) || 0);
    const widest = Math.max(1, ...counts);
    source.rows.forEach((row, index) => {
      const line = document.createElement('div');
      line.style.display = 'flex';
      line.style.alignItems = 'center';
      line.style.gap = '8px';
      line.style.margin = '2px 0';
      const label = document.createElement('span');
      label.style.flex = '0 0 7rem';
      label.style.color = 'var(--color-muted-foreground, #6b7280)';
      label.textContent = row[team];
      const bar = document.createElement('span');
      bar.style.height = '18px';
      bar.style.width = (counts[index] / widest) * 100 + '%';
      bar.style.background = 'var(--color-primary, #2c7cb0)';
      const value = document.createElement('span');
      value.textContent = row[people];
      line.append(label, bar, value);
      chart.append(line);
    });
  }
  render();
  // Type a new number into the table and this chart follows it.
  window.addEventListener('strata:data', render);
</script>
```

Esempio: un'immagine collegata a un'immagine del documento

<!-- strata:name=hero -->

![The team on launch day](strata://image/img_01ARZ3NDEKTSV4RRFFQ69G5FAV)

```html uses="hero"
<figure id="card" style="margin:0"></figure>
<script>
  function render() {
    const card = document.getElementById('card');
    card.textContent = '';
    const source = strata.data.get('hero');
    if (!source || source.kind !== 'image') {
      card.textContent = 'No hero image.';
      return;
    }
    const image = document.createElement('img');
    // url already carries the bytes, so this needs no network access.
    image.src = source.url;
    image.alt = source.alt;
    image.style.width = '100%';
    image.style.borderRadius = '12px';
    const caption = document.createElement('figcaption');
    caption.style.color = 'var(--color-muted-foreground, #6b7280)';
    caption.textContent = source.width + '×' + source.height;
    card.append(image, caption);
  }
  render();
  // Swap the image in the document and this card follows it.
  window.addEventListener('strata:data', render);
</script>
```

La definizione di un agente è un documento Markdown nella cartella /Agents. Il frontmatter YAML dichiara l'identità dell'agente, l'elenco degli strumenti consentiti e la visibilità presso l'orchestratore; il corpo sotto il frontmatter è il prompt di sistema a cui l'orchestratore passa la richiesta dell'utente così com'è. Ogni campo viene convalidato lato server al salvataggio.

Esempio

---
name: meeting-notes-summarizer
description: Summarizes meeting notes into a TL;DR with action items.
tools:
  - read_document
  - search_space
model: claude-sonnet-4-6
color: emerald
enabled: true
autoInvokable: false
---

You are a meeting-notes summarizer. Given the document body the
orchestrator hands you verbatim, produce a one-paragraph TL;DR and a
bulleted action-item list…

Un modello di prompt è un documento Markdown nella cartella /Prompts. Il frontmatter YAML dichiara nome, descrizione, argomenti e visibilità presso l'orchestratore del prompt; il corpo sotto il frontmatter è il modello vero e proprio — i segnaposto {{argument}} vengono sostituiti al momento del rendering. I valori degli argomenti vengono raccolti dal pannello slash del compositore di chat o dalla richiesta MCP prompts/get.

PromptArgument

Ogni voce dell'array `arguments` qui sopra ha la struttura seguente:

Esempio

---
name: Summarize document
description: Summarize the active document for a chosen audience.
autoInvokable: false
arguments:
  - name: focus
    description: What the assistant should focus on.
    required: true
  - name: audience
    description: Target audience for the summary.
    required: false
---

Summarize this document for {{audience}}, focusing on {{focus}}. Keep
the summary under 200 words and finish with a short action-items list.

Un modello di documento è un documento Markdown all'interno di una cartella di modelli. Il frontmatter YAML dichiara il nome del modello, le variabili tipizzate e il contratto delle sezioni; il corpo sotto il frontmatter è il contenuto riutilizzabile — i segnaposto {{key}} vengono sostituiti quando si crea un documento dal modello, tramite la galleria, l'azione MCP createFromTemplate o lo strumento create_document_from_template di un agente.

TemplateVariable

Ogni voce dell'array `variables` qui sopra ha la struttura seguente:

TemplateSection

Ogni voce dell'array `sections` qui sopra ha la struttura seguente:

Esempio

---
name: incident-postmortem
description: Standard postmortem with a verbatim escalation matrix.
variables:
  - key: incident_id
    label: Incident ID
    kind: text
    required: true
  - key: occurred_on
    label: Date of incident
    kind: date
    required: true
sections:
  - title: Timeline
    guidance: Chronological events from first alert to resolution.
    fill: required
  - title: Lessons learned
    guidance: What we change going forward.
    fill: optional
  - title: Escalation matrix
    fill: verbatim
---

## Timeline

Incident {{incident_id}} on {{occurred_on}}.

## Lessons learned

## Escalation matrix

Page the on-call lead, then the service owner…