Folio

Notes that bloom. Write prose. Charts, comparisons, timelines and references grow inline. AI agents can read it natively — every Folio document ships data-folio-block markers and JSON-LD out of the box, so ChatGPT, Claude, and Gemini parse it directly without conversion.

Spec v1.0 · Playground · npm @foliolang/cli · npm @foliolang/reader

Try in 30 seconds

Paste this URL into ChatGPT or Claude:

https://folio.dirctable.com/en/examples/folio-retro

Ask: "What's in the comparison block in section 1?"

The AI will read the document structurally and answer correctly — because Folio's HTML output is agent-callable, not just human-readable.

一行启动（本地）

npx @foliolang/cli build article.folio

或全局装：

npm install -g @foliolang/cli
folio build article.folio

需要环境变量：

export DEEPSEEK_API_KEY=sk-...
export ZHIPU_API_KEY=...

使用

folio init                          # 在当前目录生成示例项目
folio dev article.folio             # 本地预览（保存自动刷新）
folio build article.folio           # 编译为 article.html
folio build article.folio --inline  # 单文件版（无外部依赖）
folio build article.folio --pdf     # 同时输出 PDF
folio build article.folio --theme academic
folio cache stats
folio cache clean

.folio 是默认扩展名；解析器同样接受 .md。

语法速览

详见 docs/syntax.md。

设计文档

docs/superpowers/specs/2026-05-12-folio-rebrand-positioning-design.md

v1.0 Highlights

MCP Server

Folio ships a built-in MCP server for agent integration:

folio-mcp          # stdio transport

Exposes four tools: folio_build, folio_publish, folio_list_providers, folio_extract.

20+ Chat Providers

Single OpenAI-compatible factory covers: DeepSeek, OpenAI, Anthropic, Gemini, Zhipu, Moonshot, Qwen, Doubao, Qianfan, Hunyuan, Spark, Yi, StepFun, xAI, Mistral, Cohere, Groq, Together, Fireworks, OpenRouter.

Set the corresponding *_API_KEY environment variable — no config change needed.

5 Image Providers

Zhipu CogView, Gemini image, OpenAI DALL-E, DashScope Wanxiang, Doubao image.

4 Publish Targets

folio publish article.folio --target cloudflare
folio publish article.folio --target github
folio publish article.folio --target netlify
folio publish article.folio --target s3

Plugin Ecosystem

Write your own EnginePlugin, TransformPlugin, PublishPlugin, or ProviderPlugin and load it via:

{ "plugins": ["@your-org/folio-engine-xyz"] }

See docs/plugin-guide.md for the 5-minute authoring guide.

T1 + T2 + T3 Architecture

• T1 — Unified Plugin<I,O> contract; self-describing capabilities, effects, and cost estimates.
• T2 — Build DAG + BuildEventStream with orthogonal aspects: cache, retry, budget, telemetry, progress, cancellation.
• T3 — Tiered content-addressed cache (memory LRU → local fs → S3) keyed by SHA-256 of canonical plugin input.

Opt-in Telemetry

Anonymous aggregate build statistics, default OFF. See PRIVACY.md.