MDZip logo

@mdzip/editor-ng

npm license

Angular component wrapper for the MDZip workspace editor.

@mdzip/editor-ng provides a standalone MdzipWorkspaceComponent that embeds the full MDZip workspace UI — document preview, editor, package navigator, and asset manager — as a native Angular component.

Install

npm install @mdzip/editor @mdzip/editor-ng

Peer dependencies: @angular/common and @angular/core >=20.

Basic Usage

import { MdzipWorkspaceComponent } from '@mdzip/editor-ng';

@Component({
  imports: [MdzipWorkspaceComponent],
  template: `
    <mdzip-workspace
      [bytes]="fileBytes"
      fileName="document.mdz"
      mode="read-only"
      controls="viewer"
      (failed)="onError($event)"
    />
  `,
  styles: [':host { display: block; height: 600px; }']
})
export class AppComponent {
  fileBytes: Uint8Array | null = null;
}

The host element must have an explicit height. The component expands to fill it.

Archive Diff

import { MdzipDiffComponent } from '@mdzip/editor-ng';

@Component({
  imports: [MdzipDiffComponent],
  template: `
    <mdzip-diff
      [before]="{ bytes: baseBytes, label: 'Git base' }"
      [after]="{ bytes: workingBytes, label: 'Working tree' }"
      [toolbarActions]="diffActions"
      initialPath="index.md"
    />
  `,
  styles: [':host { display:block; height:600px; }']
})
export class DiffComponent {}

MdzipDiffComponent is read-only. It emits selectionChanged and failed, and exposes openPath, openPreviousChange, openNextChange, setShowUnchanged, setNavigationVisible, and setToolbarActions. The built-in toolbar adds Previous/Next change buttons and a Show-unchanged toggle; bind a controls input ({ navigation?, changeTraversal?, showUnchanged? }) to opt any of them out.

Editor Mode

<mdzip-workspace
  [bytes]="fileBytes"
  fileName="document.mdz"
  mode="editable"
  controls="standalone-editor"
  (saved)="onSaved($event)"
  (changed)="onChanged($event)"
/>

Inputs

Input Type Default Description
bytes Uint8Array | null null Raw archive bytes to open
workspace MdzWorkspace | null null Pre-built workspace object
fileName string 'document.mdz' Filename used for format detection and Save dialogs
mode MdzipWorkspaceMode 'read-only' 'read-only' or 'editable'
sourceFormat MdzipSourceFormat — Override format detection: 'mdz' or 'markdown'
controls MdzipControlPreset | MdzipControlPolicy 'viewer' 'preview', 'viewer', 'standalone-editor', 'hosted-editor', or a policy object
toolbarDensity 'comfortable' | 'compact' | 'dense' 'comfortable' Semantic sizing preset for built-in toolbar controls
contentDensity 'comfortable' | 'compact' 'comfortable' Semantic padding preset for editor and preview content
imageHydrationAnimation 'auto' | 'initial' | 'off' 'auto' Control preview image reveal animation: every render, first render per document path, or never
initialLayout MdzipWorkspaceLayout — Starting layout: 'preview', 'editor', 'split'
initialColorScheme MdzipColorSchemePreference 'system' 'light', 'dark' or 'system' (follows the OS setting live)
systemColorScheme MdzipSystemColorScheme — Makes the color scheme menu's System choice follow the host's theme instead of the OS setting, with its own label and icon, e.g. { colorScheme: 'dark', label: 'VS Code theme', icon: '<svg…>' }; changes apply live
previewMaxWidth MdzipPreviewMaxWidth 'default' Preview reading-column width: 'narrow', 'default', 'wide', 'full' or a pixel number; the user can change it from the toolbar's page-width menu
navigationMode MdzipNavigationMode 'editor' Package navigation mode
navigationButtonActive boolean true Whether the navigation button is shown
inlineSvgLinks boolean true Shows archive SVGs that contain links inline, so the links can be clicked (draw.io .drawio.svg diagrams, for example); other SVGs stay images. Read when the view is created
hostFileActions readonly MdzipFileAction[] — The host's own items in the file tree's right-click menu on files ({ id, label, appliesTo?, run }), e.g. "Open in Another Editor". Also shown as buttons on the card that stands in for a .drawio image. Read when the view is created
markdownRenderer MdzipMarkdownRenderer — Custom markdown renderer (keep the reference stable)
markdownExtensions readonly MdzipMarkdownRenderExtension[] [] Markdown pipeline extensions, diffed by name — new array identities with the same names are safe
entryRenderers readonly MdzipEntryRenderer[] [] Entry renderers claiming the content area for matching entries, diffed by id — new array identities with the same ids are safe
frontMatter MdzipFrontMatterOptions {} Front matter panel config (enabled, display, collapsible, label) — always registered, diffed by deep equality; new object identities with equal contents are safe
externalLinks MdzipExternalLinkPolicy — External-link policy, e.g. { target: '_blank' } (adds rel="noopener noreferrer"); optional rel and predicate(href). Re-applies without a re-render; diffed by reference — keep the object stable

controls, density, imageHydrationAnimation, and rendering input changes apply in place — they never recreate the workspace view. Line-number visibility changes preserve the current CodeMirror document and selection. See the @mdzip/editor Rendering Extensibility docs for the contracts and lifecycle rules.

Native entry rendering (template directives)

<mdzip-workspace [bytes]="bytes" mode="editable">
  <ng-template mdzipEntryRenderer="manifest.json" let-context>
    <app-internals
      [manifest]="context.manifest"
      [editable]="context.mode === 'editable'"
      (manifestChange)="context.updateManifest($event)"
    />
  </ng-template>

  <ng-template [mdzipEntryRendererMatch]="isDrawioEntry" let-context>
    <app-drawio-viewer [entry]="context" />
  </ng-template>
</mdzip-workspace>

Import MdzipEntryRendererDirective alongside the component. mdzipEntryRenderer matches exact archive paths (string or array, case-insensitive); [mdzipEntryRendererMatch] takes a predicate. Optional mdzipEntryRendererId / mdzipEntryRendererPriority inputs control diffing and ordering. Embedded views are created in the component's view container — change detection and DI work normally — and are destroyed on selection change.

Outputs

Output Payload Description
changed MdzipWorkspaceChange Emitted when archive bytes change
saved MdzipWorkspaceSave Emitted on Save
snapshotChanged MdzipWorkspaceSnapshot Emitted on any state change
selectionChanged MdzipWorkspaceSnapshot Emitted when the editor selection changes
dirtyChanged MdzipWorkspaceSnapshot Emitted when the dirty flag changes
validationChanged MdzipWorkspaceSnapshot Emitted when validation state changes
colorSchemeChanged MdzipColorScheme Emitted when the color scheme changes
colorSchemePreferenceChanged MdzipColorSchemePreference Emitted when the user picks Light, Dark or System in the toolbar menu
previewWidthChanged MdzipPreviewWidthChoice Emitted when the user picks a width in the toolbar's page-width menu
previewRendered MdzipWorkspaceSnapshot Emitted when the preview HTML is mounted
assetsHydrated MdzipWorkspaceSnapshot Emitted once the mounted preview's images have loaded
linkActivated MdzipLinkActivatedEvent Emitted for every preview link click before built-in handling; call event.preventDefault() to take over
failed unknown Emitted on unrecoverable errors

Conversion hook

onConversionRequested is an input function (not an output, because it must return a value): bind [onConversionRequested]="handler" where handler is (action: MdzipConversionAction) => boolean | Promise<boolean>. It fires when the user triggers the markdown→MDZ conversion flow (nav button, Insert Image, or image paste on a plain .md). Return/resolve true to take over and suppress the built-in conversion dialog.

onPackRequested is the same kind of input function for the folder→.mdz packing decision surfaced by the exposed packFilesAsWorkspace(files, options) method — fires only when the file list contains more than one Markdown file, with the same return contract as onConversionRequested.

Image insertion

Use [imageInsertMode]="'markdown' | 'ask' | 'html'" for the built-in image markup flow. Bind [imageInsertHandler]="handler" for host-owned image UI; the handler can return Markdown or HTML sizing/alignment settings, return null to cancel, or return undefined to fall back to imageInsertMode.

Bind [imageEditHandler]="handler" to let users edit an existing image by clicking it. Fully opt-in — with no handler bound, clicking an image does nothing and no edit affordance appears; there is no built-in fallback dialog.

File management (nav pane)

With controls="standalone-editor" or "hosted-editor" (or fileActions: true in a custom policy), the navigation pane offers a right-click context menu: new .md file, new folder, rename/move, duplicate, replace, download, copy markdown link, set entry point, set cover image, and delete. Files can also be dragged between folders, and OS files can be dropped onto the pane. Copy and Download remain available in read-only mode. The same operations are exposed as component methods: removeFile, renameFile, setEntryPoint, and setCoverImage. whenRendered() resolves once the current preview (including its images) is mounted — useful for revealing or animating read-only preview content.

The linkActivated output fires for every preview link click, before the view's own handling, with the parsed link (kind: 'anchor' | 'document' | 'relative' | 'external', plus path, anchor, targetPath, sourcePath, modifier keys). Call event.preventDefault() in the handler to route the link yourself; unprevented clicks keep the built-in behavior. The component also exposes scrollToAnchor(anchor) (waits for the preview to mount, resolves whether it scrolled; safe straight after load), getAvailableAnchors(), openPath(path, { anchor }) (opens another file, optionally at an anchor) and getCurrentPath(). Changing only fileName (e.g. after Save As) renames in place without reopening; set preserveSelectionOnReopen to stay on the current file when the archive content changes. See the @mdzip/editor README.

Imperative API

All imperative methods are public instance methods on MdzipWorkspaceComponent, so any reference to the component instance works. No view query is required: a template reference variable can hand the instance directly to an event handler.

@Component({
  imports: [MdzipWorkspaceComponent],
  template: `
    <mdzip-workspace #workspace [bytes]="bytes" mode="editable" controls="hosted-editor" />
    <button (click)="save(workspace)">Save</button>
  `,
})
export class AppComponent {
  async save(workspace: MdzipWorkspaceComponent): Promise<void> {
    // Flush pending edits and persist
    const snapshot = await workspace.flush();
    if (snapshot) {
      await persist(snapshot.bytes);
      workspace.markPersisted();
    }

    // Execute editor commands
    await workspace.executeCommand('bold');
  }
}

To call methods outside an event handler, use a view query — the signal-based viewChild or the classic @ViewChild decorator:

private readonly workspace = viewChild.required(MdzipWorkspaceComponent);

async save(): Promise<void> {
  const snapshot = await this.workspace().flush();
  if (snapshot) {
    await persist(snapshot.bytes);
    this.workspace().markPersisted();
  }
}

Methods called before the view initializes are safe: they no-op and resolve to false/null/empty rather than throwing.

See the @mdzip/editor package for the full API reference, theming guide, and framework-agnostic usage.

This page mirrors @mdzip/editor-ng README — the canonical, versioned source in its home repository. It is re-fetched on every site build.