A language for documents you can explore.
Try the studio · Use VS Code · Explore examples · Syntax cheatsheet · Read the specification
tinta is a language for interactive documents. It brings writing, data and interaction into a single document. Readers can explore a question, compare scenarios and see how their choices change the explanation.
An article that invites questions. A report where readers can test their assumptions. A guide that gives each reader the explanation they need.
Choose the tool that fits your work. Studio is the local browser editor, the VS Code extension brings authoring into your desktop editor, and the CLI validates and exports documents from the terminal. They share the same language and engine. Exported HTML opens independently of all three.
Write on the left. Read and interact on the right.
The included explorable article, open in tinta studio.
- See your ideas take shape. Write and see the document update beside you. Search, undo and clear error messages help you keep going.
- A starting point when you need one. Browse rendered examples and reusable snippets. Bring an existing Markdown file or import local CSV, JSON and raster images.
- A reader that participates. Move a slider, choose a scenario or inspect a chart. The explanation stays connected to the same underlying data.
- Pick up where you left off. Recovery copies help you return to a draft. Save your work, then export the finished document for your readers.
New documents open ready to type. Existing documents open in Reading mode. Studio runs as a static web app or as a single local HTML file, without an account or backend.
The local VS Code Desktop extension brings .tinta documents into your editor: directive and expression completion, diagnostics, hover help, definitions and references, plus an interactive preview with controls and charts.
Enrich an existing Markdown file into a separate Tinta document, explicitly select local images, open and save source bundles, and export interactive or static HTML. Markdown files keep their normal editing behavior. Image, bundle, enrichment and export commands require workspace trust and explicit confirmation or file choices.
After installing the repository toolchain and dependencies, build the local extension:
pnpm package:vscodeIn VS Code, run Extensions: Install from VSIX…, select build/vscode/tinta-0.1.0-dev.0.vsix, then reload. Open a .tinta file and run Tinta: Open Preview. The installed extension bundles its runtimes; editing requires no global Tinta CLI or separate Node installation.
The extension targets VS Code Desktop 1.141.0 on macOS arm64, Linux arm64 and Windows x64. Remote workspaces and vscode.dev are unsupported. Rename, quick fixes and a formatter are not included.
See the VS Code quickstart for examples, local installation, diagnostics and exports, and the host reference for behavior and limits.
This is a complete document:
@meta (title: "Plan a reading session", locale: "en-US")
@let minutes_per_page = 2
# How much time should we set aside?
@slider pages = 8 (min: 1, max: 40, label: "Pages")
@toggle discussion = false (label: "Include a discussion")
@calc minutes = pages * minutes_per_page + if(discussion, 15, 0)
Reading **{{ pages }} pages** takes about **{{ minutes }} minutes**
with these choices.
@when minutes > 45
Consider dividing the reading into two sessions.
@end
Move the slider. Include a discussion. The total changes, and the advice appears when it becomes relevant. No author JavaScript, event handlers or build setup inside the document.
tinta uses Markdown for text formatting and adds its own syntax for values, calculations, controls, data and conditional content. It supports CommonMark 0.31.2, with pipe tables, task lists and double-tilde strikethrough. A .md file stays in Markdown mode until you explicitly choose Enrich as tinta; the original file is preserved.
Use Node 24.21.0 and pnpm 10.34.6. From a checkout:
pnpm install --frozen-lockfile
pnpm devOpen the loopback URL printed by Vite, then choose Explore examples or New document. You can also open .md, .tinta and .tinta.zip files.
Prefer the production build or a standalone file?
pnpm build
pnpm previewThe static application lives in build/studio/. Hash URLs support refresh without server rewrites.
For a server-free workspace, open build/tinta-studio.html directly in a browser. It contains the editor and its runtimes in one local file. Browser storage and file permissions still depend on the environment; local recovery copies are not a substitute for saving your source.
See the setup and toolchain guide for prerequisites and troubleshooting.
Prefer the command line?
After pnpm build, validate and export an included example:
pnpm --filter @tinta-lang/cli exec tinta check examples/article.tinta
pnpm --filter @tinta-lang/cli exec tinta build examples/article.tinta \
--format interactive --output build/article.interactive.html
pnpm --filter @tinta-lang/cli exec tinta build examples/article.tinta \
--format static --output build/article.static.htmlOpen either output in a browser. Interactive HTML keeps the controls; static HTML captures the visible document with its initial answers. Replacing an existing output requires an explicit --force.
The CLI reference covers validation, enrichment, imports, exports, answer snapshots and exit codes.
Studio targets modern desktop Chromium, Firefox and Safari; the reader and HTML exports also support narrow layouts. Browser storage, file permissions and assistive technology vary by environment. See the usage environments and accessibility requirements. Automated WebKit results do not establish native Safari or iOS compatibility.
| In your document | What it does |
|---|---|
@slider · @toggle · @choice |
Let the reader adjust a number, switch an option or choose a scenario. |
@let · @calc · {{ expression }} |
Connect constants and calculated values to the prose. |
@when · @details |
Adapt an explanation or let the reader open more context. |
@data · @view · @table |
Embed typed data and reuse filtered views across text, tables and figures. |
@chart |
Explore line, area, bar, scatter, pie, donut and histogram figures. |
Charts include keyboard exploration and a complete data table. Compatible charts can bind selection to an existing control; histograms support inspection. Invalid answer updates leave the previous valid document intact.
Start with the cheatsheet, then explore the expression rules, directives, data model and chart specification.
| Document | Try this |
|---|---|
| An article you can explore | Change the growth assumption and inspect a period. |
| A report with shared filters | Watch totals, tables and charts respond to the same view. |
| A guide that adapts | Choose a platform and follow the relevant instructions. |
| Seven ways to see the data | Compare all seven chart types in one document. |
The example collection also includes a minimal starting point, function examples, Markdown enrichment and a portable image bundle.
| Format | What you keep |
|---|---|
.tinta |
Editable UTF-8 source and embedded table data. |
.tinta.zip |
Source together with validated local raster images. |
| Interactive HTML | A complete offline document with controls and its embedded runtime. |
| Static HTML | The resolved visible presentation, without an executable program. |
.tinta.state.json |
Explicitly saved reader answers tied to an exact source fingerprint. |
Interactive HTML includes the complete source, hidden branches and all embedded data. Hidden does not mean private. Static export contains the resolved visible presentation and its referenced images. See the file and export contract for the exact boundaries.
Studio's local recovery stores up to 10 copies and 30 MiB, replacing the oldest copies first. It can be disabled, and copies can be deleted. Reader answers are not automatically persisted. Studio can explicitly export an answers snapshot; the CLI can apply a matching snapshot during export. The VS Code preview keeps answers in memory and can include them in HTML exports, but does not provide snapshot import/export. How saving and recovery work →
CSV and JSON imports in Studio or the CLI copy data into typed document tables; they do not retain a live connection to the original file. Images must be validated local raster files. Use a source bundle when moving a document together with its images. See the data and import rules and file formats.
Documents cannot execute author JavaScript, CSS, HTML, plug-ins or code fences, fetch remote data, or submit forms. Raw author HTML is inert; code fences remain literal examples. Local files and images pass through explicit capability boundaries.
tinta focuses on interactive documents. There is no cloud storage, account system, telemetry, AI feature, website generator or publication service. PDF and flattened Markdown exports are outside the current scope. See the product scope and security model.
The parser and semantic engine are portable TypeScript. The reader and export runtime are independent of React and CodeMirror; those belong to the studio.
| Layer | Documentation |
|---|---|
| Parse and enrich Markdown | Syntax API |
| Compile, evaluate and manage transactional sessions | Engine API |
| Render safe documents, controls and charts | Reader API |
| Integrate editor analysis and native previews | Editor analysis · Webview protocol |
| Understand package boundaries | Architecture · Stack |
| Work with public contracts | Interfaces · Contract rules |
| Looking for | Start here |
|---|---|
| Syntax and complete documents | Cheatsheet · Examples |
| Studio editing, imports, saving and recovery | Editor and reader guide |
| VS Code installation and everyday use | Quickstart · Host behavior and limits |
| Terminal commands and automation | CLI reference |
| Source bundles, answers and HTML exports | File and export formats |
| Language semantics and error codes | Specification · Limits and diagnostics |
| Keyboard use, charts and accessible reading | Accessibility and design |
| Local resource access and untrusted documents | Security model · Security reporting |
| Development setup and checks | Toolchain · Testing · Scripts |
| Package formats and versions | Software distribution |
| Scope and compatibility | Product contract · Decisions · Change control |
Draft language. Working local tools.
Contract revision 1.0-draft.3 targets source-format version 1.0. The repository contains the specification, reusable packages, CLI, Studio and local VS Code extension. The language contract is still a draft; format version 1.0 does not identify a stable tool release. Workspace packages currently use implementation version 0.0.0; the local VSIX uses development version 0.1.0-dev.0.
Read CONTRIBUTING.md, the architecture and compatibility rules before proposing language or contract changes. Report security issues through SECURITY.md.
Run the existing checks
pnpm exec playwright install chromium firefox webkit
pnpm verifypnpm verify runs the infrastructure aggregate. pnpm verify --suite editing adds the implemented document-tooling and editor checks. Dependency auditing needs access to the npm advisory service.
For the native extension, run pnpm verify --suite vscode after provisioning VS Code Desktop and setting TINTA_VSCODE_EXECUTABLE and TINTA_VSCODE_CLI to its executable and CLI launcher. This suite includes local VSIX packaging and installed-extension workflows; missing desktop prerequisites return nonzero. See the native test instructions.
Specification consistency checks use Python's standard library:
python3 scripts/check_spec.py
python3 -m unittest discover -s scripts/tests -vSee testing and performance, conformance fixtures and checker prerequisites.
The original specification, engine, reference tools, fixtures and examples are available under the MIT License. Bundled dependencies retain their own licenses, collected in THIRD_PARTY_NOTICES.txt at the repository root.