surf-parse 0.10.0

Parser for the SurfDoc format — typed document format with block directives, Markdown-compatible
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

# surf-parse

The **SurfDoc reference implementation** — parser and renderers for the SurfDoc format, a typed document format with block directives for structured documents. Backward-compatible with Markdown.

SurfDoc uses `::directive` blocks to represent data tables, callouts, decisions, metrics, tasks, code, figures, FAQ, pricing tables, landing page sections, and full multi-page site structures. Every block is typed, validated, and renderable to HTML, markdown, LaTeX, Typst, PDF, slides, native block trees, or ANSI terminal output. A `.surf` file without a renderer is still readable plain text.

This crate is the open half of an open-core split (since 0.10.0): it contains everything needed to parse, validate, lint, and render `.surf` documents — the complete format surface. Application-platform tooling built on top of the format (e.g. compiling an app description document into a running service) is out of scope here and not part of this crate's API.

## Usage

```rust
let result = surf_parse::parse("# Hello\n\n::callout[type=tip]\nThis is a tip.\n::\n");

// Render to HTML
let config = surf_parse::PageConfig::default();
let html = result.doc.to_html_page(&config);
```

## Block Types (91)

**Core**: Callout, Code, Data, Decision, Details, Figure, Metric, Quote, Summary, Tasks
**Layout**: Columns, Divider, Section, Tabs
**Web**: BeforeAfter, Comparison, Cta, Embed, Faq, Features, Footer, Form, Gallery, Hero, HeroImage, Logo, Nav, Pipeline, PricingTable, ProductCard, Site, Page, Stats, Steps, Style, Testimonial, Toc
**App Description**: Action, Board, ChatInput, Dashboard, Feed, FilterBar, List, Search
**Compound Widgets**: Chart, Editor, SplitPane
**Infrastructure Manifest**: App, Auth, Binding, Build, Cicd, Concurrency, Crates, Database, Deploy, DeployUrls, Domains, Env, Health, Model, Route, Schema, Smoke, Use, Volumes
**App Format**: AppDeploy, AppEnv
**Compact Display**: Badge, InfoCard, Row
**App Shell / Interactive**: AppShell, BlockEditor, ChatInputSimple, ChatThread, CodeEditor, CommandPalette, Drawer, LogStream, Modal, NavTree, Panel, ProblemList, Progress, Sidebar, SuggestionChips, TabBar, TabContent, Terminal, Toolbar
**Passthrough**: Unknown (unrecognized directives preserved)

## Features

- CommonMark-compatible inline text rendering
- YAML front matter parsing
- 91 typed block directives with attribute parsing
- Renderers: HTML (with embedded CSS), markdown degradation, LaTeX, Typst, ANSI terminal, slides, native block tree (feature `native`), PDF (feature `pdf`)
- Bindings: UniFFI (feature `uniffi`) and WASM (feature `wasm`)
- `surf-lint` CLI (feature `cli`) — format/style lint with auto-fixes
- SurfDocBuilder for programmatic document construction
- Round-trip serialization via `to_surf_source()`
- Structural validation diagnostics
- Multi-page site generation (`::site` + `::page` blocks)
- 20 built-in SVG icons (Lucide-based)
- 6 font presets with Google Fonts auto-import

## License

MIT

## Editor Support

- **VS Code**: [SurfDoc extension](https://marketplace.visualstudio.com/items?itemName=CloudSurf.surfdoc) — syntax highlighting, 49 snippets, file icons. Install: `ext install CloudSurf.surfdoc`

## Links

- [SurfDoc Specification](https://surfcontext.org)
- [Repository](https://github.com/cloudsurf-software/surf-parse)