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. They share the same language and engine, and exported HTML opens independently of all three.

Work in	Use it to
tinta studio	Explore examples, write and preview documents in a browser.
VS Code	Write with completion, diagnostics and an interactive preview.
The CLI	Check documents and create HTML exports from the terminal.

Meet tinta studio

Note

You can try tinta studio in your browser. Open the demo → Explore an example, change a control and watch the document respond. No account needed.

Write on the left. Read and interact on the right.

The updated explorable article, open in tinta studio.

• Write and preview. Write and see the document update beside you. Search, undo and clear error messages help you keep going.
• Start from Markdown or an example. Browse rendered examples and reusable snippets. Bring an existing Markdown file or import local CSV, JSON and raster images.
• Try controls and charts. Move a slider, choose a scenario or inspect a chart. The explanation stays connected to the same underlying data.
• Recover a draft. 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. You can also run it locally.

Write in VS Code

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, 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 a trusted workspace.

After installing the repository toolchain and dependencies, build the local extension:

pnpm package:vscode

In 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.

Use the extension in VS Code Desktop on macOS arm64, Linux arm64 or Windows x64. Remote workspaces and vscode.dev are unsupported. Rename, quick fixes and formatting are not available.

See the VS Code quickstart for examples, local installation, diagnostics and exports, and the host reference for behavior and limits.

A small document, a real interaction

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.

Try it locally

Use Node 24.21.0 and pnpm 10.34.6. From a checkout:

pnpm install --frozen-lockfile
pnpm dev

Open 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 preview

The 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.html

Open 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. Support on Safari and iOS depends on the specific browser and device; see those references for limitations.

More than a slider

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.

Open an example. Change one thing.

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.

Save and share your document

Format	What you keep
.tinta	Editable UTF-8 source and embedded table data.
.tinta.zip	Source together with local PNG, JPEG or WebP images.
Interactive HTML	A complete offline document with controls and its embedded runtime.
Static HTML	The visible result, with fixed values and no interactive controls.
.tinta.state.json	Reader answers saved for this exact document.

Important

Interactive HTML includes the complete source, hidden branches and all embedded data. Hidden content is still present in the file. Static HTML contains only 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 local PNG, JPEG or WebP files. Use a source bundle when moving a document together with its images. See the data and import rules and file formats.

A small language. Clear boundaries.

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. Choose which local images the document can use.

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.

Write with a coding agent

The tinta authoring skill helps Codex and Claude Code write and edit .tinta documents, enrich existing Markdown, and check the result with the local CLI. It includes a platform guide, a time estimate, and a report with shared filters as starting points.

Install the same skill folder in either agent, then ask it to create a document or update one you already have. The skill needs access to local files and a working tinta CLI to validate or export documents.

Build with the engine

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

Documentation

Looking for	Start here
Syntax and complete documents	Cheatsheet · Examples
Studio editing, imports, saving and recovery	Editor and reader reference
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

Status

Draft language. Working local tools.

The language contract is 1.0-draft.3, targeting source-format version 1.0. Its syntax may change before stabilization. The repository includes the specification, reusable packages, CLI, Studio and VS Code extension. See the compatibility rules and changelog for format and software versions.

Contribute

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 verify

pnpm 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 -v

See testing and performance, conformance fixtures and checker prerequisites.

License

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.