Tidemark

[!IMPORTANT] Obsidian plugin for variable substitution in markdown via YAML frontmatter. Define variables in YAML frontmatter, reference them with {{variable}} syntax anywhere in your document, then copy or replace with a single command. Supports nested properties, arrays, default values, and live syntax highlighting.

A tidemark is the line water leaves behind. Felt fitting for a plugin that quietly stamps frontmatter values throughout a note.

---

§1 / Premise

Tidemark is a variable-substitution plugin for Obsidian. Author with placeholders — {{target}}, {{port:443}}, {{server.ip}} — and let frontmatter drive the values. Copy a line, a selection, or the whole document with values substituted; or permanently replace in-place. Variables are color-coded in the editor so you see at a glance which ones are defined, which fall back to defaults, and which are missing.

The core engine parses YAML frontmatter, resolves nested dot-notation and joined arrays, and emits CodeMirror decorations for real-time highlighting.

---

§2 / Specs

KEY	VALUE
SYNTAX	{{variable}} · {{variable:default}} · {{nested.path}} · array join
COMMANDS	9 palette commands · copy/replace by line · selection · document · rename
TYPES	Nested properties · arrays (auto-joined) · defaults · scalars
HIGHLIGHTS	Green = set · Orange = default fallback · Red = missing
CONFIG	Custom delimiters · custom missing text · case-insensitive option · per-status colors
TARGETS	Desktop · iOS · Android (mobile context-menu limited)
STACK	TypeScript · esbuild · CodeMirror decorations · MIT

Architecture in §5 below.

---

§3 / Quickstart

Install

Community Plugins (recommended):

1. Obsidian Settings → Community Plugins
2. Browse → search "Tidemark"
3. Install · Enable

Manual:

# Download main.js, manifest.json, styles.css from latest release
# Copy to .obsidian/plugins/tidemark/

Build from source

Prerequisites: Node.js 18+.

git clone https://github.com/Real-Fruit-Snacks/Tidemark.git
cd Tidemark
npm install
npm run build

cp main.js manifest.json styles.css /path/to/vault/.obsidian/plugins/tidemark/

Verify by enabling the plugin, creating a note with frontmatter variables, and running Tidemark: Copy current line (replaced) from the command palette.

---

§4 / Reference

SYNTAX

  {{variable}}                Reference frontmatter value
  {{variable:default}}        Use default if not defined in frontmatter
  {{nested.path}}             Dot notation for nested YAML structures
  Array values are joined automatically with the configured separator

EXAMPLE

  ---
  project: My Project
  author: {{author:Anonymous}}
  server:
    host: example.com
    port: 8080
  tags:
    - obsidian
    - markdown
    - variables
  ---

  # {{project}}

  Author: {{author}}
  Endpoint: https://{{server.host}}:{{server.port}}
  Topics: {{tags}}
    → Topics: obsidian, markdown, variables

PALETTE COMMANDS  (Ctrl/Cmd+P → "Tidemark")

  Copy current line (replaced)         Line with variables filled
  Copy selection (replaced)            Selection with variables filled
  Copy document (replaced)             Entire note with variables filled
  Replace in selection                 Permanently replace in selection
  Replace all in document              Replace all variables in body
  Replace in document and filename     Replace in body and rename file
  Rename file (replace variables)      Rename file with variables filled
  List all variables                   View/edit all variables by status
  Set variable value                   Set value at cursor position

CONFIGURATION

  Delimiters
    openDelimiter        {{                (default)
    closeDelimiter       }}                (default)
    defaultSeparator     :                 (default)

  Behavior
    missingValueText     [MISSING]
    supportNested        true
    caseInsensitive      false
    arrayJoinSeparator   ", "
    preserveOnMissing    false
    notificationLevel    all | errors | none

  Visual
    highlightVariables   true
    Custom hex per status (set / default / missing)

---

§5 / Architecture

src/
  main.ts                    Plugin entry · command registration
  variableReplacer.ts        Core replacement engine
  frontmatterParser.ts       YAML frontmatter extraction
  decorationProvider.ts      CodeMirror syntax highlighting
  types.ts                   TypeScript interfaces
  commands/                  Command handlers
  utils/                     String helpers · YAML utilities

manifest.json                Obsidian plugin manifest
esbuild.config.mjs           Build configuration
docs/                        GitHub Pages site

Layer	Implementation
Replace	variableReplacer.ts resolves {{var}} against frontmatter
Parse	frontmatterParser.ts extracts YAML · supports nested + arrays
Highlight	CodeMirror decorations · live status (set/default/missing)
Commands	One handler per palette command · obey replace vs. copy rules
Build	esbuild · single main.js · ships with manifest.json + styles.css

Key patterns: No external mutable state — variable resolution is a pure function of (text, frontmatter, settings). Highlight status reflects the same resolver, so what you see in the editor is what you get on copy or replace.

---

§6 / Platform support

Capability	Desktop	iOS	Android
Variable Replacement	Full	Full	Full
Copy to Clipboard	Full	Full	Full
Syntax Highlighting	Full	Full	Full
Nested Properties	Full	Full	Full
Context Menu	Full	Limited	Limited
File Rename	Full	Full	Full

---

License: MIT · Part of Real-Fruit-Snacks — building offensive security tools, one wave at a time.