diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..34341ee --- /dev/null +++ b/INTENT.md @@ -0,0 +1,362 @@ +# markitect-quarkdown + +*open-reuse integration of the Quarkdown PDF build pipeline for markitect-tool.* + +## 1. Intent + +`markitect-quarkdown` exists to provide a structured, maintainable, and automatically monitored integration between `markitect-tool` and the Quarkdown 2.x document build pipeline, with special focus on reliable PDF generation. + +The repository captures the result of integrating Quarkdown as a valuable document rendering capability and reframes that integration as an **open-reuse Integration Definition**. + +The goal is not to casually fork or copy Quarkdown. +The goal is to reuse Quarkdown’s document compilation and PDF export capabilities through a clear boundary, with enough structure to track upstream change, validate compatibility, and escalate breakage to maintainers. + +--- + +## 2. Context + +`markitect-tool` aims to support structured authoring and rendering workflows for architecture, product, requirements, and technical documentation. + +Quarkdown is a modern open-source Markdown-based typesetting system that combines Markdown readability with LaTeX-like control, scripting capabilities, multiple document targets, and support for PDF export. It supports document types such as paged documents, slides, docs, plain documents, and PDFs. + +For `markitect-tool`, Quarkdown is interesting because it can provide a powerful build pipeline for producing polished PDF artifacts from source documents while keeping the authoring experience close to Markdown. + +This repository exists as the integration layer between those worlds: + +```text +markitect-tool + ↓ +markitect-quarkdown + ↓ +Quarkdown 2.x build pipeline + ↓ +PDF / HTML / document artifacts +```` + +--- + +## 3. open-reuse Role + +This repository is an **open-reuse integration repository**. + +It is responsible for transforming a working Quarkdown integration into a managed integration asset. + +The integration shall be: + +1. **Analyzed** — the reused parts of Quarkdown are identified. +2. **Classified** — the integration mode and risk profile are made explicit. +3. **Refactored** — the boundary between `markitect-tool` and Quarkdown is made stable. +4. **Reframed** — the integration is expressed as an open-reuse Integration Definition. +5. **Registered** — the integration can be managed by the open-reuse service. +6. **Maintained** — upstream Quarkdown changes can be monitored, validated, and escalated. + +--- + +## 4. Integration Scope + +The primary scope of this repository is the integration of the **Quarkdown 2.x build-to-PDF pipeline**. + +In scope: + +* Invocation of Quarkdown compilation from `markitect-tool` +* PDF artifact generation +* Configuration of Quarkdown document type and output behavior +* Management of required runtime assumptions +* Validation of generated artifacts +* Tracking of relevant upstream Quarkdown versions +* Compatibility checks against Quarkdown CLI behavior +* Handling of Quarkdown 2.x permission model implications +* Handling of output directory conventions +* Documentation of the integration boundary +* Registration metadata for open-reuse + +Out of scope: + +* Reimplementing Quarkdown +* Replacing Quarkdown’s compiler +* Maintaining a long-lived divergent Quarkdown fork +* Becoming a general Markdown renderer +* Becoming a full authoring environment +* Owning Quarkdown language design +* Owning Quarkdown upstream release decisions + +--- + +## 5. Upstream Project + +The upstream project is Quarkdown. + +Quarkdown describes itself as: + +> Markdown with superpowers. + +It is a modern Markdown-based typesetting system intended for papers, books, presentations, documentation websites, knowledge bases, and related publishing workflows. + +Relevant upstream characteristics: + +* Open-source Markdown-based typesetting system +* Supports HTML, PDF, and plain text targets +* Supports paged documents, slides, docs, and plain document types +* Extends Markdown with functions, variables, control structures, and scripting features +* Provides a CLI compilation workflow +* Supports PDF export through its HTML rendering pipeline +* Requires Java 17+ +* Requires Node.js, npm, and Puppeteer for PDF export +* Quarkdown 2.0.0 was released on April 23, 2026 +* Quarkdown 2.0 introduces a permission system relevant to safe document compilation +* Quarkdown 2.0 changes output behavior and contains breaking changes that must be tracked + +--- + +## 6. Reuse Mode + +The intended open-reuse classification is: + +```yaml +primary_reuse_mode: adapter +secondary_reuse_modes: + - dependency-reuse + - cli-boundary +``` + +The integration should treat Quarkdown primarily as an external build capability invoked through a controlled adapter boundary. + +The preferred model is: + +```text +markitect-tool + → MarkitectQuarkdownAdapter + → Quarkdown CLI / distribution + → generated PDF artifacts +``` + +This keeps the integration aligned with upstream and avoids unnecessary internal coupling to Quarkdown implementation details. + +Component extraction, patch overlay, and fork continuation should be avoided unless a later design decision explicitly justifies them. + +--- + +## 7. Reuse Boundary + +The central boundary of this repository is the **Markitect Quarkdown Build Boundary**. + +The boundary shall hide Quarkdown-specific invocation details from `markitect-tool`. + +It should define: + +* Input document location +* Output artifact expectations +* PDF generation mode +* Quarkdown CLI command shape +* Required runtime environment +* Permission settings +* Output directory handling +* Error interpretation +* Artifact validation rules + +The consuming side should not need to know Quarkdown internals. + +The boundary should make the following conceptual contract available: + +```text +Given a Markitect-compatible document source, +produce a validated PDF artifact using Quarkdown, +or return a structured build failure. +``` + +--- + +## 8. Integration Definition Intent + +This repository shall contain an open-reuse Integration Definition describing: + +* Integration identity +* Upstream Quarkdown source +* Upstream version policy +* Reuse mode +* Local boundary +* Required runtime assumptions +* Validation harness +* Maintainers +* Escalation conditions +* Known upstream breakpoints +* Update policy + +The Integration Definition is intended to be registered with the open-reuse service so that the integration can be monitored and maintained automatically. + +--- + +## 9. Upstream Change Sensitivities + +The integration is especially sensitive to the following Quarkdown upstream changes: + +* CLI command changes +* PDF export behavior changes +* Permission model changes +* Default output directory changes +* Preview or watch-mode behavior changes +* Artifact naming changes +* HTML-to-PDF rendering changes +* Puppeteer dependency changes +* Node.js/npm requirements +* Java runtime requirements +* Standard library renames +* License changes +* Security advisories +* Changes to installation or distribution layout + +Known Quarkdown 2.0 sensitivities include: + +* The new permission system using allow/deny semantics +* The new default output directory `./quarkdown-output` +* Changed preview output naming behavior +* The standard library module rename from `Injection` to `Html` +* The move toward offline HTML output with bundled assets +* Larger output directories due to local asset bundling +* PDF export dependency on Node.js, npm, and Puppeteer + +--- + +## 10. Validation Intent + +The integration shall be considered healthy only if it can repeatedly produce expected PDF artifacts from controlled test documents. + +Validation should include: + +* Quarkdown CLI availability check +* Runtime dependency check +* Minimal document compilation test +* Paged document PDF generation test +* Asset handling test +* Permission-restricted compilation test +* Failure-mode test for invalid documents +* Output artifact existence check +* Output artifact non-empty check +* Optional PDF metadata or text extraction check +* Regression comparison against known-good artifacts where feasible + +The validation harness should be executable by automation. + +--- + +## 11. Maintainer Escalation + +The open-reuse service should escalate to registered maintainers when: + +* Upstream Quarkdown releases a new version +* Validation fails after an upstream update +* Quarkdown CLI behavior changes +* PDF export behavior changes +* Required runtime dependencies change +* Permission requirements become stricter +* Generated artifacts change unexpectedly +* License terms change +* Security advisories affect Quarkdown or its PDF pipeline dependencies +* The integration definition becomes stale or incomplete + +Automation may propose updates, but maintainers remain responsible for accepting risky changes. + +--- + +## 12. Design Principles + +### Keep Quarkdown upstream-aligned + +Prefer clean invocation and configuration over local modification. + +### Keep the boundary explicit + +`markitect-tool` should depend on a stable local adapter, not on Quarkdown internals. + +### Validate artifacts, not just commands + +A successful CLI exit code is not enough. The generated PDF artifact must be checked. + +### Treat document compilation as potentially unsafe + +Quarkdown documents can contain powerful scripting constructs. The integration must respect Quarkdown 2.x permission controls and avoid overbroad defaults. + +### Prefer reproducible builds + +The integration should aim for predictable output paths, dependency versions, and artifact generation behavior. + +### Escalate uncertainty + +If upstream change impact cannot be classified confidently, the integration should require maintainer inspection. + +--- + +## 13. Repository Responsibilities + +This repository is responsible for: + +* Documenting the integration intent +* Providing the open-reuse Integration Definition +* Defining the Quarkdown adapter boundary +* Providing validation examples and test documents +* Capturing known compatibility assumptions +* Defining update and escalation policies +* Supporting registration with open-reuse +* Preserving the rationale for using Quarkdown inside `markitect-tool` + +This repository is not responsible for: + +* Developing Quarkdown itself +* Publishing Quarkdown releases +* Owning Quarkdown documentation +* Replacing Quarkdown issue tracking +* Maintaining unrelated Markdown renderers + +--- + +## 14. Expected Initial Repository Structure + +```text +markitect-quarkdown/ +├── INTENT.md +├── README.md +├── open-reuse.integration.yaml +├── examples/ +│ ├── minimal/ +│ ├── paged-pdf/ +│ └── assets/ +├── tests/ +│ ├── fixtures/ +│ ├── expected/ +│ └── validation/ +├── scripts/ +│ ├── validate-quarkdown.sh +│ └── build-pdf.sh +└── docs/ + ├── boundary.md + ├── upstream-notes.md + └── compatibility.md +``` + +--- + +## 15. Success Criteria + +This repository succeeds when: + +* `markitect-tool` can produce PDF artifacts through Quarkdown using a stable adapter boundary. +* The Quarkdown integration is described as an open-reuse Integration Definition. +* The integration can be registered with the open-reuse service. +* Upstream Quarkdown changes can be detected and classified. +* Validation can prove whether PDF generation still works. +* Maintainers are notified when automation cannot safely proceed. +* The integration remains aligned with upstream Quarkdown rather than becoming an unmanaged fork. + +--- + +## 16. One-Sentence Summary + +`markitect-quarkdown` is the open-reuse integration repository that makes Quarkdown’s PDF build pipeline available to `markitect-tool` through a clear adapter boundary, automated validation, upstream monitoring, and maintainer escalation. + +``` +::contentReference[oaicite:2]{index=2} +``` + +[1]: https://quarkdown.com/ "Quarkdown | Markdown with superpowers" +[2]: https://github.com/iamgio/quarkdown "GitHub - iamgio/quarkdown: Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases. · GitHub" + diff --git a/wiki/MarkitectQuarkdownResearch.md b/wiki/MarkitectQuarkdownResearch.md new file mode 100644 index 0000000..c6537c5 --- /dev/null +++ b/wiki/MarkitectQuarkdownResearch.md @@ -0,0 +1,94 @@ +**Short Take** +Quarkdown is much closer to a programmable publishing/typesetting system than to what `markitect-tool` is becoming. It compiles Markdown-like source into polished HTML/PDF/slides/docs with a Turing-complete function language, layout standard library, media pipeline, live preview, and renderer/post-renderer stack. + +`markitect-tool` is better positioned as a document infrastructure and pipeline framework: contracts, validation, extraction, references, processors, literate workflows, cache/index backends, provenance, and future policy/context engines. Quarkdown could fit as an optional output/rendering target or inspiration source, but I would not fold its language model into Markitect core. + +**What Quarkdown 2.0 Adds** +As of the Heise article on April 24, 2026 and the GitHub stable release on April 23, 2026, `v2.0.0` is the latest stable release I’d treat as relevant here. GitHub also shows a “Development build” pre-release, but given our current date of May 4, 2026, I would not base planning on that timestamp. + +Main 2.0 changes: + +- Permission system for compile-time access control: `project-read`, `global-read`, `network`, `native-content`, `all`, configured with `--allow` / `--deny`. +- Fully offline HTML output: fonts, code themes, and optional libraries are bundled/copied instead of relying on CDNs, with exceptions for some font cases. +- Parallel rendering across sibling elements. +- Lighter media storage: copy by reference and checksum validation to avoid unnecessary copies. +- Static `public/` assets copied to output root. +- HTML `baseurl`, canonical links, and `sitemap.xml`. +- Root output path symbol `@` for shared output-root assets. +- `.image` function with fine-grained media behavior. +- Linked `.ref` cross-references for headings, figures, tables, code blocks, equations, and custom numbered blocks. +- Function-call line continuation and `.keybinding`. + +**What Is Novel Compared With Markitect** +Quarkdown’s big novelty is the integrated authoring-to-rendering loop. It has one language that covers Markdown, functions, variables, loops, conditionals, layout, document metadata, includes, media handling, cross-references, themes, slides, docs, paged output, live preview, and post-rendering. + +Markitect currently has parts of this as infrastructure concepts, but not as one renderable authoring language. + +Notably novel or stronger in Quarkdown: + +- Rich function language inside Markdown. +- Layout primitives: rows, columns, grids, boxes, alignment, page margins, slides config. +- Numbering and references as rendered document semantics. +- First-class media storage and static asset output. +- Offline HTML packaging. +- Live preview/compiler workflow. +- Static-site-ish output support: sitemap, canonical links, `public/`. +- User-facing document types: `plain`, `paged`, `slides`, `docs`. +- A full compiler pipeline: lexing, parsing, function expansion, traversal, rendering, post-rendering. + +**What Markitect Already Has Conceptually** +Markitect already has several “deeper infrastructure” equivalents, though often not renderer-facing: + +- Includes/transclusion: `mkt include`, reference-backed processor include. +- References: namespaces, fragments, sections, regions, fenced blocks, tags, line ranges. +- Cross-reference foundation: content units and IDs exist, though rendered links do not. +- Processors: deterministic fenced-block processor registry. +- Literate workflows: `mkt tangle`, `mkt weave`, named chunks. +- Contracts: document expectations, metrics, fields, assertions, rubrics. +- Templates/generation: deterministic templates and generation hooks. +- Provenance: operation and backend provenance envelopes. +- Cache/backend planning: snapshot identity, refresh planning, dependency invalidation. +- Permission/policy concept: backend fabric has policy gateways, but not yet a Quarkdown-style execution sandbox. + +**Where Quarkdown Could Fit** +Best fit: optional rendering/export backend. + +Possible integration shape: + +- `markitect-tool` validates, extracts, composes, resolves references, checks contracts, runs deterministic processors, and emits Quarkdown source. +- Quarkdown compiles that source to HTML/PDF/slides/docs. +- Markitect backend tracks Quarkdown source inputs, generated outputs, media dependencies, checksums, and provenance. +- Markitect contracts could validate “pre-render” structure, while Quarkdown handles final layout/render semantics. + +This is cleaner than reimplementing Quarkdown’s renderer. Let Quarkdown be a publishing target; let Markitect remain the contract/pipeline/cache/provenance layer. + +**Gaps To Revisit Later** +High-value gaps inspired by Quarkdown: + +- Render-aware cross-reference model: figures, tables, equations, code blocks, custom numbered units. +- Asset/media pipeline: copied assets, checksums, public directory, root asset references. +- Output profiles: `plain`, `docs`, `slides`, `paged` as generation targets. +- Permission sandbox for processors and assisted/LLM execution. +- Preview/watch mode, probably later and outside core. +- Function-call style macro layer, but only if kept separate from core Markdown contracts. +- Document numbering and generated ToC as structured operations. +- Quarkdown export adapter: `mkt export quarkdown` or a dataflow step in WP-0011. +- Provenance for rendered outputs: source unit -> generated page/slide/asset. + +**Caution** +Quarkdown is GPL/AGPL-licensed depending on module/binary, so direct code reuse is probably not a good fit unless licensing is deliberately accepted. Conceptual interoperability or invoking it as an external tool is safer. + +**Recommendation** +Do not pivot Markitect toward being “our own Quarkdown.” Instead, add a future workplan or WP-0011/WP-0005 notes for: + +1. Quarkdown export adapter. +2. Render-aware reference/numbering model. +3. Media/static asset pipeline. +4. Processor permission sandbox. +5. Output provenance for rendered artifacts. + +That would let Markitect gain Quarkdown’s practical publishing utility without corrupting the elegant infrastructure direction we’ve built. + +Sources: [Heise article](https://www.heise.de/en/news/Books-and-slides-from-Markdown-Quarkdown-2-0-is-here-11271511.html), [Quarkdown v2.0.0 release notes](https://github.com/iamgio/quarkdown/releases/tag/v2.0.0), [Quarkdown homepage](https://quarkdown.com/), [function syntax docs](https://quarkdown.com/wiki/syntax-of-a-function-call/), [include docs](https://quarkdown.com/wiki/including-other-quarkdown-files/), [media storage docs](https://quarkdown.com/wiki/media-storage/), [pipeline docs](https://quarkdown.com/wiki/pipeline---function-call-expansion/). + +My take: Quarkdown’s function language is a very good inspiration for a future Markitect “document function layer,” especially if we keep it optional, markdown-close, typed enough for contracts, and integrated with our provenance/cache/access-control fabric. diff --git a/wiki/QuarkdownFunctionLanguage.md b/wiki/QuarkdownFunctionLanguage.md new file mode 100644 index 0000000..485b824 --- /dev/null +++ b/wiki/QuarkdownFunctionLanguage.md @@ -0,0 +1,117 @@ +This is one of Quarkdown’s most interesting ideas. +It is not just “Markdown plus directives”; it is closer to a small document programming language embedded in Markdown. + +**Core Idea** + +In Quarkdown, function calls are the central extension mechanism. They use a dot-prefixed syntax: + +```quarkdown +.sum {26} {16} +``` + +Arguments can be positional or named: + +```quarkdown +.multiply {6} by:{3} +``` + +They can be inline, block-level, nested, chained, or given an indented body argument. Quarkdown explicitly presents functions as its key feature and groups them across layout, utility views, math/logical operations, control flow, file data, and document metadata. Source: [Quarkdown function-call syntax](https://quarkdown.com/wiki/syntax-of-a-function-call/). + +**What Makes It Rich** + +1. **Functions produce document content, not just scalar values** + +A function may return text, Markdown content, layout structures, booleans, numbers, tables, etc. This is crucial: document generation and computation live in the same language. + +```quarkdown +.if {.isadult age:{20}} + You're an adult! +``` + +User-defined functions are declared with `.function`, and their body is a lambda-like block: + +```quarkdown +.function {greet} + to from: + **Hello, .to** from .from! +``` + +Source: [Declaring functions](https://quarkdown.com/wiki/declaring-functions/). + +2. **Block arguments make functions feel Markdown-native** + +Instead of forcing everything into parenthesized expressions, Quarkdown lets the final argument be an indented block: + +```quarkdown +.box {Example} + This is the content of the example. +``` + +That is a very elegant move. It keeps prose readable while making structured composition possible. + +3. **Chaining gives it pipeline ergonomics** + +This: + +```quarkdown +.pow {3} {2}::subtract {1}::sum {2} +``` + +is transformed conceptually into nested calls where each result becomes the first argument of the next call. That gives Quarkdown a pleasant Unix-pipe / method-chain feel without turning the surface language into JavaScript. Source: [Chaining calls](https://quarkdown.com/wiki/syntax-of-a-function-call/). + +4. **Variables are functions too** + +Variables are defined with `.var`, then accessed like zero-argument functions: + +```quarkdown +.var {name} {Quarkdown} + +Hello, .name! +``` + +They can hold simple values or block/layout content. There is also `.let` for scoped temporary variables. Sources: [Variables](https://quarkdown.com/wiki/variables/) and [Let](https://quarkdown.com/wiki/let/). + +5. **It has real control flow** + +Quarkdown has conditional functions like `.if` and `.ifnot`, plus loops like `.foreach` and `.repeat`: + +```quarkdown +.foreach {1..3} + n: + The number is **.n** +``` + +The loop returns an iterable of evaluated results, so it behaves more like `map` than a pure side-effect loop. Source: [Loops](https://quarkdown.com/wiki/loops/). + +6. **It has higher-order behavior** + +Lambdas show up in custom functions, `let`, `foreach`, sorting, filtering, and table operations. Inline lambdas can be passed as arguments, for example in table filtering: + +```quarkdown +.tablefilter {2} {@lambda x: .x::isgreater {20}} + ... +``` + +Source: [Table manipulation](https://quarkdown.com/wiki/table-manipulation/). + +7. **It includes typed-ish document values** + +The docs list value types such as string, number, Markdown content, boolean, none, iterable, dictionary, range, lambda, size, color, and dynamic values. It is weak/dynamic enough to remain author-friendly, but structured enough to support meaningful diagnostics and reusable functions. + +**Why This Matters For Markitect** + +For Markitect, the lesson is not necessarily “copy Quarkdown syntax.” The deeper lesson is this: + +Quarkdown treats document operations as composable functions with Markdown-native block bodies. + +That maps beautifully to our direction: + +- Markitect contracts could define allowed/expected processors as named document functions. +- Our fenced-block processors could grow into a function registry with capability metadata. +- Our dataflow pipelines could benefit from function chaining semantics. +- Our template/generation layer could distinguish pure deterministic functions, context-bound functions, LLM-backed functions, and unsafe external functions. +- Our diagnostics could be stronger than Quarkdown’s if every function call has provenance, declared inputs, permissions, and expected output type. + +My take: Quarkdown’s function language is a very good inspiration for a future Markitect “document function layer,” especially if we keep it optional, markdown-close, typed enough for contracts, and integrated with our provenance/cache/access-control fabric. + +