DocUP

Document Unambiguous Precise
A document markup language that compiles to a standalone HTML5 file.

---

Table of Contents

• About
• Build from Source
• Example Document
• Usage
• Features (v0.3.1)
• Roadmap: v0.3.0
• Documentation
• Important Links
• Contributing
• License

---

About

This repository is the DocUP compiler.

Document Unambiguous Precise.

DocUP is specified like a programming language. It uses named blocks and explicit scopes, and it parses in one pass, so a given input has one reading.

It is not a Markdown replacement. The markup should stay predictable, fast to parse, and easy to extend.

The compiler writes one HTML5 file. Built-in CSS ships in the output. KaTeX and Google Fonts are linked from CDNs only when the generated page needs them.

---

Build from Source

./build.sh

Clean:

./build.sh clean

---

Example Document

meta {
    title: "Hello DocUP",
    author: "Prathmesh",
    version: "1.0.0"
}

h(1) { Hello, DocUP }

p {
    This is a paragraph with b{bold}, i{italic}, and inline code{let x = 1;}.
}

codeblock(lang: "go", file: "main.go") {!
package main

func main() {
    println("Hello, DocUP!")
}
!}

Output is a single .html file.

---

Usage

docup build hello.du
docup build hello.du -o hello.html
docup build hello.du -o dist/index.html -s style.css
docup build hello.du --verbose
docup build hello.du --quiet

docup watch hello.du
docup watch hello.du --port 3000

docup fmt .
docup fmt hello.du
docup fmt --check
docup fmt hello.du --stdout

docup version
docup help

build compiles once. watch rebuilds on change and serves 127.0.0.1:8080 by default.

fmt rewrites .du files into a stable layout. fmt --check does not write, and it exits 1 if a file would change. After docup fmt, docup fmt --check should pass.

Flags for build and watch:

Flag	Meaning
-o, --output	Output HTML path (default: input path with .html)
-s, --style	CSS file copied into the output
-p, --port	Watch-mode port (default 8080)
-V, --verbose	Stage timings
-q, --quiet	No progress lines

--verbose and --quiet cannot be used together.

---

Features (v0.3.1)

• Metadata (meta): title required when meta is present; also lang, theme, author, version, description, keywords, canonical, image, stylesheet
• Headings (h(1) to h(6), id / class)
• Paragraphs (p)
• Inlines: b, i, strike, code, m, link, fn
• Code blocks (codeblock): lang, file, line_numbers, highlight
• Horizontal rule (hr)
• Lists (list, item): unordered, ordered: true, nestable
• Task lists (task, done)
• Blockquotes (quote, nestable)
• Images (image)
• Tables (table, row, cell, header)
• Callouts (callout): note, tip, warning, danger
• Raw HTML (raw)
• Display math (math) and inline math (m)
• Table of contents (toc)
• Footnotes (footnote, fn)
• Includes (include)
• Custom CSS (--style and meta stylesheet)
• Watch mode with live reload

Language reference: docs/index.du in this repo.

---

Roadmap: v0.3.0

Language:

• list(ordered: true, start: N): ordered list start index
• br {}: explicit line break inside prose
• Prose escapes: \{, \}, \! so reserved characters are literal outside strings
• image("src", href: "url", alt: "..."): image wrapped in a link
• figure("src", alt: "...", caption: "..."): image plus caption
• quote(cite: "url", author: "name"): attribution on a blockquote
• callout(type: "note", title: "..."): custom callout title
• table(caption: "..."): table caption
• cell(colspan: N, rowspan: N): merged cells
• deflist { term { } desc { } }: definition list
• details { summary { } ... }: collapse block
• columns { col { } col { } }: side-by-side columns
• sup { } / sub { }: superscript and subscript
• mark { }: highlight span
• kbd { }: keyboard key
• ref("heading-id"): in-document cross reference, resolved after includes
• include "file.du" (shift: 1): include and bump heading levels
• Numbered display math: math(id: "eq1") plus ref("eq1")
• comment { }: source-only block, dropped from HTML
• id / class on p, list, quote, table, codeblock

Compiler and output:

• docup fmt: rewrite a .du file with a stable layout
• docup ast: print the document AST as JSON
• docup build --fragment: emit body HTML only, no page shell
• Multipage build: one output HTML per root .du in a directory
• Heading auto-numbers: meta { numbering: "true" }, reflected in toc
• Theme toggle in the page: button that sets data-theme
• Heading permalink control: meta { permalinks: "true" }
• dir and lang per block: p(lang: "hi", dir: "ltr")

---

Documentation

The reference is written in DocUP:

cd docs
docup build index.du

docs/index.du is the root file. The other .du files are pulled in with include.

---

Important Links

• Repository: https://github.com/pbarot2009/docup
• License: LICENSE
• Creator: https://github.com/pbarot2009

---

Contributing

Open an issue or a pull request.

---

License

Apache 2.0. See LICENSE.