Overview

SurfDoc (.surf) is a document format that combines human-readable text with typed structural metadata. Each SurfDoc file contains YAML frontmatter defining document properties -- such as title, type, version, and status -- followed by body content organized through standard headings and typed block directives.

The format was created by CloudSurf Software LLC and is formally defined in the Agent-Ready Documentation Standard (ARDS), currently at version 3.0. The specification is published at surfcontext.org.

Design

SurfDoc's architecture is built on several core design principles:

• Typed blocks -- Content sections use typed block directives (denoted by :: syntax) such as ::summary, ::callout, ::action-items, and ::code. Each block type carries semantic meaning, enabling software to understand not just the text but its role within the document.

• YAML frontmatter -- Every SurfDoc file begins with a structured metadata header specifying properties like document type, version, authorship, status, and relationships to other documents. This metadata layer makes documents queryable and organizable by automated systems.

• Backward compatibility -- SurfDoc files degrade gracefully when opened in standard text editors or Markdown viewers. The typed block directives appear as labeled text sections, and the YAML frontmatter is displayed or hidden according to the viewer's conventions.

• Accessibility by construction -- Accessibility features are expressed as language-level constructs rather than optional attributes. Image blocks require alt text. Document structure enforces heading hierarchy. These constraints are validated at parse time by the surf-parse tool.

• Security by construction -- SurfDoc does not permit arbitrary script execution or raw HTML injection. The format's typed block system restricts content to defined, safe patterns.

• Translation by design -- Document structure and metadata support internationalization natively, enabling automated translation workflows that preserve semantic structure.

Specification

The Agent-Ready Documentation Standard (ARDS) v3.1 defines the complete SurfDoc specification, including all valid block types, frontmatter schema, nesting rules, and rendering behavior. ARDS also specifies how repositories should organize documentation using the SurfContext file structure (.context/ directories, CONTEXT.surf entry points) so that AI agents and other automated tools can discover and navigate project documentation.

The specification is open and published at surfcontext.org.

Parser

surf-parse is the reference parser, validator, and renderer for SurfDoc. Written in Rust, it supports 37 typed block directives and is available as an open-source library.

Adoption

SurfDoc is used across several CloudSurf products:

• Surf Wiki -- Over 900,000 articles stored and rendered in SurfDoc format.
• Surf Docs -- The document workspace at app.surf uses SurfDoc as its native file format.
• WaveSite -- The AI website builder at wave.site generates SurfDoc, which is then compiled into live websites.

File Extension

SurfDoc files use the .surf file extension.

References

• ARDS v3.1 specification
• CloudSurf Software
• surf-parse — Reference parser, validator, and renderer (Rust)
• Surf Wiki — 900,000+ articles in SurfDoc format
• WaveSite — AI website builder using SurfDoc