// SPDX-License-Identifier: CC-BY-SA-4.0 = pandoc-k9 Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk :toc: :toc-placement: preamble

Pandoc custom reader and writer for K9 Nickel self-validating components (.k9.ncl files) — converts between the K9 format and Pandoc's AST for documentation generation.

== Overview

K9 components are Nickel configuration files with a specific schema: metadata (name, version, description, author, trust_level), a security profile (three permission flags), and optional lifecycle recipes (install, validate, deploy, migrate, rollback).

pandoc-k9 provides two cooperating Lua files:

• k9-reader.lua — Pandoc custom reader that parses a .k9.ncl file into a Pandoc AST (header, metadata table, security profile section, recipe code blocks, raw source appendix). Produces HTML, Markdown, PDF, or any format Pandoc supports.
• k9-writer.lua — Reverses the process: walks a Pandoc AST and emits a syntactically valid .k9.ncl file the K9 toolchain can evaluate.

== K9 Security Levels

[cols="1,3"] |=== | Level | Capability

| 'Kennel | Data-only. No execution. Strict sandbox. Safe to parse anywhere. | 'Yard | Nickel evaluation + limited I/O. Capability-based sandbox. | 'Hunt | Full shell execution via recipes. Cryptographic signature required. |===

== Usage

[source,sh]

K9 → HTML documentation

pandoc -f k9-reader.lua component.k9.ncl -o docs.html

K9 → Markdown

pandoc -f k9-reader.lua component.k9.ncl -t markdown

Round-trip: K9 → Pandoc AST → K9

pandoc -f k9-reader.lua input.k9.ncl -t k9-writer.lua -o roundtrip.k9.ncl

== Related

• link:https://github.com/hyperpolymath/k9-showcase[k9-showcase] — K9 component showcase
• link:https://nickel-lang.org[Nickel] — configuration language used by K9
• link:https://pandoc.org/custom-readers.html[Pandoc custom readers]

== License

MPL-2.0. See link:LICENSE[LICENSE].