# HTML and Markdown conversion

Choose browser or server conversion APIs and understand Schema, format rules and data loss.

HTML and Markdown are input/output representations. Conversion does not install extensions or produce Classic's paginated interface. Choose your product's Schema, then supply rules for the content you need to exchange.

## Browser: read the current editor

An Editor exposes `getJSON()`, `getHTML()` and `getMarkdown()`. HTML uses node/mark `renderHTML()` rules; JSON represents canonical content; Markdown uses installed extension rules. See [reading and replacing content](/en/guide/content) for strict JSON restoration.

For HTML conversion without an Editor, use `generateJSON(html, extensions)` and `generateHTML(json, extensions)` from `@quirekit/html`. The browser entry requires a DOM; do not execute it directly in a Node server.

## Server: select the separate entry

```sh [Install HTML utilities]
pnpm add @quirekit/html @quirekit/core @quirekit/starter-kit
```

Node uses `@quirekit/html/server`. Utilities receive resolved extensions: expand composites such as StarterKit through `resolveExtensions()` first. This function mounts no View, needs no client Editor and shares no DOM document between requests:

### core/formats/server.ts

```ts
import { generateHTML, generateJSON } from "@quirekit/html/server";
import { resolveExtensions } from "@quirekit/core";
import { StarterKit } from "@quirekit/starter-kit";

/**
 * Converts supported semantic HTML without mounting an editor or sharing a browser document.
 * @param html - Application-authorized HTML; this function is not a sanitizer.
 * @returns Normalized canonical JSON and its semantic HTML representation.
 */
export function normalizeArticleHTML(html: string) {
  const extensions = resolveExtensions([StarterKit.configure({})]);
  const document = generateJSON(html, extensions);
  return { document, html: generateHTML(document, extensions) };
}

```

Client and server need compatible extensions and configuration. A server that understands only paragraphs cannot restore client business cards. `generateJSON()` normalizes HTML against the Schema and may discard unknown tags, attributes or styles. A successful result does not establish lossless HTML preservation.

Parsing and security filtering are separate. The converter is not a general sanitizer. Apply your content policy to untrusted HTML and explicitly decide which links, images and external resources to permit.

## Markdown: declare the input type

Strings default to HTML. For Markdown, creation options or `setContent()` options must include `contentType: 'markdown'`.

### core/formats/markdown.ts

```ts
import { Editor } from "@quirekit/core";
import { StarterKit } from "@quirekit/starter-kit";

/**
 * Converts supported Markdown in a headless editor, releasing its session afterwards.
 * @param markdown - Source using the installed extensions' Markdown syntax.
 * @returns Canonical JSON and normalized Markdown, not the original source spelling.
 */
export function normalizeArticleMarkdown(markdown: string) {
  const editor = new Editor({ extensions: [StarterKit.configure({})], content: markdown, contentType: "markdown" });
  try { return { document: editor.getJSON(), markdown: editor.getMarkdown() }; }
  finally { editor.destroy(); }
}

```

The recipe handles content supported by StarterKit and emits normalized Markdown. Original whitespace, delimiter spelling and unsupported syntax are not guaranteed to survive. Restore JSON with the same model for continued editing; reparsing Markdown is not lossless JSON storage.

A custom Node/Mark's HTML rules do not become Markdown rules. Custom syntax needs Markdown token parsing and rendering contracts too. Until implemented, explicitly reject, downgrade or preserve the original separately. A [typing rule](/en/guide/rules) for `==text==` does not teach that syntax to the Markdown parser.

## Choose a storage format

| Goal | Approach |
| --- | --- |
| Restore product content precisely | Versioned canonical JSON plus media assets |
| Publish or exchange semantic HTML | HTML rules, tested with links, images and custom nodes |
| Interoperate with Markdown tools | Defined supported syntax and loss policy, tested both ways |
| Preserve Word pages, styles and relationships | Word model and DOCX service with conversion diagnostics |

Round-trip headings, mixed marks, lists, links and a business node. Compare canonical structure and meaningful attributes; `textContent` alone misses structure and formatting loss.