[Docs] Say plainly that OciDeck is independent of Marp, and verify the Marp-CLI claim #591

New issue

Closed

opened 2026-07-22 16:18:10 +00:00 by brenno · 1 comment

brenno commented

2026-07-22 16:18:10 +00:00

Owner

Found in the pre-publication first-impression review.

Evidence: "Marp" appears eight times in README.md (:5, :33, :36, :37, :38, :41, :112, :114), including "a bundled Marp CSS theme". The disclaimer that would prevent the obvious misreading lives only in THIRD_PARTY_NOTICES.md:134 — "Not affiliated with, endorsed by, or a product of the Marp Team."

OciDeck does not use Marp: the renderer is its own (lib/services/marp_html_service.dart plus lib/services/parts/marp_html_service_*.dart), built on marked, as docs/ARCHITECTURE.md:302 states outright ("this is marked, not Marp Core").

Yet docs/FILE_FORMAT.md:7 promises that "a saved presentation can be processed directly with the Marp CLI or the VS Code Marp extension", and nothing verifies it: grep -rn "npx|marp-cli|node " Makefile finds nothing, there is no Node tooling anywhere in the repo, and no test named against the Marp CLI.

Why this matters now: the Marp community is the single most likely first audience, and their two questions will be "is this a fork or a frontend?" and "did you actually run your output through marp-cli?". The README implies a closer relationship than exists, and the compatibility promise — the core value proposition, the reason the format is called the stable contract — is an untested assertion made by a reimplementation. If one exported deck fails in real Marp, that becomes the headline.

Proposal: two sentences in the README under the opening paragraph: OciDeck is an independent project that reads and writes Marp-compatible Markdown, is not affiliated with or endorsed by the Marp Team, and does not embed Marp Core — it has its own renderer. Then a make verify-marp target (opt-in, npx @marp-team/marp-cli) that runs a handful of fixture decks through the real CLI and diffs slide counts. If that does not land before launch, soften docs/FILE_FORMAT.md:7 to "designed to be processed by the Marp CLI (not yet verified against it)".

Found in the pre-publication first-impression review. **Evidence:** "Marp" appears eight times in `README.md` (`:5, :33, :36, :37, :38, :41, :112, :114`), including "a bundled Marp CSS theme". The disclaimer that would prevent the obvious misreading lives only in `THIRD_PARTY_NOTICES.md:134` — "Not affiliated with, endorsed by, or a product of the Marp Team." OciDeck does not use Marp: the renderer is its own (`lib/services/marp_html_service.dart` plus `lib/services/parts/marp_html_service_*.dart`), built on `marked`, as `docs/ARCHITECTURE.md:302` states outright ("this is `marked`, not Marp Core"). Yet `docs/FILE_FORMAT.md:7` promises that "a saved presentation can be processed directly with the Marp CLI or the VS Code Marp extension", and nothing verifies it: `grep -rn "npx|marp-cli|node " Makefile` finds nothing, there is no Node tooling anywhere in the repo, and no test named against the Marp CLI. **Why this matters now:** the Marp community is the single most likely first audience, and their two questions will be "is this a fork or a frontend?" and "did you actually run your output through marp-cli?". The README implies a closer relationship than exists, and the compatibility promise — the core value proposition, the reason the format is called the stable contract — is an untested assertion made by a reimplementation. If one exported deck fails in real Marp, that becomes the headline. **Proposal:** two sentences in the README under the opening paragraph: OciDeck is an independent project that reads and writes Marp-compatible Markdown, is not affiliated with or endorsed by the Marp Team, and does not embed Marp Core — it has its own renderer. Then a `make verify-marp` target (opt-in, `npx @marp-team/marp-cli`) that runs a handful of fixture decks through the real CLI and diffs slide counts. If that does not land before launch, soften `docs/FILE_FORMAT.md:7` to "designed to be processed by the Marp CLI (not yet verified against it)".

brenno added the

docs

label

2026-07-22 16:18:10 +00:00

brenno referenced this issue from a commit

2026-07-22 17:07:09 +00:00

docs(readme): een voorpagina die in tien seconden te lezen is (#582 #590 #591 #611 #619 #620 #621 #635)

brenno referenced this issue from a commit

2026-07-22 17:07:10 +00:00

docs: noem de herkomst van MIAUW, en verlaag "conforming" (#604 #591)

brenno referenced this issue from a commit

2026-07-22 17:12:52 +00:00