phormat

Phormat

Source-canonical block Markdown editor for Svelte 5. Markdown source is the persisted representation; a typed block tree is the in-memory editing model.

Monorepo note: The npm package is phormat. This repository folder may still be named md-editor.

Install

npm install phormat

Peer dependencies (install in your app):

• svelte ^5.0.0
• phoundry-ui >=0.0.18
• @iconify/svelte ^4.0.0 || ^5.0.0

In a Phoundry monorepo, use a file: dependency (e.g. "phormat": "file:../md-editor") and run npm run prepack in this repo after editing package source.

Publishing

Maintainers: see docs/publishing.md. Quick path: npm run release after npm login and ensuring phoundry-ui@>=0.0.18 is on npm.

Styles

Import phoundry-ui styles (host-owned) plus Phormat’s editor CSS / Tailwind @source scan:

@import 'phoundry-ui/styles';
@import 'phoundry-ui/themes/default-dark/theme.css';
@import 'phormat/styles';

phormat/styles does not re-import phoundry-ui — that keeps the host’s selected UI package authoritative when nested copies exist.

Overlay setup

Phormat uses phoundry-ui mono icons, context menus, and inline formatting popovers. Register the mono collection, call setupOverlays() once in your root layout, and render the overlay hosts:

<script>
  import { ContextMenuOverlay, PopoverOverlay, setupOverlays } from 'phoundry-ui';
  import { registerPhoundryMono } from 'phoundry-ui/icons';

  registerPhoundryMono();
  setupOverlays();
</script>

<ContextMenuOverlay />
<PopoverOverlay />

Phormat opens the inline formatting toolbar and link-edit chrome via popover.open({ content }) — empty PopoverOverlay is enough. Optional package exports InlineFormattingToolbar / LinkEditPopoverHost remain for hosts that prefer default-child mounting. See the demo layout.

Quick start

<script>
  import { PhormatEditor } from 'phormat';

  let source = $state('# Hello\n\nEdit me.');
</script>

<PhormatEditor value={source} onchange={(next) => (source = next)} />

For file-backed apps, the parent owns load/save and passes value / onchange; call markSaved() on the internal state only if you use MarkdownEditor directly. With PhormatEditor, track persistence against your own on-disk baseline and use bind:embedder to prepare a focused inline draft before writing or closing (see package usage).

Package exports

Import	Purpose
phormat	PhormatEditor, InlineFormattingToolbar, LinkEditPopoverHost, MarkdownEditor state class, model types and helpers
phormat/styles	Editor CSS + Tailwind @source for packaged Phormat components (host imports phoundry-ui/styles)
phormat/demo	Browser-only demo helpers (file load, localStorage drafts, download) — not for production file I/O

Documentation

• Package usage — embedder API, props, dirty baseline, demo vs production boundaries
• Architecture overview — internal pipeline and extension points (contributors)
• Context glossary — domain terms

Demo app

npm install
npm run dev

Dev server: http://127.0.0.1:5181/ (pinned with strictPort; see vite.config.ts). If you see the Phoundry marketing site instead, a stale phoundry-website dev server is squatting on 5181 — stop it and restart Phormat.

The SvelteKit route at src/routes/+page.svelte is a reference implementation using phormat/demo for browser file upload, draft recovery, and export.

Scripts

Command	Description
npm run dev	Demo dev server
npm run check	Typecheck
npm run test	Unit tests
npm run prepack	Build library (dist/)
npm run pack:local	Build + create .tgz for inspection
npm run release	Patch version, build, npm publish