1 files changed, 68 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5020ad8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+# NorgEditor
+
+NorgEditor provides a syntax-highlighting and indentation aware SwiftUI source
+editor for `.norg` / [Neorg](https://github.com/nvim-neorg/neorg) documents, built on
+[NorgKit](https://git.sr.ht/~rbdr/norgkit)'s lexer and the [NorgKeyboardToolbar](https://git.sr.ht/~rbdr/norg-keyboard-toolbar) input accessory.
+
+## Installation
+
+Add the package with Xcode package manager: `https://git.r.bdr.sh/norg-editor`,
+and depend on `NorgUI` from your target.
+
+## Usage
+
+Bind `NorgEditor` to a `String` of source. It highlights on every keystroke; on
+iOS/iPadOS it also installs the Norg keyboard toolbar and keeps the caret above
+the keyboard.
+
+```swift
+import SwiftUI
+import NorgEditor
+
+struct NoteEditor: View {
+    @Binding var source: String
+
+    var body: some View {
+        NorgEditor(text: $source)
+            .padding(.horizontal)
+    }
+}
+```
+
+## Theming
+
+Highlighting colours and the base font can be changed by creating an
+`EditorTheme` aund using the `.norgEditorTheme(_:)` modifier.
+
+```swift
+var theme = EditorTheme.default
+theme.font = UIFont(name: "IBMPlexMono-Light", size: 14) ?? theme.font
+theme.headingColor = { _ in .systemTeal }
+theme.linkColor = .systemBlue
+
+NorgEditor(text: $source)
+    .norgEditorTheme(theme)
+```
+
+### EditorTheme API
+
+`PlatformFont` and `PlatformColor` are aliases for `UIFont`/`UIColor` on UIKit
+platforms and `NSFont`/`NSColor` on macOS.
+
+| Property | Type | Styles |
+| --- | --- | --- |
+| `font` | `PlatformFont` | Base font; `bold`/`italic` runs derive traited variants |
+| `textColor` | `PlatformColor` | Plain, unstyled source |
+| `headingColor` | `(Int) -> PlatformColor` | Heading marker runs (`*`…), per level |
+| `markerColor` | `PlatformColor` | List/quote/definition/footnote/table markers, delimiting lines, rules, inline-modifier delimiters, link brackets, escapes |
+| `taskStatusColor` | `(TaskStatus) -> PlatformColor` | Task status markers, e.g. `(x)` |
+| `tagColor` | `PlatformColor` | Ranged-tag header (`@code …`) and `@end` |
+| `verbatimColor` | `PlatformColor` | Inline `` `verbatim` `` and ranged-tag body lines |
+| `commentColor` | `PlatformColor` | Inline comments (`%…%`) |
+| `linkColor` | `PlatformColor` | Link/anchor locations and descriptions |
+| `spoilerColor` | `PlatformColor` | `spoiler` inline runs |
+
+## Requirements
+
+- Swift 6 tools
+- iOS 18 / iPadOS 18 / visionOS 2 (UIKit) or macOS 15 (AppKit)