QMDC — QMD.md Language Support

The VS Code extension for the QMDC toolchain. Provides language support for QMD.md files — a format for human-readable structured data in Markdown.

Features

Language Support

• Syntax Highlighting for .qmd.md files
• Autocompletion for object IDs, Kinds, namespaces, and references
• Hover preview of object definitions with fields
• Go to Definition (Cmd+Click / F12) for references [[#id]]
• Find All References (Shift+F12) for objects across workspace
• Document Symbols (Cmd+Shift+O) — outline with object hierarchy
• Workspace Symbols (Cmd+T) — search objects across all files
• Rename Symbol (F2) — rename object ID and update all references
• Diagnostics — broken links, duplicate IDs, validation errors

Enhanced Navigation

• Click on ID in definition — shows all references to this object
• Click on Kind in definition — shows all objects of this Kind

Workspace Support

• Multi-file projects with automatic indexing
• Multi-root workspace support — multiple QMDC workspaces in one folder
• QMDC Explorer — tree view with workspaces, namespaces, and objects
• Namespaces (__Namespace) for organizing objects
• Cross-file references with namespace qualifiers
• SQL Queries — execute SQL queries against workspace objects

Requirements

The extension requires qmdc CLI tool (QMDC Language Server).

Install qmdc

# From the qmdc repository
cd qmdc-rs
cargo build --release
# Binary at: target/release/qmdc

Or install globally:

cd qmdc-rs
cargo install --path .

Set custom path in settings if needed:

{
  "qmdc.server.path": "/path/to/qmdc"
}

Commands

QMDC Explorer

The QMDC Explorer sidebar shows a hierarchical view of your workspace:

• 📁 Workspaces — all QMDC workspaces in the project (supports multi-root)
  • 📂 Namespaces — logical groupings of objects
    • 📄 Objects — all QMD.md objects with their kinds

Click on any item to navigate to its definition. The explorer automatically updates when files change.

Extension Settings

Better Readability: Dim Metadata

By default, QMDC metadata ([[id]], [[id: Kind]]) is dimmed for better readability. To customize colors, add this to your settings.json:

{
  "editor.tokenColorCustomizations": {
    "textMateRules": [
      {
        "scope": [
          "punctuation.definition.tag.begin.qmd.md",
          "punctuation.definition.tag.end.qmd.md"
        ],
        "settings": {
          "foreground": "#6a737d55"
        }
      },
      {
        "scope": [
          "entity.name.tag.qmd.md",
          "entity.name.type.qmd.md",
          "keyword.operator.auto-id.qmd.md"
        ],
        "settings": {
          "foreground": "#6a737d88",
          "fontStyle": "italic"
        }
      }
    ]
  }
}

This makes [[id]] and [[id: Kind]] appear gray and italic, so they don't distract from the main content.

SQL Queries

You can execute SQL queries against your workspace objects using the QMDC: Run SQL Query command:

-- Find all services
SELECT __id, __label, __file FROM objects WHERE __kind = 'Service'

-- Count objects by kind
SELECT __kind, COUNT(*) as count FROM objects GROUP BY __kind

-- Find all references to a specific object
SELECT source_id, target_id, field_name FROM edges WHERE target_id = 'auth'

Available tables:

• objects — all objects with columns: __id, __kind, __label, __file, __line, data (JSON)
• edges — all references with columns: source_id, target_id, field_name

The extension automatically loads all workspaces recursively and maintains an in-memory SQLite database.

QMD.md Syntax Quick Reference

Object Definition

# My Project [[my_project:__Workspace]]
- description: Project root

## Users Table [[users:Table]]
- name: users
- columns: [id, name, email]

## Orders [[orders]]
- user_ref: [[#users]]

Header Variations

# Title [[id]]           # ID at end
# [[id]] Title           # ID at start  
# Title [[:Kind]]        # Auto-generated ID with Kind
# Title [[id:Kind]]      # Explicit ID and Kind

References

- local: [[#users]]                      # Local reference
- with_kind: [[#Table:users]]            # Kind-qualified
- namespace: [[#storage:users]]          # Cross-namespace
- workspace: [[#proj:storage:users]]     # Cross-workspace

Field Types

- name: API Service       # String
- port: 8080              # Number
- enabled: true           # Boolean
- tags: [api, backend]    # Array
- ref: [[#auth]]          # Reference

Multiline Text (YAML pipe syntax)

## Config [[config]]
- description: |
    This is a multiline
    description field.

Workspace Structure

my-project/
├── readme.qmd.md              # [[my_project:__Workspace]]
├── users.qmd.md
├── storage/
│   ├── readme.qmd.md          # [[storage:__Namespace]]
│   └── tables.qmd.md
└── api/
    ├── readme.qmd.md          # [[api:__Namespace]]
    └── endpoints.qmd.md

Installation

From VSIX (Local Install)

cd qmdc-vscode
npm install
npm run build          # Creates qmdc-vscode-X.Y.Z.vsix

Then in VS Code: Cmd+Shift+P → "Extensions: Install from VSIX..." → select the .vsix file.

Or via command line:

code --install-extension qmdc-vscode-0.2.0.vsix

Building qmdc (Language Server)

The extension requires the QMDC language server (qmdc):

cd qmdc-rs
cargo build --release
# Binary at: target/release/qmdc

Development

cd qmdc-vscode
npm install
npm run compile

Press F5 to launch Extension Development Host.

Prerequisites for Cross-Platform Build

To build for all platforms (Mac, Linux, Windows), install these tools:

# 1. Zig (for cross-compilation)
brew install zig

# 2. cargo-zigbuild (Rust cross-compiler using Zig)
cargo install cargo-zigbuild

# 3. MinGW (for Windows x64)
brew install mingw-w64

# 4. Rust targets
rustup target add \
  x86_64-apple-darwin \
  aarch64-apple-darwin \
  x86_64-unknown-linux-gnu \
  aarch64-unknown-linux-gnu \
  x86_64-pc-windows-gnu \
  aarch64-pc-windows-gnullvm

⚠️ Make sure you're using rustup Rust, not Homebrew Rust. Check with which cargo — should be ~/.cargo/bin/cargo.

Available Scripts

Platform-Specific Builds

Release Workflow

# 1. Bump version
npm run bump-version patch   # 0.2.0 -> 0.2.1

# 2. Build for all platforms
npm run package:all

# 3. Test locally (Mac)
code --install-extension qmdc-vscode-darwin-arm64-0.2.1.vsix

# 4. Publish all to marketplace
npm run publish:all

Quick Local Build (Mac only)

npm run build
code --install-extension qmdc-vscode-0.2.1.vsix

Links

• QMD.md Syntax
• QMDC Workspace Specification

License

AGPL-3.0-or-later © mikilabs