markitect-quarkdown/INTENT.md

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