npm package: @rendermark/core
Description: > Markdown rendering engine — convert Markdown to beautiful HTML documents, PDFs, DOCX, slides, and more.
Latest version: 0.1.3

# @rendermark/core

> Markdown rendering engine — convert Markdown to beautiful HTML documents, PDFs, DOCX, slides, and more.

<!-- badges placeholder -->

## Installation

```bash
npm install @rendermark/core
```

## Quick Start

```typescript
import { renderMarkdownToHtml } from "@rendermark/core";

const html = await renderMarkdownToHtml({
  title: "My Document",
  markdown: "# Hello World\n\nThis is **RenderMark**.",
  theme: "default",
  showToc: true,
});

// html is a complete, styled HTML document ready to serve or save
```

## API Reference

### Rendering

#### `renderMarkdownToHtml(options: RenderOptions): Promise<string>`

Render markdown to a full, styled HTML document with CSS, fonts, branding, and table of contents.

```typescript
const html = await renderMarkdownToHtml({
  title: "Report",
  markdown: content,
  showToc: true,
  theme: "serif",
  template: "report",
  github: { owner: "user", repo: "repo", branch: "main", path: "docs/file.md" },
  sanitize: true, // Strip XSS for public-facing pages
});
```

#### `markdownToHtmlFragment(markdown: string): Promise<string>`

Render markdown to an HTML fragment (no document wrapper). Useful for inline rendering or blog posts.

#### `generateGoogleDocsHtml(title: string, markdown: string): Promise<string>`

Generate simplified HTML optimized for Google Docs import, with inline styles and GDocs-compatible formatting.

#### `markdownToDocx(options): Promise<Buffer>`

Convert markdown to a DOCX (Word) file buffer.

```typescript
import { markdownToDocx } from "@rendermark/core";

const buf = await markdownToDocx({
  markdown: content,
  title: "My Document",
  github: { owner: "user", repo: "repo", path: "doc.md" },
});
```

#### `renderToImage(options: RenderToImageOptions): Promise<void>`

Render markdown to a PNG or JPEG screenshot via a callback. Requires a Puppeteer-compatible environment.

#### `renderDiff(options: DiffOptions): string`

Generate a visual diff between two markdown versions as a standalone HTML document.

```typescript
import { renderDiff } from "@rendermark/core";

const html = renderDiff({
  before: oldMarkdown,
  after: newMarkdown,
  mode: "inline", // or "side-by-side"
  title: "Document Changes",
});
```

#### `markdownToSlides(options: SlideOptions): Promise<string>`

Convert markdown into a presentation slide deck. Slides split on `---` (horizontal rules) or `## ` headings.

```typescript
import { markdownToSlides } from "@rendermark/core";

const html = await markdownToSlides({
  markdown: content,
  title: "My Presentation",
  theme: "dark",
  splitOn: "hr", // or "h2"
});
```

### Frontmatter

#### `parseFrontmatter(markdown: string): { data: FrontmatterData; content: string }`

Parse YAML frontmatter from a markdown string. Returns the parsed data and the content without frontmatter.

### Themes

#### `getTheme(name: string): string`

Get the CSS override for a named theme. Returns an empty string for unknown themes.

#### `listThemes(): string[]`

List all available built-in theme names.

#### `isBuiltinTheme(name: string): boolean`

Check if a theme name is a built-in theme.

### Templates

#### `applyTemplate(name: string, options): string`

Apply a named template to markdown content. Templates wrap the markdown with structural elements.

#### `listTemplates(): string[]`

List all available built-in template names.

#### `getTemplateDefaultTheme(name: string): string | undefined`

Get the default theme associated with a template.

### Utilities

#### `resolveGitHubRelativePaths(markdown: string, context?: GitHubContext): string`

Resolve relative image/link paths in markdown to absolute GitHub raw URLs.

#### `extractHeadings(markdown: string): TocItem[]`

Extract headings (h1–h3) from raw markdown for table of contents generation.

#### `generateTocHtml(headings: TocItem[]): string`

Generate an HTML table of contents from extracted headings.

#### `generateSlug(text: string): string`

Generate a URL-safe slug from heading text, matching GitHub/rehype-slug conventions.

#### `escapeHtml(str: string): string`

HTML-escape a string (`&`, `<`, `>`, `"`, `'`).

### Unified Pipelines

#### `createProcessor()`

Create the full unified processor with all remark/rehype plugins (GFM, math, syntax highlighting, mermaid, callouts, etc.).

#### `createBasicProcessor()`

Create a basic processor without syntax highlighting or advanced plugins. Used for Google Docs output.

#### `createSanitizedProcessor()`

Create a sanitized processor that strips XSS vectors while preserving classes/ids for styling.

### Plugins

These remark/rehype plugins are used internally and exported for advanced usage:

- **`remarkMermaid`** — Transform `mermaid` code blocks into client-side rendered diagrams
- **`remarkCallouts`** — Obsidian-style `> [!note]` callout boxes
- **`remarkWikiLinks`** — `[[slug]]` and `[[slug|text]]` wiki-style links
- **`remarkComments`** — Strip `%%hidden%%` Obsidian-style comments
- **`rehypeSourceLines`** — Add `data-source-line` attributes for scroll sync

## RenderOptions

```typescript
interface RenderOptions {
  title: string;
  markdown: string;
  showToc?: boolean;        // Include table of contents (default: true)
  github?: GitHubContext;   // GitHub context for resolving relative paths
  docId?: string;           // Document ID for branding links
  theme?: string;           // Theme name
  template?: string;        // Template name
  sanitize?: boolean;       // Use sanitized processor for public pages
}
```

## Themes

| Theme     | Description                           |
|-----------|---------------------------------------|
| `default` | Clean, modern with Geist font         |
| `dark`    | Dark background, light text           |
| `serif`   | Traditional serif typography          |
| `minimal` | Stripped-down, distraction-free       |

Themes can be set via the `theme` option or `theme` frontmatter field.

## Templates

| Template        | Description                        | Default Theme |
|-----------------|------------------------------------|---------------|
| `report`        | Formal report with cover page      | —             |
| `meeting-notes` | Meeting notes with attendees       | —             |
| `memo`          | Internal memo format               | —             |
| `letter`        | Formal letter layout               | serif         |
| `slides`        | Presentation slide deck            | —             |
| `changelog`     | Version changelog format           | —             |

Templates can be set via the `template` option or `template` frontmatter field.

## Frontmatter

RenderMark supports YAML frontmatter at the top of markdown files:

```yaml
---
title: My Document
theme: serif
template: report
toc: true
author: Jane Doe
date: 2025-01-15
custom_field: any value
---
```

### Supported Fields

| Field      | Type    | Description                              |
|------------|---------|------------------------------------------|
| `title`    | string  | Document title                           |
| `theme`    | string  | Theme name (default, dark, serif, minimal)|
| `template` | string  | Template name                            |
| `toc`      | boolean | Show table of contents                   |
| `author`   | string  | Author name (used by templates)          |
| `date`     | string  | Date (used by templates)                 |

Additional custom fields are passed through and available to templates.

## License

MIT