# Authoring content for VISC

How to write one markdown string that a VISC user pastes into a creation form to get a rich, fully-populated page. Today this works for **locality topics** (citizen dossier pages); future importers (agenda programs, directories, FAQs) will reuse the same contract.

The loop: you compose ONE markdown string following this contract → the user opens the creation form (for topics: their locality page → *Comença un tema*) → pastes it into the **Descripció** field → reviews the detected sections and items in a preview panel → submits. Parsing is deterministic — the same string always produces the same page, no AI on the platform side — so the quality of the result is entirely in the string you write.

## The contract — what each construct becomes

| You write | It becomes |
|---|---|
| `# Títol del tema` (first line) | the page title (max 80 chars) and its URL slug |
| prose before the first `##` | the page description (max 4,000 chars; overflow is cut at a paragraph break with a visible warning) |
| `## Secció` | a section — its title opens every derived entry as a bold lead line |
| `- element` at column 0 (also `* ` / `1. `) | one entry (card) per bullet, when the section has 2 or more |
| indented lines under a bullet | stay inside that entry (wrapped text, nested lists) |
| a section with prose and fewer than 2 bullets | one single entry with the whole section body |
| a short paragraph (≤200 chars) right after a `##` | a lead-in, merged into the section's first entry |
| longer prose between bullets | its own entry |

## Rich content inside an entry

Standard markdown works inside one entry: `[text](https://…)` links and bare URLs (each URL on its own line also gets a link preview card — one fetch per URL, so use real, reachable links), YouTube URLs become a playable embed, `![alt](https://…)` images (https only — a paste cannot upload files), GFM tables, `> ` quotes, ```` ```mermaid ```` diagrams, `**bold**`, `_italics_`, `~strikethrough~`, `` `code` ``. `[900 818 482](tel:900818482)` dials on tap and `[address](mailto:a@b.cat)` opens the mail client — neither href may contain spaces.

## Controlling the layout

Entries render as cards in a masonry grid; each card's width is derived from its heft. Use it deliberately:

- **Small (quarter width):** entry under 200 chars — bare links, one-liners.
- **Large (full width):** entry of 900+ chars, or containing a table or an image.
- **Medium (half width):** everything else.

A good-looking page mixes them: a few Large anchor entries (the key report, a table, a photo), Medium analysis entries, Small link/fact entries.

## Limits

| Limit | Value |
|---|---|
| whole paste | 40,000 chars |
| title | 80 chars |
| description | 4,000 chars |
| one entry | 4,000 chars (auto-split past it, with a warning) |
| entries worth creating | ~10–40 (the page shows 60 max) |
| detection floor | at least 1 section AND 3 entries, or no import is offered |

## Grounding rules

- **Language: Catalan, always.** The platform's content language. Write the whole paste in Catalan even though these docs are in English.
- **Ground every fact in real sources; never invent.** Use real press and official URLs only — a fabricated URL becomes a visibly dead link card that discredits the whole page.
- **Don't put official file/reference numbers inside entries** — tracked references are a separate feature the user adds on the page itself.
- **One provenance per paste.** All entries of one paste share one source chip (Official / Premsa / Ciutadania / Document). If the content mixes provenances, keep the paste to the main batch and let the user add the odd entries by hand.
- **Make each entry self-contained.** Entries are re-ranked by votes, so never encode meaning in their order — that's also why the section title is repeated inside each entry.

## Template

```markdown
# Abocador de Coll Cardús i les olors

El CTR tracta residus de tota la comarca i les queixes per pudor
s'acumulen des de 2019. Aquesta pàgina aplega documents oficials,
premsa i aportacions veïnals per seguir el cas.

## Documents oficials

- **Resolució de l'ARC (2023)** — obre expedient de control d'olors.
  https://arc.gencat.cat/exemple-resolucio
- **Informe municipal d'olors** amb els mesuraments de 2022 i 2023.
- Taula de llindars aprovats (la taula fa l'entrada d'amplada completa):

  | Paràmetre | Llindar |
  | --- | --- |
  | Unitats d'olor | 5 ouE/m³ |

## Cronologia

Els fets principals, dels més antics als més recents.

- **2019** — primeres queixes veïnals registrades a l'Ajuntament.
- **2021** — moció aprovada al ple per exigir mesures correctores.
- **2023** — l'ARC obre expedient i imposa mesures.

## Premsa

- Reportatge comarcal sobre l'onada de queixes.
  https://exemple-mitja.cat/reportatge
- https://www.youtube.com/watch?v=exemple
```