SDK

JavaScript SDK

TypeScript-first client for mdfy.cc. Works in Node.js, Deno, Bun, and browsers. Zero dependencies.

Installation

bash
npm install @mdcore/api

Also available: yarn add @mdcore/api or pnpm add @mdcore/api

Quick Start

typescript
import { publish } from "@mdcore/api";

const result = await publish("# Hello World");
console.log(result.url);  // https://mdfy.cc/d/abc123

MdfyClient

The MdfyClient class provides a stateful client with user identity and base URL configuration.

typescript
import { MdfyClient } from "@mdcore/api";

const client = new MdfyClient({
  baseUrl: "https://mdfy.cc",  // default
  userId: "user-uuid",          // optional
  email: "user@example.com",    // optional
});

Constructor Options

baseUrlstringAPI base URL. Default: https://mdfy.cc
userIdstringUser UUID for ownership-based operations.
emailstringUser email for identification.

Methods

publish(markdown, options?)PublishResultCreate a new document.
pull(id, options?)DocumentRead a document by ID.
update(id, markdown, options)voidUpdate document content.
delete(id, editToken)voidSoft-delete a document.
list()Document[]List user's documents.
versions(id)Version[]Get version history.
upload(file)stringUpload an image, returns URL.
setPublished(id, editToken)voidSet document to published.
setDraft(id, editToken)voidSet document to draft.

client.publish()

typescript
const result = await client.publish("# Hello World", {
  title: "My Document",
  isDraft: false,
  password: "optional-secret",
  expiresIn: "7d",
  editMode: "token",
  folderId: "folder-uuid",
});

console.log(result.id);        // "abc123"
console.log(result.editToken); // "tok_aBcDeFgH..."
console.log(result.url);       // "https://mdfy.cc/d/abc123"

client.pull()

typescript
const doc = await client.pull("abc123");

console.log(doc.markdown);    // "# Hello World"
console.log(doc.title);       // "My Document"
console.log(doc.view_count);  // 42
console.log(doc.is_draft);    // false

// With password
const doc2 = await client.pull("abc123", {
  password: "secret",
});

client.update()

typescript
await client.update("abc123", "# Updated Content", {
  editToken: "tok_aBcDeFgH",
  title: "New Title",
  changeSummary: "Fixed typos in section 2",
});

client.delete()

typescript
await client.delete("abc123", "tok_aBcDeFgH");
// Document is soft-deleted (can be restored by owner)

client.list()

typescript
const docs = await client.list();

docs.forEach(doc => {
  console.log(`${doc.id}: ${doc.title} (${doc.is_draft ? "draft" : "published"})`);
});

client.versions()

typescript
const versions = await client.versions("abc123");

versions.forEach(v => {
  console.log(`${v.version}: ${v.changeSummary} (${v.created_at})`);
});

client.upload()

typescript
// Browser
const input = document.querySelector("input[type=file]");
const file = input.files[0];
const imageUrl = await client.upload(file);

// Node.js
import { readFileSync } from "fs";
const buffer = readFileSync("screenshot.png");
const blob = new Blob([buffer], { type: "image/png" });
const imageUrl = await client.upload(blob);

Standalone Functions

For quick one-off operations without creating a client instance.

typescript
import {
  publish,
  pull,
  update,
  deleteDocument,
  upload,
} from "@mdcore/api";

// Publish
const { id, editToken, url } = await publish("# Hello World");

// Read
const doc = await pull(id);

// Update
await update(id, "# Updated content", editToken);

// Delete
await deleteDocument(id, editToken);

// Upload image
const imageUrl = await upload(file);

npm Packages

Independent packages. Each can be installed and used separately. No cross-dependencies.

@mdcore/api

HTTP client for mdfy.cc. Publish, read, update, delete documents. Zero dependencies (native fetch).

npm install @mdcore/api
@mdcore/engine

WASM Markdown renderer (Rust/comrak). GFM, KaTeX math, Mermaid diagrams, syntax highlighting.

npm install @mdcore/engine
@mdcore/styles

CSS-only package. Dark/light themes, rendered document styles, print/PDF styles. No JavaScript.

npm install @mdcore/styles
@mdcore/ai

AI provider integrations. Gemini, OpenAI, Anthropic. Text-to-Markdown, ASCII rendering.

npm install @mdcore/ai
mdfy-mcp

Local stdio MCP (6 core tools). For all 25 tools use the hosted MCP at https://mdfy.cc/api/mcp.

npx mdfy-mcp

@mdcore/engine Example

typescript
import { mdcore } from "@mdcore/engine";
import { postProcessHtml } from "@mdcore/engine";

await mdcore.init();

const { html, flavor } = mdcore.render("# Hello **World**");
const finalHtml = await postProcessHtml(html);

@mdcore/styles Example

css
/* Import all styles */
@import "@mdcore/styles";

/* Or import individual modules */
@import "@mdcore/styles/theme-dark.css";
@import "@mdcore/styles/rendered.css";
@import "@mdcore/styles/code.css";
@import "@mdcore/styles/print.css";

@mdcore/ai Example

typescript
import { mdfyText, callAI, isAiConversation } from "@mdcore/ai";

// Convert raw text to structured Markdown
const markdown = await mdfyText("some rough text here...");

// Detect AI conversation format
if (isAiConversation(text)) {
  const { turns } = parseConversation(text);
  const formatted = formatConversation(turns);
}