swift.markdown.video.mp4
A native AppKit Markdown editor for macOS, built on TextKit 2 and bridged to SwiftUI. It is the editor inside Nodes, a macOS notes app. Live styling, wiki-link support, fenced code blocks with syntax highlighting, LaTeX rendering, embedded images, and GitHub-style task checkboxes.
- Live Markdown styling — bold, italic, headings, lists, blockquotes, GFM tables, code, links, task checkboxes, horizontal rules
- Wiki-style linking with two-form storage / display roundtripping
(
[[Name|<id>]]↔[[Name]]) - Image embeds — both
![[Name]](Obsidian-style, embedder supplies the
bytes) and standard Markdown - LaTeX — both block (
$$ … $$) and inline ($…$), embedder supplies the renderer - Code blocks with embedder-supplied syntax highlighting and overlayable copy buttons
- Reading column — opt-in fixed-width centered column, wide tables
break out to the full window width (
readingWidth) - Scroll-away header — host your own SwiftUI view above the document; it scrolls with the content and collapses to a pinned top row
- TextKit 2 layout for accurate, modern text rendering
- Writing Tools integration on macOS 15.1+
- Comfortable bottom overscroll so the caret never pins to the viewport edge while typing
- Drag-select autoscroll boost for long documents
- Spelling & grammar with code/LaTeX/wiki-link suppression
- Extensions — opt-in constructs defined by a delimiter pair (
==highlight==,~~strikethrough~~, …); add your own viaMarkdownExtension - Directives — opt-in constructs defined by a name and typed arguments, for what a delimiter pair can't express (
@font(size: 18){text}); add your own viaMarkdownDirective
dependencies: [
.package(url: "https://github.com/nodes-app/swift-markdown-engine", from: "0.1.0")
],
targets: [
.target(
name: "YourApp",
dependencies: [
.product(name: "MarkdownEngine", package: "swift-markdown-engine"),
]
)
]Or in Xcode: File → Add Package Dependencies… and paste the repo URL.
The package ships three library products — add only what you need:
| Product | Use when |
|---|---|
MarkdownEngine |
You want the editor only. Zero external dependencies. |
MarkdownEngineCodeBlocks |
You want the full visual code-block experience — background fill, monospace font, and syntax highlighting — without writing your own bridge. Pulls in HighlighterSwift transitively. See Customization → Code Blocks. |
MarkdownEngineLatex |
You want LaTeX formula rendering without writing your own bridge. Pulls in SwiftMath transitively. See Customization → LaTeX Rendering. |
import SwiftUI
import MarkdownEngine
struct EditorScreen: View {
@State private var text: String = "# Hello, *world*"
var body: some View {
NativeTextViewWrapper(text: $text)
}
}That's it. See Customization below for syntax highlighting, themes, wiki-link state, and more.
Displaying multiple editors? Pass a stable, unique
documentId: "your-doc-id"so undo history and pending replacements stay scoped to each editor instance.
The engine talks to your app through four service protocols, each with a no-op default so you only implement what you actually need:
| Protocol | What you supply | Ready-made bridge / suggested library |
|---|---|---|
WikiLinkResolver |
Resolve a [[Name]] to a stable opaque id |
(your data model) |
EmbeddedImageProvider |
Look up an NSImage for ![[Name]] |
(your asset store) |
SyntaxHighlighter |
Highlight code blocks for a given language | HighlighterSwiftBridge (recommended) — built on HighlighterSwift |
LatexRenderer |
Render a LaTeX string to an NSImage |
SwiftMathBridge (recommended) — built on SwiftMath |
Implement what you need and pass it through MarkdownEditorServices:
struct MyResolver: WikiLinkResolver {
func resolve(displayName: String, range: NSRange) -> WikiLinkResolution? {
myIndex[displayName].map { WikiLinkResolution(id: $0, exists: true) }
}
}
configuration.services = MarkdownEditorServices(
wikiLinks: MyResolver()
// images, syntaxHighlighter, latex omitted → no-op defaults
)Each protocol and its no-op default are documented in DocC.
Recommended path: depend on the MarkdownEngineCodeBlocks product
and use the bundled HighlighterSwiftBridge. Rolling your own
SyntaxHighlighter has subtle footguns the bridge already handles —
line-height metrics across light/dark themes, appearance-change
observation, layout-pass timing, font name extraction from the theme,
and CSS-theme-derived background colors. Use the bundle unless you
specifically need a non-HighlighterSwift library.
import MarkdownEngineCodeBlocks
var configuration = MarkdownEditorConfiguration.default
configuration.services = MarkdownEditorServices(
syntaxHighlighter: HighlighterSwiftBridge()
)The bridge auto-switches between atom-one-light and atom-one-dark
with system appearance. Different theme names or a pinned single theme
are configurable via init params — see DocC.
Need a different highlighter library entirely? Implement
SyntaxHighlighter yourself (see Service Protocols
above for the declaration) and reference the bundled bridge in
Sources/MarkdownEngineCodeBlocks/ as a working example.
Recommended path: depend on the MarkdownEngineLatex product and use
the bundled SwiftMathBridge. Hand-rolling a LatexRenderer has
real footguns the bridge already handles — appearance-aware text color,
zero-sized output guards (lockFocus crashes on 0×0 images),
window-vs-NSApp appearance distinction, single-letter padding, and an
internal cache keyed by (latex, font size, appearance, theme color).
import MarkdownEngineLatex
var configuration = MarkdownEditorConfiguration.default
configuration.services = MarkdownEditorServices(
latex: SwiftMathBridge()
)The bridge uses the Latin Modern math font and tints formulas with
MarkdownEditorTheme.latexLightModeText / latexDarkModeText. Pass
singleLetterPaddingBottom: to override the engine's matching default.
Every color the editor puts on screen reads from MarkdownEditorTheme:
var theme = MarkdownEditorTheme.default
theme.bodyText = .labelColor
theme.findMatchHighlight = NSColor(named: "MyAccent")!
var configuration = MarkdownEditorConfiguration.default
configuration.theme = themeDefaults map to NSColor dynamic system colors, so light/dark mode
keeps working without extra code.
MarkdownEditorConfiguration exposes every spacing / sizing / behavior
knob the engine has, grouped by concern:
var configuration = MarkdownEditorConfiguration.default
configuration.codeBlock.fontSizeScale = 0.9
configuration.headings.fontMultipliers = [2.4, 1.8, 1.4, 1.1, 0.9, 0.75]
configuration.overscroll.percent = 0.4
configuration.lists.helpersEnabled = false
configuration.safeAreaInsets = SafeAreaInsets(top: 56) // headroom under a translucent toolbarTwo optional bindings on NativeTextViewWrapper let you observe
wiki-link state and push inline replacements programmatically. Pass
only what you need — each is independent and defaults to a no-op:
NativeTextViewWrapper(
text: $text,
isWikiLinkActive: $isWikiLinkActive,
pendingInlineReplacement: $pendingReplacement
)isWikiLinkActive— the wrapper sets this totruewhile the caret sits inside a[[Name]]link, so you can present a contextual UI.pendingInlineReplacement— assign a non-nil value to push a replacement (e.g. an autocomplete result); the engine consumes it and clears the binding.
By default the editor scrolls internally. Set heightBehavior to
.fitsContent to make it grow to fit its content and report that height to
SwiftUI, so an enclosing ScrollView scrolls the page instead:
ScrollView {
NativeTextViewWrapper(text: $text, configuration: .init(heightBehavior: .fitsContent))
}Composes with readingWidth and the scrolling header, and is switchable at
runtime. .fitsContent lays out the whole document (no viewport
virtualization), so prefer it for small-to-medium content. See
HeightBehavior in DocC for the full behavior.
Give long documents a fixed-width centered column; wide GFM tables break out to the full window width, Google-Docs-style:
configuration.readingWidth = 650Text wraps at readingWidth and never re-wraps on resize (only the column's
position moves), keeping live resize smooth. Leave it nil (default) to fill
the container edge-to-edge.
Host a SwiftUI view above the document body that scrolls away with it — metadata, a property table, a contextual toolbar:
NativeTextViewWrapper(
text: $text,
header: AnyView(MyDocumentHeader(document: document)),
headerCollapsedHeight: 40,
headerExpanded: isHeaderExpanded
)The engine hosts it in an NSHostingView, reserves its intrinsic height, and
keeps it fully interactive. headerExpanded: false collapses to
headerCollapsedHeight (top row stays, rows below clip away, animated). Inject
any required environment before wrapping in AnyView, and give wrapping
content an explicit height so it doesn't clip at the band's bottom. Composes
with readingWidth; an optional placeholder: shows ghost text while empty;
header: nil (default) adds nothing. The demo's Header toggle shows it.
An extension is a pair of delimiters plus how to style what sits between
them — that is the whole shape, and what distinguishes it from a
directive. The core engine parses pure markdown; constructs like
==highlight==, ~~strikethrough~~, and ::: … ::: container blocks are
opt-in extensions:
var config = MarkdownEditorConfiguration()
config.extensions = [HighlightExtension(), StrikethroughExtension(), ContainerExtension()]Unregistered syntax stays literal text. An extension contributes an inline
form (InlineSyntax), a fenced block form (BlockSyntax), or both — plus the
attributes for its content and an HTML wrapper for rich copy. The parser owns
all geometry, marker/fence hiding, caret reveal, and incremental restyling, so
extensions behave identically to built-ins and cannot affect neighboring
constructs. Conform to MarkdownExtension to add your own.
The second opt-in seam, for constructs that need a NAME and TYPED ARGUMENTS rather than delimiters:
var config = MarkdownEditorConfiguration()
config.directives = [FontDirective(), ColorDirective()]@font(size: 18){eighteen point}, @font(size: 1.5em){half again}, @color(red){tinted}Two forms: container (@font(size: 18){text}) and self-contained
(@pagebreak). A container's font transform composes over the font inherited
at that point in the tree, so @font(size: 18){**bold**} is bold and 18pt,
and the same call inside a heading keeps the heading's weight. There is no
"applies to everything after me" form — a directive's effect is scoped to its
own node, which is what keeps per-keystroke restyling block-local.
Self-contained calls parse and claim their span, so nothing inside them is autolinked or emphasized — but they currently render as their literal source, and no self-contained directive ships yet. The glyph presentation that would draw one as a rule or a badge arrives with a later phase.
The marker defaults to @ and is configurable per registry
(config.directiveSettings) and per directive, and several markers can be
registered at once. An unregistered name stays literal text, and a directive
only opens at a non-word character — so name@example.com is never a
directive. If your app already uses @ to trigger mentions, give directives
their own marker instead of disambiguating at the keystroke; the
registered-names-only rule keeps @alice literal, but the trigger itself is
still shared.
Two limits worth knowing before you author one. A body holding a span claimed by an earlier parse pass — an inline code span, or a backslash escape — leaves the whole construct literal rather than producing a directive around it:
@font(size: 18){this has `code` in it} ← not a directive, stays as typed
@font(size: 18){this has *emphasis*} ← fine, composes normallyConstructs claimed in the same pass or later ($…$, links, emphasis, nesting)
work inside a body. And the engine ships the seam, not a picker: there is no
completion UI for directive names or argument values.
Conform to MarkdownDirective to add your own; a typical one is about 30
lines, including its argument schema and HTML. FontDirective and
ColorDirective are reference implementations meant to be read — they are not
registered unless you register them.
A runnable SwiftUI demo lives in Demo/.
Open it in Xcode and hit Run — the demo references the package via
a local path, so any engine edit rebuilds into the demo on the next run.
Its sample document is ordered by where each construct comes from rather than by feature: core markdown first, then the optional bridge products, then the two opt-in seams. The toolbar's Opt-in seams toggle unregisters the extensions and directives at runtime, so that last part collapses into literal text while the rest doesn't move a pixel — the fastest way to see what the core grammar actually knows.
If you're seeing a "missing package product" error, it's almost always stale package cache. Use File → Packages → Reset Package Caches once and rebuild.
Full API docs ship as DocC. In Xcode: Product → Build Documentation
(⇧⌃⌘D); for local CLI preview see CONTRIBUTING.md. Once
hosted on Swift Package Index, docs will live at
https://swiftpackageindex.com/nodes-app/swift-markdown-engine/documentation.
- macOS 14 or later (15.1+ for Apple Writing Tools integration)
- Swift 5.9 / Xcode 15 or later
MarkdownEngine is currently pre-1.0. The public API may change between
minor releases as it stabilizes. Production use is fine — pin a specific
version (0.x.y) in your Package.swift.
MarkdownEngine is the editor inside Nodes, a macOS app for writing, linking and exploring notes. This is not a side project we open-sourced and walked away from — it is the editor our own users type in every day, and every fix here ships in a real app first.
If it is useful to you, telling someone about it is all we would ask for.
Bug reports, ideas, and pull requests are welcome.
- ARCHITECTURE.md — codemap and pipeline guide for contributors
- CONTRIBUTING.md — setup, PR process, and design constraints
MarkdownEngine is released under the Apache 2.0 License. See LICENSE for the full text.
Built by a small team in Munich and Zurich. Day-to-day on Instagram.