Developer Reference & Specification

CarbonSheet Schema & Live Render Specification

Detailed guide to the CarbonSheet Zod schema structure alongside live rendered previews of every component element.

1. Overview & Architecture 2. SheetMetadata (Root Schema)3. Code Blocks, Tabs & Annotations 4. Structured Comparison Tables 5. Visual Diagrams (Mermaid / SVG)6. Callouts & Gotchas

1. Overview & Architecture

CarbonSheet follows a Documentation as Code philosophy. Cheat sheets are structured JSON files defined with Zod schemas. They support code highlighting, token callouts, type evaluations, interactive tables, flowcharts, and gotcha callouts.

src/content/sheets/*.json → SheetMetadataSchema.parse() → SubtopicCard Component

2. SheetMetadata (Root Schema)

Top-level properties describing the cheat sheet technology, difficulty, tags, and array of sections.

{
  "id": "kotlin-core",
  "slug": "kotlin",
  "title": "Kotlin Syntax & Patterns",
  "description": "High-density reference guide for Kotlin language constructs.",
  "technology": "Kotlin",
  "category": "Backend",
  "difficulty": "INTERMEDIATE",
  "tags": ["kotlin", "jvm", "android"],
  "aliases": ["kt", "android-kotlin"],
  "relatedSheets": ["java", "android-jetpack-compose"],
  "sections": [ ... ]
}

3. Code Blocks, Tabs & Annotations

Supports syntax highlighting, token callouts, type output arrows (input » output), and external playground links.

Live Rendered Component Preview

Annotated Code Blocks & Type Evaluations

Code blocks support language highlighting, token callout annotations, and type evaluations (input » output).

kotlin

Run in Kotlin Playground

fun <T> processSequence(items: List<T>): Sequence<T> {

return items.asSequence()

.filter { it != null }

.map { transform(it) }

}

Code Annotations:

<T>

Generic type parameter T scoped to function

asSequence()

Creates lazy evaluation pipeline (no intermediate allocations)

processSequence(listOf(1, 2, 3)).toList()»[10, 20, 30]

⚡

Lazy Evaluation

Sequence operations are evaluated lazily. Terminal operators like .toList() trigger execution.

kotlingenericssequences

4. Structured Comparison Tables

Render structured matrices for feature comparison, operational parameters, or protocol benchmarks.

Live Rendered Component Preview

Structured Comparison Table

Tables organize technical parameters, feature flags, or version differences into clear matrix layouts.

Collection Type Characteristics

Collection	Order Preserved	Duplicates	Lookup Time
List / ArrayList	Yes	Allowed	O(1) by index
Set / HashSet	No	Unique Only	O(1) hash lookup
Map / HashMap	No	Unique Keys	O(1) by key
TreeSet / TreeMap	Sorted	Unique	O(log N) tree traversal

⚠️

Thread Safety

Standard collections are not thread-safe. Use ConcurrentHashMap or Collections.synchronizedList for concurrent writes.

collectionsdata-structuresperformance

5. Visual Flowchart Diagrams (Mermaid)

Embedded Mermaid flowcharts render system architecture and decision pipelines directly inline.

Live Rendered Component Preview

Architecture & Flowchart Diagrams

Render live Mermaid flowcharts or SVG diagrams to illustrate data flows and system architecture.

Visual Architecture & Flowchart

Mermaid.js

graph LR A[Client Request] -->|HTTP POST| B(API Gateway) B -->|Validate Token| C{Auth Guard} C -->|Valid| D[Worker Service] C -->|Invalid| E[401 Unauthorized] D -->|Write| F[(Database)]

diagrammermaidarchitecture

6. Callouts & Gotchas

Titled notice boxes with custom icons and color themes (green, amber, blue, red, purple).

💡

Tip CalloutBest practices and optimization advice.

⚠️

Warning CalloutCommon pitfalls, gotchas, and performance caveats.