@nova-lang/cli

Nova

Nested Ordered Versatile Architecture — a programmable markup language.

Nova is not a simple mashup of HTML, YAML, and TeX. It abstracts their strengths into a unified node model — everything is a functional Block with attributes and children.

---

安装 / Install

npm (recommended)

npm install -g @nova-lang/cli
# Requires Zig compiler: https://ziglang.org/download/
nova examples/sample.nv output.html

pip

pip install -e .
nova examples/sample.nv output.html

Zig

zig build
./zig-out/bin/nova examples/sample.nv output.html

---

Nova 语法规范 v1.0 / Language Specification

核心理念 / Core Design

• 一切皆块 / Everything is a Block — document elements, metadata, styles, data types, and macros all share one syntax form.
• 缩进定界 / Indentation-based — block content is delimited by indentation (like YAML/Python), no closing tags needed.
• 标签即函数 / Tags are Functions — block types are invoked with @command, attributes in (), children in indented {} — functional markup.
• 双模数据 / Dual-mode Data — natural inline writing for prose, compact CSV-like tables or external references for data.
• 强类型可编译 / Strongly Typed — embed type definitions and interfaces, generate code or validate data directly.
• 数学与宏不变质 / Math & Macros — retains TeX's powerful typesetting, unified into one syntax.

English · 中文

---

1. 基础词法 / Lexical Basics

// single-line comment
/* multi-line
    comment */

// document metadata
@meta {
    title: "Nova Example"
    author: Li Hua
    date: 2026-06-20
}

// importing external packages
@use "nova/std/typography"
@use "nova/schema/gencode"

Token	Examples	Notes
字符串 / String	"double" 'single'	Supports #{...} interpolation
数字 / Number	42 3.14 6.02e23 0xAB	Integer, float, hex, scientific
布尔与空 / Bool & Null	true false null
标识符 / Identifier	[a-zA-Z_][a-zA-Z0-9_-]*

---

2. 块语法 / Block Syntax

A block's basic form:

@BlockName(attr1: val, attr2: val) optional inline text {
    child block 1
    child block 2
}

• No children → omit braces: @image(src: "photo.png", alt: "avatar")
• Anonymous block → unnamed container, acts like <div> or YAML mapping.
• Attributes in (), comma-separated, : or = for key-value pairs, boolean attrs can omit value.
• Children must be indented 2 spaces deeper than parent.

示例 / Example

@page {
    @header {
        @title "Nova Language Manual"
        @author "Li Hua"
    }
    @body {
        @section(id: "intro") {
            @p "Nova is a new programmable markup language."
        }
    }
}

Equivalent to HTML <page><header><title>...</title>… but without closing tags, structure clearly expressed by indentation.

---

3. 内联元素与格式 / Inline Elements & Formatting

Inline content uses @tag{ text } or @tag(attrs){ text }:

Text with @em{emphasis} and @strong{bold},
a @a(href: "https://nova-lang.org"){link} and @code{print(x)}.

Similar to TeX's \emph{...}, but with unified attribute syntax.

Math — TeX syntax embedded directly:

• Inline: $E = mc^2$
• Display: $ \sum_{i=1}^n i = \frac{n(n+1)}{2} $
• Block form: @equation { x = \frac{-b \pm \sqrt{b^2-4ac}}{2a} }

---

4. 列表与映射 / Lists & Maps

Unordered (- or *):

@ul {
    - Apple
    - Banana
    - Orange
}

Ordered (+):

@ol {
    + Step one
    + Step two
}

Maps — key-value pairs:

@config {
    host: "localhost"
    port: 8080
    timeout: 30s
}

List items can be blocks themselves:

- @p "First point with details"
  @note "Supplementary info"
- @p "Second point"

---

5. 表格系统 / Tables

5.1 Inline 2D Array (CSV style)

@table {
    [["Name", "Age", "City"],
     ["Alice", 30, "Beijing"],
     ["Bob", 25, "Shanghai"]]
}

5.2 Block table with headers

@table {
    @header { Name, Age, City }
    @row { Alice, 30, Beijing }
    @row { Bob, 25, Shanghai }
}

5.3 External data reference

@table(src: @csv("data/measurements.csv"), caption: "Measurement Data")

---

6. 宏与变量 / Macros & Variables

Define macros with @def or @macro, supporting positional, keyword, and block parameters.

@def greet(name) {
    @p "Hello, #{name}!"
}

@def framed(title: String = "Notice", @content) {
    @div(style: "border") {
        @strong "#{title}"
        @content
    }
}

@greet("World")
@framed("Warning") {
    This is important information.
}

Calls are syntactically identical to regular blocks — markup is code.

---

7. 类型定义与代码生成 / Types & Code Generation

Define strongly-typed schemas for code generation, data validation, or API contracts.

@schema(Person) {
    id: Int32 @1
    name: String @2 = ""
    email: String? @3       // ? means optional
    tags: List<String> @4
}

@service(UserAPI) {
    getUser(id: Int32) -> Person
    listUsers() -> List<Person>
    updateUser(id: Int32, data: UpdateMask) -> Person
}

The compiler can output Go structs, Protobuf, JSON Schema, or Python dataclasses.

---

8. 交叉引用与参考文献 / Cross-references & Bibliography

• Label: @label(identifier)
• Reference: @ref(identifier)
• Citation: @cite(key)

@chapter(id: "intro") {
    @title "Introduction"
    @label(sec:intro)
}

See @ref(sec:intro) for discussion. This method originates from @cite(lamport94).

@bibliography {
    @entry(key: lamport94, type: book,
            author: "Leslie Lamport",
            title: "LATEX: A Document Preparation System",
            year: 1994)
}

---

9. 流程控制 / Flow Control

• Conditional: @if(condition) { ... } @else { ... }
• Loop: @for(item in list) { ... }

@if(@defined(debug)) {
    @warn "Debug mode: #{value}"
}

@ul {
    @for(user in users) {
        - @strong(user.name) (#{user.email})
    }
}

Documents become living documents with lightweight logic, not just static text.

---

10. 完整综合示例 / Complete Example

@use "nova/std"
@use "nova/plot"

@meta {
    title: "Nova Language Whitepaper"
    authors: ["Li Hua", "Zhang Wei"]
    version: 1.0
}

@page {
    @title "Nova Language Whitepaper"

    @abstract {
        Nova unifies document and data, providing an unprecedented authoring experience.
        See @ref(sec:design) for details.
    }

    @chapter(id: "intro") @label(sec:intro) {
        @p "This paper describes Nova's syntax and design philosophy."
        @p "Math example: conservation of energy $E = mc^2$."
    }

    @chapter(id: "design") @label(sec:design) {
        @p "Core architecture is based on unified functional blocks."
        @table(caption: "Language Comparison") {
            @header { Feature, HTML, YAML, TeX, Nova }
            @row { Tags, ✅, ❌, ✅, ✅ Functional }
            @row { Indentation, ❌, ✅, Partial, ✅ }
            @row { Math, ❌, ❌, ✅, ✅ }
            @row { Type Defs, ❌, ❌, ❌, ✅ }
        }
    }

    @chapter(id: "api") {
        @p "Data model definition:"
        @schema(Measurement) {
            sensor_id: Int32 @1
            value: Float64 @2 = 0.0
            unit: String @3 = "mV"
        }
    }

    @bibliography {
        @entry(key: nova2026, title: "Nova Language Spec", year: 2026)
    }
}