DEV Community

Cover image for I Built VoxMark — A Declarative Language for Interactive Documents and Web Applications
Divyanshu Sinha
Divyanshu Sinha

Posted on

I Built VoxMark — A Declarative Language for Interactive Documents and Web Applications

#opensource #webdev #voxmark #documentation

Over the past several months, I've been working on VoxMark, a project that started as an idea to make writing interactive documents simpler.

Today, I'm excited to share that VoxMark 1.0.0 is officially available on PyPI.

What is VoxMark?

VoxMark is a declarative markup language built around VML (VoxMark Language). It extends familiar Markdown-style authoring with interactive widgets, layouts, and application-oriented components while compiling to static web assets.

Instead of writing large amounts of HTML, CSS, and JavaScript, you describe your document using VML syntax.

For example:

::alert[success]{
Your project has been built successfully.
}
Enter fullscreen mode Exit fullscreen mode 
::card[Welcome]{
This content is inside an interactive card.
}
Enter fullscreen mode Exit fullscreen mode 
::icon[rocket|1.2em|#f59e0b]{} Launch
Enter fullscreen mode Exit fullscreen mode

The compiler generates HTML, CSS, a lightweight JavaScript loader, and a WebAssembly module. The JavaScript's role is simply to bootstrap the page and load the compiled WebAssembly module, where the runtime logic resides.

Features

Current features include:

  • Interactive widgets
  • Cards, alerts, tabs, timelines, progress bars, badges, collapsible sections, and more
  • Built-in SVG icon library with 209 icons
  • Syntax highlighting
  • Variables and reusable components
  • Include system for modular documents
  • HTML generation
  • WebAssembly modules
  • Development server
  • Project scaffolding
  • Source formatter
  • Linter
  • AST viewer
  • File watcher for automatic rebuilds

Documentation Written in VoxMark

One milestone I'm particularly happy about is that the official documentation is written entirely in VML.

The documentation isn't written in Markdown and converted later—it is authored directly using the language itself and compiled with the VoxMark compiler.

In other words, VoxMark is now dogfooding its own technology.

Installation

Install directly from PyPI:

pip install voxmark
Enter fullscreen mode Exit fullscreen mode

Show the available commands:

python -m voxmark --help
Enter fullscreen mode Exit fullscreen mode

Create Project:

python -m voxmark init <project name>/

cd <project name>
Enter fullscreen mode Exit fullscreen mode

Edit generated *.vml file inside project directory.

Compile a document:

python -m voxmark compiler --build <file name>.vml -o build/
Enter fullscreen mode Exit fullscreen mode

Serve it locally:

python -m voxmark server build/
Enter fullscreen mode Exit fullscreen mode

How VoxMark Looks After Compilation

One of the goals of VoxMark is to let authors write declarative VML while generating polished, interactive web pages. Here are a few examples of the compiled output.

📊 Graph Widgets

Graph 1

Graph 2

📦 Embedded Content

Embed

🎨 Custom Styling

Custom Style

📈 Charts

Chart

🚀 Hero Sections

Hero Section

Why I Built It

My goal wasn't to replace HTML.

Instead, I wanted a language that lets authors focus on content and structure while still being capable of building interactive documentation and lightweight web applications.

I also wanted the syntax to stay approachable for people already familiar with Markdown while providing richer capabilities through widgets.

What's Next?

This is only the beginning.

Future work includes expanding the widget ecosystem, improving the compiler, enhancing the developer experience, and continuing to refine the language based on feedback from the community.

Links

📦 PyPI: https://pypi.org/project/voxmark/

📖 Documentation: https://divyanshusinha136.github.io/VoxMark-Language/

💻 GitHub: https://github.com/DivyanshuSinha136/VoxMark-Language/

I'd love to hear your thoughts, suggestions, and ideas. Feedback from the developer community will help shape the next versions of VoxMark.

Top comments (0)