@document.meta
title: NorgKit Example
authors: [rbdr]
categories: documentation
version: 1.0
@end

* NorgKit

NorgKit is a pure-/Foundation/ parser for *Norg* documents. This file exercises
a representative spread of the syntax so it can double as a parser benchmark and
a quick visual reference.

** Inline markup

A paragraph can mix *bold*, /italic/, _underline_ and -strikethrough- runs, plus
`verbatim` spans and $f(x) = x^2$ math. Modifiers /can be _nested_/ where it makes
sense, and a {https://github.com/nvim-neorg/neorg}[link] points elsewhere while a
bare {* NorgKit} link references a heading. Escapes like \*these\* stay literal.

** Tasks

- (x) Parse headings and their TODO status
- (x) Parse ordered and unordered lists
- ( ) Parse `@code` blocks with a language
- (-) Wire up the benchmark target
- (=) Investigate a streaming backend
- (?) Decide on a tree-sitter bridge
-- ( ) Nested subtask one
-- (x) Nested subtask two
- (!) An urgent follow up
- (+) A recurring chore
- (_) A cancelled idea

** Ordered steps

~ Read the document into memory
~ Split it into lines
~ Recognise each block
~~ Detached modifiers first
~~ Then ranged tags
~ Emit the block list

** Quotes

> A language that doesn't affect the way you think about programming is not worth
> knowing.
> (x) Even a quote can carry a settled status.

** Code

@code swift
import NorgKit

let document = NorgParser.parse(source)
for block in document.blocks {
    print(block.line, block.status as Any)
}
@end

@code
plain verbatim block without a language
@end

** Other ranged tags

@math
\int_0^1 x^2 \, dx = \frac{1}{3}
@end

@image.png diagram alt text
/assets/architecture.png
@end

** Definitions and footnotes

$ Norg
A structured plain-text format for note-taking and task management.

$$ Ranged definition
This form scans every block until the closing modifier, so it can hold
- a list,
- and more than one paragraph.
$$

^ source
The reference lives in the Neorg specification repository.

** Prose

This final section is a longer paragraph intended to be soft-wrapped across
several source lines so the paragraph-merging path is exercised. The parser
should join these physical lines into a single logical paragraph, preserving the
inline styling such as *emphasis* and `code` while collapsing the line breaks
into spaces. It keeps going for a few more lines to give the merge loop some
real work to do during the benchmark run.

---

A weak delimiter precedes this paragraph and a horizontal rule follows it.

___

* Closing heading

That's the end of the example document.