User Guide

This guide covers everything you need to use CalcMark effectively – from editor shortcuts and export options to the full language feature set. Use the links below to jump to a specific topic, or read through the sections on this page first.

Contents #

• Editor Shortcuts – Keyboard shortcuts for the CalcMark editor
• Locale Formatting – Display numbers in your locale
• Exporting Results – cm convert and cm eval
• Embedded Mode – CalcMark blocks inside standard Markdown files
• Sharing with GitHub Gist – Share and open documents via GitHub Gist
• Language Features
  • Dates & Time – Date creation, relative dates, quarters, fiscal periods, ago/from, end of
  • Units & Measurement – Physical units, conversion, and measurement conventions
  • Currency & Exchange Rates – Exchange rates in frontmatter
  • Frontmatter Directives – Globals, directives, templates, scale and convert
  • Functions & NL Syntax – Built-in functions, NL forms, network, storage, growth
  • Formatting & Display – Rates, dates, napkin math, precise display, percentages
  • Worked Examples & Tips – Complete scenarios, tips, and troubleshooting

Editor Shortcuts #

The CalcMark editor provides keyboard shortcuts for common actions. Press F1 for full help inside the editor.

File #

Edit #

View #

Navigation #

Locale Formatting #

CalcMark can format output numbers using locale-specific decimal and thousands separators. This affects how results are displayed in all output modes (editor, REPL, eval, convert).

Setting Your Locale #

Per-command with the --locale flag:

cm eval --locale=de-DE budget.cm
cm convert doc.cm --to=html --locale=fr-FR

Permanently in your config file:

# ~/.config/calcmark/config.toml
locale = "de-DE"

The --locale flag overrides the config file for that invocation.

Example: Same Document, Different Locales #

Given a CalcMark document:

price = $1500
pi = 3.14159
users = 1500000
weight = 50.5 kg

What Stays the Same #

Regardless of locale, these never change:

• Input syntax – always use . for decimals and , or _ for thousands in your source
• K/M/B/T suffixes – always English letters
• Currency symbols – always prefix position ($, €, etc.)
• CalcMark format – cm convert --to=cm is always locale-independent

JSON Output #

When exporting to JSON, each result includes a locale-formatted display value and structured type information:

cm convert budget.cm --to=json --locale=de-DE

{
  "source": "price = $1500",
  "value": "$1.500,00",
  "type": "currency",
  "numeric_value": 1500,
  "unit": "USD",
  "variable": "price"
}

Use type for dispatch, numeric_value + unit for computation, and value for display. The type, numeric_value, and unit fields are always locale-independent. See Configuration: JSON Output for details.

Exporting Results #

Convert CalcMark files to other formats using cm convert:

cm convert doc.cm --to=html              # HTML to stdout
cm convert doc.cm --to=md -o doc.md      # Markdown file
cm convert doc.cm --to=json              # JSON to stdout
cm convert doc.cm --to=html -T tpl.html  # Custom HTML template

Use cm eval for quick evaluation, or pipe directly into cm:

cm eval budget.cm            # Print final results
cm eval -v budget.cm         # Show all intermediate values
echo "1 + 2" | cm           # Evaluate piped input (auto-detects pipe)
echo "1 + 2" | cm --format json  # JSON output for scripting/agents
cm eval --locale=de-DE budget.cm  # German number formatting

All export formats respect the --locale flag (or config setting) except cm format, which stays locale-independent.

Embedded Mode #

You can embed CalcMark blocks inside standard Markdown files — blog posts, READMEs, Hugo content — and use cm convert --embedded to evaluate just the calculation blocks while leaving everything else untouched.

cm convert report.md --embedded            # Evaluate cm blocks, output to stdout
cm convert report.md --embedded -o out.md  # Write to file

Each ```cm or ```calcmark fenced code block is treated as an independent CalcMark document. Blocks can have their own frontmatter (exchange rates, scale directives), but they don’t share variables with each other. Everything outside the blocks — prose, Hugo frontmatter, footnotes, tables, HTML — passes through byte-for-byte.

This makes CalcMark work like a preprocessor in your static site build pipeline, similar to how D2 handles diagram blocks. See the CLI reference for full details and the embedded datacenter cost example for a complete walkthrough.

Sharing with GitHub Gist #

Share CalcMark documents as GitHub Gists directly from the editor. This feature requires the GitHub CLI (gh) to be installed and authenticated.

Prerequisites #

Install and authenticate the GitHub CLI:

# Install
brew install gh          # macOS
sudo apt install gh      # Debian/Ubuntu

# Authenticate
gh auth login

Share To Gist #

Open the command menu (Ctrl+H or F1), select Share To Gist, then choose visibility (public or secret) and add an optional description. Press Enter to share. The Gist URL is copied to your clipboard.

If you are not authenticated, CalcMark will launch gh auth login interactively and retry after you sign in.

Open From Gist #

Open the command menu, select Open From Gist, then paste a Gist URL or ID. CalcMark fetches the Gist content and loads it into the editor. If the Gist contains multiple files, .cm files are preferred.

Note: Sharing with GitHub Gist is not available in the browser (WASM) build.

Language Features #

The CalcMark language is covered in detail across these sub-pages:

• Dates & Time – Date creation, relative dates (next Friday, this quarter), fiscal periods, ago/from, start of/end of, calendar-correct month arithmetic
• Units & Measurement – Supported units, unit conversion with in/as, and measurement conventions (US, Imperial, Troy)
• Currency & Exchange Rates – Currency conversion using frontmatter exchange rates
• Frontmatter Directives – Global variables, @scale/@globals references, template interpolation, and document-wide scale/convert transforms
• Functions & NL Syntax – All built-in functions with examples, natural language syntax, network/storage/growth domain functions
• Formatting & Display – Rates and over, date arithmetic, napkin math, precise display, capacity planning, multiplier suffixes, percentages
• Worked Examples & Tips – Complete calculation scenarios, organizational tips, and troubleshooting common errors