SpecMD - Conditional Markdown

Markdown with variables and conditional blocks. Create a single source document and generate multiple variants for different products, versions, or regions.

Quick Start

1. Create config.yaml

productName: "My Product"
version: 2
isPremium: true

2. Create spec.smd

---
config: ./config.yaml
---

# ${productName} v${version}

@isPremium
  ## Premium Features
  This content only shows when isPremium is true.
@end

3. Preview

Press Alt+D to open preview.

That's it! Change values in config.yaml and see the preview update in real-time.

Features at a Glance

Demo

Variables

Conditions

Switch/Case

File Includes

Syntax Reference

Variables

Use ${variableName} to insert values from config.

Product: ${productName}
Version: ${version}

Conditions

Basic condition:

@isPremium
  Premium content here
@end

With comparison:

@version >= 2
  New features in v2+
@end

With elif/else:

@level >= 3
  Pro user
@elif level >= 2
  Standard user
@else
  Basic user
@end

Nested conditions:

@isPremium
  @version >= 2
    Premium v2+ features
  @end
@end

Alternative @if syntax (both work the same):

@if isPremium
  Premium content
@end

Operators:

Switch/Case

@switch region
  @case "asia"
    100V
  @case "europe"
    230V
  @default
    120V
@end

Multiple values: @case "value1" or "value2"

Include

@include ./header.smd
@include ../common/footer.smd
@include ./data.csv

• Paths are relative to current file
• Ctrl+Click to jump to file
• CSV files are automatically converted to Markdown tables

Table of Contents

# Title

[TOC]

## Chapter 1
## Chapter 2

Config File (YAML)

Basic Variables

productName: "Widget Pro"
version: 2
isPremium: true
voltage: 100

Computed Values ($expr)

voltage: 100

displayVoltage:
  $expr: "voltage == 100 ? '100V' : '230V'"

isHighPower:
  $expr: "voltage >= 200"

label:
  $expr: "isPremium and version >= 2 ? 'Pro v2+' : 'Standard'"

Switch in Config ($switch)

region: "asia"

voltage:
  $switch: region
  asia: 100
  europe: 230
  us: 120
  $default: 100

plugType:
  $switch: region
  asia: "Type A"
  europe: "Type C"
  $default: "Type B"

Linking Config to Document

Option 1: External file

---
config: ./config.yaml
---

Option 2: Inline

---
productName: "Widget"
version: 1
---

Option 3: Both (inline overrides external)

---
config: ./config.yaml
productName: "Custom Name"
---

Editor Features

• Syntax Highlighting - Conditions colored by result (green=true, gray=false)
• Inline Values - See variable values and condition results
• Hover Info - Details on variables and expressions
• Autocomplete - Variables after ${, keywords after @
• Outline - Navigate headings (includes @include files)
• Go to Definition - Ctrl+Click on variables or @include paths
• Diagnostics - Warnings for undefined variables
• Live Preview - Real-time Markdown preview with search (Ctrl+F)
• Auto Format - Shift+Alt+F to auto-indent @if/@switch blocks
• References Panel - See which files @include the current file (in Explorer sidebar)
• Dependency Graph - Visualize @include relationships
• Image Drop - Shift+Drop images to insert as Markdown

Image Drag & Drop

Drag image files into your .smd document while holding Shift to automatically insert a Markdown image reference with a relative path.

Supported formats: PNG, JPG, JPEG, GIF, WebP, SVG, BMP, ICO, TIFF

Example:

1. Drag images/screenshot.png into your document while holding Shift
2. Inserts: ![screenshot](https://github.com/kitsune8848/SpecMD/raw/HEAD/images/screenshot.png)

The alt text is automatically generated from the filename, and spaces are URL-encoded.

Preview Search

Press Ctrl+F in the SpecMD Preview to search within the document:

• Enter or ↓ - Next match
• Shift+Enter or ↑ - Previous match
• Escape - Close search

Auto Format Example

Before formatting:

@isPremium
@version >= 2
Premium v2 content
@end
@end

After Shift+Alt+F:

@isPremium
  @version >= 2
    Premium v2 content
  @end
@end

Commands

Access via Command Palette (Ctrl+Shift+P) or right-click menu.

Table Support

Snippets

Insert Table with Custom Size

1. Open Command Palette (Ctrl+Shift+P)
2. Run "SpecMD: Insert Table"
3. Enter size like 5x10 (5 columns, 10 rows)

Import from CSV

From clipboard:

1. Copy CSV data
2. Run "SpecMD: Insert Table from CSV"
3. Paste CSV

From file:

1. Run "SpecMD: Import Table from CSV File"
2. Select .csv file

Auto-Format Tables

Press Shift+Alt+F to auto-align table columns:

Before:

|Name|Age|City|
|---|---|---|
|Alice|30|Tokyo|
|Bob|25|San Francisco|

After:

| Name  | Age | City          |
|-------|-----|---------------|
| Alice | 30  | Tokyo         |
| Bob   | 25  | San Francisco |

Snippets

Example: Multi-Product Docs

config-basic.yaml:

productName: "Widget Basic"
tier: 1
hasPremium: false

config-pro.yaml:

productName: "Widget Pro"
tier: 3
hasPremium: true

spec.smd:

---
config: ./config-basic.yaml
---

# ${productName}

## Features

@hasPremium
  ### Premium Features
  - Advanced analytics
  - Priority support
@end

@tier >= 2
  ### Extended Features
  Available for Standard and Pro tiers.
@end

Switch between configs using the status bar selector to preview different variants.

License

MIT