README.md

  1# OrgSwift
  2
  3A dependency-free Swift library that renders a practical subset of
  4[org-mode](https://orgmode.org). Two products:
  5
  6- **`OrgSwift`** — org to sanitized HTML or `AttributedString`. Pure Foundation,
  7  no SwiftUI, WebKit, UIKit, or third-party packages.
  8- **`OrgSwiftUI`** — org to native SwiftUI views, no web view involved.
  9
 10Originally extracted from the hand-rolled renderer in the Hutch iOS client so it
 11could be shared across apps, and since rebuilt around an element tree: org is
 12parsed once into a document model, and each output format walks it. See
 13[ARCHITECTURE.md](ARCHITECTURE.md).
 14
 15## Supported syntax
 16
 17Headings (with trailing `:tags:`), paragraphs, ordered/unordered lists (with
 18arbitrary-depth nesting, wrapped lines, and `[ ]`/`[x]`/`[-]` task checkboxes),
 19description lists (`term :: definition` → `<dl>`), multi-paragraph list items,
 20list items holding block elements (a source block, table, or quote inside an item),
 21tables (with `:---:` alignment), `#+begin_src` / `example` / `quote` / `center` /
 22`verse` / `export` blocks and `#+begin_<name>` special blocks,
 23`#+TITLE`/`#+AUTHOR`/`#+DATE` metadata, `#+CAPTION`/`#+ATTR_HTML`/`#+NAME`
 24figures, org links and images (`[[file:x.png]]` → `<img>`, `[[dest][label]]` →
 25link, `[[id:target]]` → `#target`), horizontal rules, comments, timestamps
 26(`<2024-01-15 Mon>`, inactive, times, and ranges → `<time>`), footnotes
 27(references, inline, and definitions → a `<section class="footnotes">`), and
 28inline markup (`*bold*`, `/italic/`, `~code~`, `=verbatim=`, `+strike+`,
 29`_underline_`, `x^2` superscript, bare-URL and email autolinks). Other
 30`#+KEYWORD:` lines are consumed as document metadata.
 31
 32Output is sanitized: only `http`/`https`/`mailto` link schemes and
 33`http`/`https` image schemes are allowed; everything else is dropped.
 34
 35## Usage
 36
 37```swift
 38import OrgSwift
 39
 40let html = OrgRenderer.renderToHTML(orgSource)
 41```
 42
 43### Relative links
 44
 45Pass an `OrgRenderOptions` to rewrite repository-relative links and images to
 46absolute `blob` URLs. When `owner`/`repositoryName` are nil (the default),
 47relative links are left as-is, which the scheme allowlist then drops.
 48
 49```swift
 50let html = OrgRenderer.renderToHTML(
 51    orgSource,
 52    options: OrgRenderOptions(
 53        host: "git.sr.ht",       // default
 54        owner: "~ccleberg",
 55        repositoryName: "Hutch",
 56        ref: "HEAD",             // default
 57        readmePath: "README.org" // resolves paths relative to this file
 58    )
 59)
 60```
 61
 62`./images/badge.svg` then resolves to
 63`https://git.sr.ht/~ccleberg/Hutch/blob/HEAD/images/badge.svg`.
 64
 65### Native SwiftUI
 66
 67`OrgSwiftUI` renders the same parse as views rather than HTML — selectable text,
 68Dynamic Type, and VoiceOver, without a `WKWebView`.
 69
 70```swift
 71import OrgSwiftUI
 72
 73OrgView(orgSource, options: options)
 74```
 75
 76`OrgRenderOptions` means the same thing here, so links and images resolve exactly
 77as they do in HTML. An image whose source will not resolve to an *absolute* URL
 78shows its alt text instead: HTML can lean on a document base URL, a view cannot.
 79
 80Syntax highlighting for `#+begin_src` blocks is the app's to supply, which is what
 81keeps this package dependency-free:
 82
 83```swift
 84struct Highlighter: OrgCodeStyler {
 85    func highlighted(code: String, language: String?) -> AttributedString? {
 86        // nil means "show it as plain monospaced text"
 87    }
 88}
 89
 90OrgView(orgSource, options: options, styler: Highlighter())
 91```
 92
 93Org's `TODO`/`DONE` keywords default to semantic colors, because a package
 94cannot know your palette. Pass your own:
 95
 96```swift
 97OrgView(orgSource, options: options,
 98        keywords: OrgKeywordStyle(todo: .gbOK, done: .gbDone))
 99```
100
101### Title and heading level
102
103Two presentation knobs, both defaulting to how Hutch rendered:
104
105- `metadataHeader` (default `true`) — emit a leading `<div class="org-metadata">`
106  with the `#+TITLE`/`#+AUTHOR`/`#+DATE`. Set `false` to drop it (e.g. when the
107  surrounding UI shows the title itself).
108- `headingLevelOffset` (default `0`) — added to each heading's star count, clamped
109  to `1...6`. Default renders `*` as `<h1>`; use `1` to render `*` as `<h2>`,
110  leaving `<h1>` for a document title.
111
112### Syntax highlighting
113
114Code blocks are highlighted through a protocol so the library carries no
115highlighter dependency:
116
117```swift
118public protocol CodeHighlighter {
119    func highlightedHTML(code: String, language: String?) -> String?
120}
121```
122
123The default `PlainCodeHighlighter` returns `nil`, so blocks fall back to escaped
124`<pre><code>`. Provide your own conformer to plug in a real highlighter:
125
126```swift
127let html = OrgRenderer.renderToHTML(orgSource, highlighter: MyHighlighter())
128```
129
130A conformer returning `nil` for a given block gets the same escaped fallback.
131
132## Conformance
133
134OrgSwift is tested against the shared [org-conformance](../org-conformance)
135corpus, whose golden outputs come from `orgo` (itself validated against Emacs
136`ox-html`). `swift test` locates a sibling `../org-conformance` checkout, or set
137`ORG_CONFORMANCE_DIR`. The suite reduces both this renderer's HTML and orgo's to
138a semantic skeleton and compares them; the current pass/divergence state is
139recorded per case, so a closed gap or a regression both surface as a failing
140test. See [GAPS.md](GAPS.md) for the outstanding backlog.