CLI Reference

htmlc renders Vue Single File Components (.vue) to HTML entirely in Go — no Node.js, no browser, no JavaScript runtime.

Installation

go install github.com/dhamidi/htmlc/cmd/htmlc@latest

render

Renders a .vue component as an HTML fragment (no <!DOCTYPE>). Scoped styles are prepended as a <style> block.

htmlc render [-strict] [-dir <path>] [-layout <name>] [-debug] [-props <json>] <ComponentName>

Flags

-dir stringDirectory containing .vue components. Default: .
-props stringJSON object of props to pass to the component.
-layout stringWrap the fragment in a layout component.
-debugAnnotate output with HTML comments showing render trace.
-strictAbort on missing props.

Examples

# Render a greeting fragment
htmlc render -dir ./templates Greeting -props '{"name":"world"}'

# Render with layout
htmlc render -dir ./templates Article -layout AppLayout -props '{"title":"Hello"}'

# Pipe props from stdin
echo '{"name":"world"}' | htmlc render -dir ./templates Greeting

page

Like render, but outputs a full HTML page (adds <!DOCTYPE html> and injects scoped styles into <head>).

htmlc page [-strict] [-dir <path>] [-layout <name>] [-debug] [-props <json>] <ComponentName>
$ htmlc page -dir ./templates HomePage -props '{"title":"My site"}'
<!DOCTYPE html>
<html>
  <head><title>My site</title></head>
  <body><h1>My site</h1></body>
</html>

build

Walks the pages directory recursively, renders every .vue file as a full HTML page, and writes results to the output directory. The directory hierarchy is preserved.

htmlc build [-strict] [-dir <path>] [-pages <path>] [-out <path>] [-layout <name>] [-debug] [-dev <addr>]

Flags

-dir stringDirectory containing shared .vue components. Default: .
-pages stringRoot of the page tree. Default: ./pages
-out stringOutput directory. Created if missing. Default: ./out
-layout stringLayout component (from -dir) to wrap every page.
-dev stringStart a dev server at addr with live rebuild (e.g. :8080).
-strictAbort on missing props; validate all components before rendering.
-debugAnnotate output with diagnostic HTML comments.

Data files

Props for each page are loaded by merging JSON data files in order (later wins):

  1. pages/_data.json — root defaults (all pages)
  2. pages/subdir/_data.json — subdirectory defaults
  3. pages/subdir/hello.json — page-level props (highest priority)

Examples

# Build with defaults (components in ., pages in ./pages, output to ./out)
htmlc build

# Explicit paths
htmlc build -dir ./templates -pages ./pages -out ./dist

# With a shared layout
htmlc build -dir ./templates -pages ./pages -out ./dist -layout AppLayout

# Development server with live rebuild
htmlc build -dir ./templates -pages ./pages -out ./dist -dev :8080

Layouts

Two patterns for layouts:

Pattern 1 — Component-embedded layout: The page component references the layout directly using slots. No CLI flag needed.

<!-- templates/PostPage.vue -->
<template>
  <AppLayout :title="title">
    <article>{{ body }}</article>
  </AppLayout>
</template>

Pattern 2 — -layout flag: The page renders as a fragment; htmlc passes the HTML as content prop to the layout. The page needs no knowledge of the layout.

<!-- templates/AppLayout.vue -->
<template>
  <html>
    <body>
      <main v-html="content"></main>
    </body>
  </html>
</template>
htmlc build -dir ./templates -pages ./pages -out ./dist -layout AppLayout

props

Lists the props referenced by a component — useful for discovering what data a component expects.

htmlc props [-dir <path>] <ComponentName>
$ htmlc props -dir ./templates Card
title
body
author

Export as shell variables:

$ htmlc props -dir ./templates Card -export
export title=""
export body=""
export author=""

ast

Prints the parsed template as a JSON AST. Useful for debugging parsing problems or understanding how htmlc sees a template.

htmlc ast [-dir <path>] <ComponentName>

help

htmlc help [<subcommand>]
# Show general help
htmlc help

# Show help for a specific subcommand
htmlc help build