coulomb/markitect-quarkdown
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Quarkdown research and integration intent

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-04 12:37:28 +02:00
parent bc3935c074
commit d3214f51be
3 changed files with 573 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

362
INTENT.md Normal file
View File

@@ -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"

94
wiki/MarkitectQuarkdownResearch.md Normal file
View File

@@ -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.

117
wiki/QuarkdownFunctionLanguage.md Normal file
View File

@@ -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.