md-fusion

Convert notes between HTML/JSON and Markdown with YAML Frontmatter.

A lightweight Node.js library and CLI tool to bridge the gap between structured note data (JSON) and static Markdown files. It handles YAML Frontmatter bidirectionally, making it ideal for migrating content to Obsidian, Notion, or Jekyll / Hugo sites.

Installation

# Global install (CLI)
npm install -g md-fusion

# Project dependency
npm install md-fusion

Usage

CLI

# Convert a JSON notes file to individual Markdown files
md-fusion to-md notes.json -o ./my-vault

# Parse a single Markdown file to JSON
md-fusion from-md ./my-vault/daily-note.md

API

import { toMarkdown, fromMarkdown } from 'md-fusion';

const myNote = {
  title: "Project Idea",
  content: "<h1>Big Plans</h1><p>Do the thing.</p>",
  tags: ["ideas", "work"],
  created: "2023-10-27T10:00:00Z"
};

// Convert a Note object → Markdown string with YAML Frontmatter
const md = toMarkdown(myNote);
console.log(md);
/*
---
title: Project Idea
tags:
  - ideas
  - work
created: 2023-10-27T10:00:00Z
---
# Big Plans

Do the thing.
*/

// Parse Markdown → Note object
const noteObj = fromMarkdown(md);
console.log(noteObj.title);   // "Project Idea"
console.log(noteObj.created); // "2023-10-27T10:00:00Z"  (or undefined if absent)

Handling Missing Dates

fromMarkdown() returns undefined for created / updated when the Frontmatter does not include them. Apply your own fallback:

const note = fromMarkdown(mdContent);
const fileDate = new Date(file.lastModified).toISOString();

note.created = note.created ?? fileDate;
note.updated = note.updated ?? fileDate;

Type Definition

interface Note {
  title: string;
  content: string;   // HTML
  tags: string[];
  created?: string;  // ISO 8601, undefined when absent from Frontmatter
  updated?: string;  // ISO 8601, undefined when absent from Frontmatter
  slug?: string;
  status?: string;
  [key: string]: any; // Extra YAML keys are preserved round-trip
}

License

MIT

{ github.com/mgks }