markhook

An engine for the Markhook Archive format

What is Markhook

Markhook is a Markdown engine with plugin support that uses Markhook Archives (.mdh), archives containing the markdown file, metadata, plugins, and your assets (like images)

Installation

Install markhook with npm

  npm i markhook

Usage/Examples

import { initMdh, editContent, addPlugin, makeKeywordMap, runMarkdown } from "markhook";

async function example() {
  const mdh = await initMdh();

  await editContent(mdh, `
# Hello World

Here's an image: {{{ asset image.png }}}

And a keyword call: #greet John;
  `);

  await addPlugin(mdh, "greet.js", `//!kw greet
async function greet(name) {
  return \`Hello, \${name}!\`;
}`);

  const keywordMap = await makeKeywordMap(mdh);

  const result = await runMarkdown(mdh, keywordMap);
  console.log(result);
}

example();

API Reference

initMdh(): Promise<JSZip>

Creates a new empty Markhook Archive (.mdh) with base folders and a default manifest.

• Returns: A Promise resolving to a JSZip instance representing the new archive.

---

editContent(mdh: JSZip, newContent: string): Promise<JSZip>

Replaces the markdown content (content.md) inside the archive.

• Parameters:

  • mdh: The Markhook Archive (JSZip instance).
  • newContent: The new markdown string.

• Returns: The updated JSZip archive.

• Throws: Error if mdh is missing.

---

addPlugin(mdh: JSZip, pluginPath: string, pluginContent: string): Promise<JSZip>

Adds or updates a plugin JS file under the plugins/ folder.

• Parameters:

  • mdh: The Markhook Archive.
  • pluginPath: Path or filename for the plugin (auto-prefixed with plugins/ if missing).
  • pluginContent: The JS source code of the plugin.

• Returns: The updated JSZip archive.

• Throws: Error if mdh is missing.

---

editMetadata(mdh: JSZip, newMeta: object): Promise<JSZip>

Merges new metadata into the archive’s manifest.json.

• Parameters:

  • mdh: The Markhook Archive.
  • newMeta: Object with new metadata fields to merge.

• Returns: The updated JSZip archive.

• Throws: Error if JSON parsing fails or if mdh is missing.

---

extractMdh(mdhBytes: Uint8Array | ArrayBuffer): Promise<JSZip>

Loads a Markhook Archive from raw bytes.

• Parameters:

  • mdhBytes: The binary data of a .mdh archive.

• Returns: A Promise resolving to a JSZip instance of the loaded archive.

---

readMarkdown(mdh: JSZip): Promise<string>

Reads the markdown content (content.md) with all {{{ asset filename }}} placeholders replaced by base64 data URIs.

• Parameters:

  • mdh: The Markhook Archive.

• Returns: Processed markdown string.

• Throws: Error if content file or assets are missing.

---

readMarkdownRaw(mdh: JSZip): Promise<string>

Reads the markdown content (content.md).

• Parameters:

  • mdh: The Markhook Archive.

• Returns: Markdown string.

• Throws: Error if content file or assets are missing.

---

readMeta(mdh: JSZip): Promise<object>

Reads and parses the manifest.json metadata.

• Parameters:

  • mdh: The Markhook Archive.

• Returns: Metadata object.

• Throws: Error if manifest file is missing or JSON parsing fails.

---

makeKeywordMap(mdh: JSZip): Promise<Record<string, {plugin: string, lineNumber: number}>>

Scans all plugin files in plugins/ folder and creates a map of keywords to their plugin file and line number.

• Parameters:

  • mdh: The Markhook Archive.

• Returns: Keyword map object.

---

runMarkdown(mdh: JSZip, keywordMap: object): Promise<string>

Processes markdown content by replacing keyword calls (#keyword[arg];) with plugin function outputs.

• Parameters:

  • mdh: The Markhook Archive.
  • keywordMap: The map generated by makeKeywordMap.

• Returns: Markdown string with keywords replaced by plugin output.

---

runKeywordFunction(mdh: JSZip, keywordEntry: {plugin: string, lineNumber: number}, context?: string): Promise<string>

Runs the function corresponding to a keyword inside its plugin file.

• Parameters:

  • mdh: The Markhook Archive.
  • keywordEntry: Object containing plugin file path and line number of the keyword.
  • context: Optional argument string passed to the function.

• Returns: The string output from the plugin function.

• Throws: Error if plugin file or function is missing or evaluation fails.

addAsset(mdh: JSZip, assetPath: string, assetContent: Uint8Array | string): Promise<JSZip>

Adds or updates a file in the assets/ folder of the Markhook Archive.

• Parameters:

  • mdh: The Markhook Archive (JSZip instance).
  • assetPath: Relative path or filename for the asset (auto-prefixed with assets/ if missing).
  • assetContent: The file content as a string or binary data (e.g., Uint8Array).

• Returns: The updated JSZip archive.

• Throws: Error if mdh is missing.

removeAsset(mdh: JSZip, assetPath: string): Promise<JSZip>

Removes a file from the assets/ folder inside the Markhook Archive.

• Parameters:

  • mdh: The Markhook Archive (JSZip instance).
  • assetPath: Relative path or filename of the asset to remove (auto-prefixed with assets/ if missing).

• Returns: The updated JSZip archive.

• Throws: Error if mdh is missing or asset doesn’t exist.

Custom Markdown Elements

{{{ asset [file] }}}

Embeds an asset from the Markhook Archive (.mdh) as a dataurl

• Parameters:
  • file: File path in the Markhook Archive
• Replaces with: DataURL of the asset

Example:

![Markdown]({{{ asset markdown.png }}})

#[keyword] [arguments];

Custom keywords managed by plugins

• Parameters:
  • keyword: a keyword managed by a plugin
  • arguments: additional information passed over to the plugin
• Replaces with: a string returned by the plugin

Example

#calculate 2+2;

Custom Plugin Elements

//!kw [keyword]

Registers a keyword

• Parameters:
  • keyword: The keyword to register

WARNING: For the keyword to work you'll have to use the function functionName() syntax or else it will error out thinking theres no function to run

Note: Async is supported

Example

//!kw calculate
function calculate(expression) {
    expression = expression.split("+")
    return expression[0] + expression[1]
}

Authors

• @psenakdotsk

Contributing

Contributions are always welcome!

See contributing.md for ways to get started.