VML — VoxMark Language¶

VML (VoxMark Language) is a declarative programming language for building interactive web applications and documents. It combines component-based UI, data binding, conditional rendering, scoped styling, reusable object definitions, routing, and compilation to HTML, CSS, and WebAssembly through the VoxMark compiler.

Table of Contents¶

Installation ¶

Install VoxMark Language using Python Package Manager (pip).

pip install voxmark

Quick Build¶

• Create Project

voxmark init my-project

• Change working directory

cd my-project

• Build the project

voxmark compiler --build index.vml -o build/

Or, set a title.

voxmark compiler --build index.vml -o build/ --title My-Project

• Preview the build Open build/index.html directly, or run the VoxMark server

voxmark server build/

Or, choose a port:

voxmark server --port 7080 build/

Or, bind a host and port:

voxmark server --host 0.0.0.0 --port 7080 build/

::cmd[args]{body}       ← double colon  — most widgets
:::cmd[args]{body}      ← triple colon  — block/layout/structural widgets

::button[primary|https://example.com]{Visit}
::icon[github|1.2em|#7c6dff]{🐙}
::badge[stable|#22c55e]

::tab[Python|Rust]{
python
||
rust
}

::badge[v1.0|#7c6dff]
::progress[72/100|Completion]
::divider[]
::spacer[2em]

::card[Example]{
  Status: ::badge[OK|#22c55e]
  Press ::kbd{Ctrl+S} to save.
  ::alert[info]{Nested alert inside a card body.}
}

::callout[💡]{
**Bold**, *italic*, `inline code`, [links](https://example.com),
and even fenced code blocks all work here.
}

::var[author]{Divyanshu Sinha}
::var[version]{2.0.0}
::var[repo]{https://github.com/DivyanshuSinha136}

Built by **@author** — VoxMark v@version.
[Source code](@repo)

::class_def[School]{
  name:Springfield Elementary
  ||address:742 Evergreen Terrace, Springfield
  ||founded:1953
  ||principal:Principal Skinner
  ||website:https://springfield-elem.edu
}

The school is **@School.name**, founded in @School.founded.
Address: @School.address
Principal: @School.principal — [Website](@School.website)

Content Widgets¶

::card[🚀 Card Title]{
Body content here. Supports **Markdown**, ::badge[tags|#7c6dff], and nested widgets.
}

::card[]{No title — just body content.}
::card[Title]{Body text}

::card[]{No title — just body content.}
::card[Title]{Body text}

::alert[success]{Your document saved successfully.}
::alert[info]{This is an informational note.}
::alert[warn]{Something needs your attention.}
::alert[error]{An error occurred. Check the logs.}

::alert[success]{Your document saved successfully.}
::alert[info]{This is an informational note.}
::alert[warn]{Something needs your attention.}
::alert[error]{An error occurred. Check the logs.}

::callout[💡]{**Pro Tip:** You can use `::var[name]{value}` to define
reusable values and reference them with `@name`.}

::callout[⚠]{Be careful when nesting more than 3 levels of widgets.}
::callout[🔗]{Check the [full docs](https://github.com/DivyanshuSinha136).}

::callout[💡]{**Pro Tip:** You can use `::var[name]{value}` to define
reusable values and reference them with `@name`.}

::callout[⚠]{Be careful when nesting more than 3 levels of widgets.}
::callout[🔗]{Check the [full docs](https://github.com/DivyanshuSinha136/VoxMark-Language).}

::tab[Python|JavaScript|Rust]{
Python
||
JS
||
Rust
}

::timeline{
  Project Kickoff::Started VoxMark as a production-grade document engine.
  ||v1.0 Released::Shipped Markdown + 26 VML widgets with live preview.
  ||v2.0::Added sidebar, router, footer, includes, class system, and forms.
  ||You Are Here::Explore, edit, and create!
}

::progress[72/100|Project Completion]
::progress[3/5|Milestones]
::progress[1/1|Tests Passing]

Status: ::badge[stable|#22c55e]
Version: ::badge[v2.0|#7c6dff]
License: ::badge[MIT|#f59e0b]
Platform: ::badge[Python 3.12|#3b82f6]

:::fold[Click to expand — Advanced Options]{
### Variable System

Define once, use everywhere:

### Nested Widgets

Everything works inside a fold:

::alert[info]{Even alerts.}
::progress[80/100|Even progress bars.]
}

::var[author]{Divyanshu Sinha}

VoxMark uses ::tooltip[LEB128|Unsigned Little-Endian Base-128 variable-length encoding]{LEB128}
encoding in its WASM binary output.

Layout Widgets¶

::columns[1:1]{
**Left column**

Full Markdown here — lists, code, widgets, anything.
||
**Right column**

::alert[info]{Even nested widgets.}
}

::columns[2:1]{
Main content (takes 2/3 width)
||
Sidebar content (takes 1/3 width)
}

:::grid[3|16px]{
::card[Card 1]{Content}
||
::card[Card 2]{Content}
||
::card[Card 3]{Content}
}

:::flex[12px|center|flex-start|wrap]{
::badge[Python|#3b82f6]
||
::badge[NASM|#f59e0b]
||
::badge[Flask|#22c55e]
}

:::hero[#13162a|center|400px]{
# Welcome to VoxMark

The document engine built from **first principles**.

:::btngroup{::button[outline|#]{Get Started}||::button[ghost|#]{Learn More}}
}

:::section[Features|Everything you need|center]{
::columns[1:1:1]{
::card[Fast]{Sub-millisecond rendering.}
||
::card[Secure]{XSS scanning built in.}
||
::card[Extensible]{53+ widget types.}
}
}

:::box[info]{
This is an info box. Useful for highlighting important content.
}

:::div[my-custom-class|my-id|color:red;font-size:1.2em]{
Content with custom styling applied.
}

Center / Right¶

Align block content.

::center{This text and ::badge[content|#7c6dff] are centered.}

::right{Right-aligned text.}

Preview¶

Spacer / Divider¶

Add whitespace or a horizontal rule.

::spacer[2em]         ← vertical whitespace of 2em

::divider[]           ← default styled HR
::divider[dashed]     ← dashed style
::divider[dotted]     ← dotted style
::divider[gradient]   ← gradient fade

Both are bodyless — no {...}.

Preview¶

Typography Widgets¶

Highlight¶

Highlighted / marked text with colour variants.

Normal text, then ::hl[yellow]{important}, ::hl[green]{success},
::hl[pink]{warning}, ::hl[blue]{info}, ::hl[orange]{note}, ::hl[purple]{vml}.

• [colour] — yellow · green · pink · blue · orange · purple
• {text} — inline text to highlight

Preview¶

Normal text, then important, success, warning, info, note, vml.

Styled Bold¶

Bold text with special rendering styles.

::b[gradient]{Gradient}   — multicolour gradient fill
::b[outline]{Outline}     — transparent with a stroke
::b[shadow]{Shadow}       — layered drop shadow
::b[neon]{Neon}           — glowing neon effect
::b[stamp]{STAMP}         — uppercase bordered stamp
::b[underline]{Underline} — accent underline
::b[mono]{mono}           — monospace code-style bold

• [style] — one of the above styles
• {text} — the bold text content

Preview¶

Gradient
Outline
Shadow
Neon
STAMP
Underline mono

Color¶

Inline text with a custom colour.

::color[#ef4444]{Red text}  ::color[#22c55e]{Green text}  ::color[#f59e0b]{Amber text}

• [hex] — any CSS colour value (hex, named, rgb, etc.)
• {text} — text to colour

Preview¶

Glow¶

Glowing text with a custom glow colour.

::glow[#7c6dff]{VoxMark glows in the dark.}
::glow[#38d9a9]{Teal glow}

• [colour] — CSS colour for the glow
• {text} — text to apply the glow effect to

Preview¶

Keyboard Key¶

Render keyboard shortcuts as styled kbd elements.

Press ::kbd{Ctrl+S} to save.
Press ::kbd{Ctrl+Enter} to render.
Press ::kbd{⌘+K} to open command palette.

• {body} — key combination text (raw, not Markdown)

Preview¶

Press Ctrl + S to save. Press Ctrl + Enter to render. Press ⌘ + K to open command palette.

Math¶

Render a LaTeX / KaTeX expression.

::math{E = mc^2}
::math{\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}}
::math{\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}}

• {body} — LaTeX expression (raw, processed by KaTeX)
• KaTeX must be loaded (included automatically in --build output)

Preview¶

Navigation Widgets¶

:::sidebar[My Portfolio|left|260px]{
  Site Name
  ||Home::#home
  ||About::#about
  ||Projects::#projects
  ||---
  ||Contact::#contact
  ||::badge[v2.0|#7c6dff]
}

Router¶

A hash-based single-page router with auto-generated tab navigation.

::router[home]{
  home:Home::# Welcome
  Body of the home page — full Markdown + VML.

  ||about:About::# About
  About page content here.

  ||projects:Projects::# Projects
  ::card[VoxMark]{A compiler built from scratch.}
}

[default_page_id] — the page shown on first load (defaults to first page).

Body segment format: each || segment is page_id:Display Title::page body.

• Direct URL navigation: visiting page.html#about loads the about page immediately
• history.replaceState updates the URL hash without a page reload
• Pages fade in with a CSS animation on each switch
• Nested widgets (cards, badges, progress bars, forms, etc.) work inside every page

Combined with ::include for multi-file sites:

::router[home]{
  home:Home::     
  ||about:About:: 
  ||work:Work::   
}

Footer¶

A site footer with an optional multi-column layout and copyright bar.

::footer[© 2025 Divyanshu Sinha|#7c6dff]{
  **VoxMark**
  A custom Markdown + VML engine.
  ::badge[Open Source|#22c55e]
  ||
  **Navigation**
  [Home](#home) · [About](#about) · [Projects](#projects)
  ||
  **Connect**
  ::icon[github|1em|#7c6dff]{} [GitHub](https://github.com/DivyanshuSinha136)
  ::icon[mail|1em|#38d9a9]{} [Email](mailto:you@example.com)
}

Arguments ([copyright|accent]):

Body:

• Single segment → full-width centered block
• Multiple || segments → flex columns, wrapping on mobile

Each column renders its own mini VML + inline-Markdown pass, so badges, icons, links, and bold/italic text all work inside footer columns.

Media & Embed Widgets¶

::icon[github|1.2em|#7c6dff]{🐙}
::icon[rocket|1em|#f59e0b]{}
::icon[check-circle|1em|#22c55e]{} Done

Icon Card¶

A card with a large icon, title, and description text.

::iconcard[rocket|Fast Render]{Sub-millisecond VML transforms.}
::iconcard[lock|Secure]{XSS scanning and rate limiting built in.}
::iconcard[layers|Extensible]{53+ widget types and growing.}

• [icon-name|title] — icon from the built-in set and card title
• {body} — description text

Best used inside :::grid or ::columns for a feature-cards layout.

Preview¶

Inline SVG¶

Render raw SVG directly in the document. Uses triple-colon.

:::svg{

}

• {body} — raw SVG markup, sanitised server-side
• No [args] needed

Preview¶

¶

Embed¶

Embed external content of many types.

::embed[youtube]{https://www.youtube.com/watch?v=dQw4w9WgXcQ}
::embed[github]{https://github.com/DivyanshuSinha136/VoxMark}
::embed[spotify]{https://open.spotify.com/track/...}
::embed[codepen]{https://codepen.io/pen/...}
::embed[map]{https://maps.google.com/...}
::embed[pdf]{/docs/spec.pdf}
::embed[audio]{/assets/music.mp3}
::embed[image]{https://example.com/photo.jpg}
::embed[site]{https://example.com}

• [type] — youtube · github · spotify · codepen · map · pdf · audio · image · site
• {src} — the URL or path to embed

Form Widgets¶

Input¶

A styled form input field.

::input[text|Enter your name|inp-name]{Full Name}
::input[email|you@example.com|inp-email]{Email Address}
::input[password|••••••••|inp-pw]{Password}
::input[number|0|score|50|0|100|1]{Score (0–100)}
::input[date||dob]{Date of Birth}
::input[range||brightness|75|0|100]{Brightness}
::input[color||accent|#7c6dff]{Accent Colour}
::input[file||upload]{Upload File}

Arguments ([type|placeholder|id|default|min|max|step]):

{body} — visible label text (above the input)

Supported types: text · email · password · number · url · tel · search · date · datetime-local · time · range · color · file

Range inputs get a live numeric readout. Color inputs get a swatch preview.

Preview¶

Checkbox¶

A styled checkbox with a label.

::checkbox[agree|yes]{I agree to the terms and conditions.}
::checkbox[newsletter|yes|checked]{Subscribe to newsletter (pre-ticked)}

Arguments ([id|value|checked]):

{body} — checkbox label text

Select¶

A styled dropdown select.

::select[country|IN|Country]{
  US:United States|UK:United Kingdom|IN:India|JP:Japan|DE:Germany
}

::select[size||T-Shirt Size]{S|M|L|XL|XXL}

Arguments ([id|default|label]):

{body} — pipe-separated options:

• Plain: Small (value = label)
• With value: S:Small (value S, displays Small)

Preview¶

Button¶

A styled button / link.

::button[primary|https://github.com]{Visit GitHub}
::button[secondary|#about]{Learn More}
::button[ghost|mailto:you@example.com]{Send Email}
::button[outline|#]{Read Docs}
::button[danger|#delete]{Delete}
::button[success|#]{Confirm}

Arguments ([style|action]):

{body} — button label, supports inline VML like ::icon and ::badge

Preview¶

Button Group¶

A group of buttons rendered inline. Uses triple-colon.

:::btngroup{
  ::button[primary|#]{Get Started}
  ||::button[ghost|#]{Learn More}
  ||::button[outline|https://github.com]{GitHub}
}

• {button0||button1||…} — each segment is a ::button widget or any inline content

Preview¶

Control Flow Widgets¶

All control-flow widgets are client-side — the condition is evaluated in the browser using Function("return (expr)")() with a character-class safety filter. They are evaluated once at page-load.

If¶

Show content when a JavaScript expression is truthy.

::if[window.innerWidth > 768]{Wide-screen layout — only visible on desktop.}

::if[navigator.language.startsWith('en')]{English content.}

::if[document.documentElement.dataset.theme === 'dark']{Dark mode content.}

• [condition] — JS expression (sanitised to [A-Za-z0-9_.\\s<>=!&|()])
• {body} — content shown when condition is truthy

Else¶

Show content when the same expression is falsy. Pair with a preceding ::if.

::if[window.innerWidth > 768]{Wide layout.}
::else[window.innerWidth > 768]{Narrow / mobile layout.}

• Uses the same condition string as the matching ::if

If / Else (inline)¶

Compact inline branch — shows one of two segments based on a condition.

::ifelse[navigator.onLine]{
  You are **online** — live features active.
  ||
  You are **offline** — some features unavailable.
}

• {then||else} — two segments: first shown if truthy, second if falsy

CSS Widgets¶

Scoped CSS Block¶

Define CSS that applies to the current document scope. Uses triple-colon.

:::css{
.my-box {
  background: linear-gradient(135deg, #7c6dff22, #38d9a911);
  border: 1px solid #7c6dff44;
  border-radius: 12px;
  padding: 20px 24px;
}
.my-box h3 {
  color: #7c6dff;
  margin: 0 0 8px;
}
}

::class[my-box]{### Scoped styles applied here

This block uses the styles defined above.}

• {body} — raw CSS (not processed through Markdown)
• Styles are injected via a style tag in the page

Preview¶

CSS Playground¶

A live split-editor showing CSS and HTML side-by-side with instant preview. Uses triple-colon.

:::cssplay{
.card {
  background: linear-gradient(135deg, #7c6dff, #38d9a9);
  padding: 24px; border-radius: 16px; color: white;
}
||

  
Live Preview
  
Edit the CSS pane to see changes instantly.

}

• {css||html} — two segments: CSS in the first, HTML in the second

Preview¶

CSS Variable¶

Define a CSS custom property (--variable) for the document scope.

::cssvar[--brand]{#7c6dff}
::cssvar[--accent2]{#38d9a9}
::cssvar[--gap]{16px}

Then use it in any :::css{} block:

:::css{
.branded {
  border-left: 4px solid var(--brand);
  background: color-mix(in srgb, var(--brand) 10%, transparent);
}
}

• [--property-name] — the CSS custom property name (must start with --)
• {value} — the property value

Inline Style¶

Apply arbitrary inline CSS to a block of content.

::style[display:flex;gap:12px;flex-wrap:wrap;margin:.5em 0]{
  ::style[background:#7c6dff;color:#fff;padding:10px 18px;border-radius:10px;font-weight:700]{Primary}
  ::style[background:#22c55e22;color:#22c55e;padding:10px 18px;border-radius:10px;border:1px solid #22c55e44]{Success}
}

• [css-properties] — semicolon-separated CSS property declarations
• {body} — content to wrap in the styled container

Preview¶

CSS Class¶

Apply one or more CSS class names to a block of content.

::class[my-box hero-card]{
### Scoped Class Applied

Content inside this div has `class="my-box hero-card"` applied.
}

• [class-names] — space-separated class name(s)
• {body} — content, Markdown-rendered

Data Visualisation¶

Chart¶

A Chart.js chart powered by a JSON data payload.

::chart[bar]{
{
  "labels": ["Jan", "Feb", "Mar", "Apr", "May"],
  "datasets": [{
    "label": "Revenue ($k)",
    "data": [42, 58, 37, 71, 63],
    "backgroundColor": ["#7c6dff","#38d9a9","#f59e0b","#ef4444","#3b82f6"]
  }]
}
}

• [type] — bar · line · pie · doughnut · radar · polarArea
• {body} — Chart.js-compatible JSON { labels, datasets } object
• Chart.js must be loaded (included automatically in --build output)

Preview¶

Graph¶

A rich server-side data graph with built-in themes.

::graph[bar|Monthly Revenue|purple|280px]{
{
  "labels": ["Jan","Feb","Mar","Apr"],
  "data":   [42, 58, 37, 71]
}
}

::graph[area|Monthly Revenue|purple|280px]{
{
  "labels": ["Jan","Feb","Mar","Apr"],
  "data":   [42, 58, 37, 71]
}
}

• [type|title|palette|height] — chart type, display title, colour palette, container height
• {body} — simplified JSON { labels, data } object

Preview¶

Graph Playground¶

An interactive graph editor. Uses triple-colon.

:::graphplay{{"type":"bar","data":{"labels":["Mon","Tue","Wed","Thu","Fri","Sat","Sun"],"datasets":[{"label":"Visitors","data":[320,450,280,690,510,820,430]},{"label":"Conversions","data":[32,45,28,69,51,82,43]}]}}}

Preview¶

Demo Sandbox¶

A live HTML/CSS sandbox. Uses triple-colon.

:::demo{

  
✦ Live Demo
  
This HTML is editable and renders live.

}

• {body} — raw HTML rendered in a sandboxed iframe
• The source is shown in an editable textarea; clicking ▶ Run re-renders

Preview¶

Build-time Widgets¶

Include¶

Read another .vml file from disk and inline its fully-rendered output here.

• [path] — path relative to the current source file
• Allowed extensions: .vml · .md · .txt
• Processed at compile time by voxmark compiler --build
• In the live editor (/api/render), includes render as empty placeholders since there is no filesystem context
• Circular includes are detected and skipped with an HTML comment
• Nesting up to 16 levels deep is supported
• Missing files emit an HTML comment instead of an error

Multi-file project example:

my-site/
  index.vml
  sections/
    home.vml
    about.vml
    contact.vml

index.vml:

:::sidebar[My Site]{Home::#home||About::#about||Contact::#contact}

::router[home]{
  home:Home::  
  ||about:About:: 
  ||contact:Contact:: 
}

::footer[© 2025]{Built with **VoxMark**}

Build with:

voxmark compiler --build index.vml -o build/

CLI Reference¶

voxmark compiler --build input -o build-dir

voxmark server  [--port PORT] [--host HOST] [--open]
voxmark lint [input]
voxmark format [input] [-o output] [-i]
voxmark ast [input] [--json]
voxmark init [directory]
voxmark watch [input] -o build-dir [--port PORT]
voxmark version

Global flags: --verbose / -v · --quiet / -q · --no-color

Quick-reference Table¶