generated from coulomb/repo-seed
Quarkdown research and integration intent
This commit is contained in:
362
INTENT.md
Normal file
362
INTENT.md
Normal 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"
|
||||
|
||||
Reference in New Issue
Block a user