Turn a prompt into a native, editable slide deck.
A Nextcloud AppAPI ExApp: pptx, html or pdf authored from plain language.
Naming note: the product is called SlidePrepper; the Python package and this repository still carry the historical name
marp_slidesbecause the rendering engine is Marp and the internal module names predate the product rename.
Slide generation inside Nextcloud today means either a Collabora round trip that converts a document you already wrote into slides, or filling JSON into a template with a fixed layout. Neither takes "explain X to audience Y" and hands back a finished deck.
Language models can write slides, but two things break when you bolt one onto an office suite. Raw model output needs validation before it becomes a deliverable, and the easy rendering path, rasterizing slides to images, produces decks nobody can edit afterwards.
SlidePrepper takes a plain prompt, has the instance's own text provider author strict Marp Markdown, validates it against an explicit construct allow-list, and rebuilds it as native PowerPoint content: real text boxes, list paragraphs, tables, hyperlinks, speaker notes. Or it renders a standalone HTML presentation or a PDF. The pptx opens editable in PowerPoint, OnlyOffice and Collabora. Anything the model writes that cannot map to native content is rejected with a message that says what to do instead; nothing degrades silently.
You need Nextcloud 33 to 35 with the AppAPI app, a configured core:text2text provider (this app schedules the instance's own provider, it never calls a model API), and the AppAPI docker deploy daemon.
git clone https://github.com/WSHAPER/marp_slides.git
cd marp_slides
docker build -t slideprepper:0.1.1 .Register the app on your instance, manually with occ or through whatever deployment automation already manages your AppAPI apps:
occ app_api:app:register slideprepper \
--json-info "$(cat appinfo/info.xml | jq -Rs '{info: .}')" \
--force-scopes --wait-finishThen ask for a deck from the Assistant or any chat tool that schedules TaskProcessing work; the download link comes back when the task reports.
Editing a generated deck in place needs an office integration. Where Collabora's viewer app is present, the pptx opens and edits there; git-based Nextcloud 35 no longer ships that app, so office files do not open in-app until the platform's viewer migration lands on the Nextcloud 36 line. Pinning the viewer app at v35.0.2 restores it in the meantime (nextcloud/richdocuments#6218). The deck itself is unaffected: the download opens and edits in PowerPoint, OnlyOffice or desktop LibreOffice, and the html and pdf outputs need no office integration at all.
The operational knobs are admin-manageable at runtime. AppAPI renders them as a declarative settings form (Settings -> Administration -> ExApps Settings -> "SlidePrepper"); a saved value is stored server-side and read by the ExApp per claimed task. The same keys are settable with occ:
# create (first time) or update (add --update-only) a server-side value
occ app_api:app:config:set slideprepper SLIDEPREPPER_MAX_SLIDES --value 40
occ app_api:app:config:set slideprepper SLIDEPREPPER_MAX_SLIDES --value 30 --update-only
occ app_api:app:config:delete slideprepper SLIDEPREPPER_MAX_SLIDES # back to env/defaultPrecedence, highest first: admin value (declarative form or occ) > environment variable (deploy-time) > built-in default. The environment stays a fully working fallback: until an admin saves a value, behavior is exactly the env-driven behavior. An empty admin field means unset, and an invalid admin value fails soft to the env value (the ExApp log carries a warning naming the knob and the bad value). The form displays the built-in defaults as placeholders; it cannot see the container environment, so an env override still in force may differ from what the form shows.
Refresh semantics: the worker reads the admin values once per claimed task behind a 30-second cache (ADMIN_CONFIG_REFRESH_TTL_S). A change saved at time T applies to tasks claimed from T+30 s at the latest; a task already running keeps the settings it started with.
Two Nextcloud declarative-settings quirks shape the form (both verified live against Nextcloud 35 + AppAPI 35 and pinned by tests): the settings UI submits the form id with the app prefix stripped, so the form is registered as operational_settings (an id containing marp_slides_ would make every UI save a silent no-op, returned as success but stored nowhere); and boolean knobs render as Yes/No radios rather than checkboxes, because an unchecked checkbox saves JSON false, which AppAPI stores as an empty string, and an empty value means "keep the environment value" here. Saving through occ stores any of the accepted spellings directly.
| Knob (admin key = env var) | Built-in default | Applies to |
|---|---|---|
SLIDEPREPPER_TOTAL_LLM_TIMEOUT |
1800 s | total time budget of both inner LLM attempts |
SLIDEPREPPER_MAX_SLIDES |
60 | upper slide bound per deck (per-task requests can only lower it) |
SLIDEPREPPER_MAX_PROMPT_CHARS |
8192 | prompts longer than this are rejected before any LLM round |
SLIDEPREPPER_DRAFTS_FOLDER |
empty | Files folder receiving draft .md copies (empty keeps drafts on the ExApp volume) |
SLIDEPREPPER_RETRY_LLM |
true | one self-correcting retry of failed LLM rounds |
SLIDEPREPPER_OVERFLOW_CHECK |
true | per-slide overflow measurement and deck-level gate |
SLIDEPREPPER_LOG_EXCERPT |
true | 240-char deck-failure markdown excerpt in the log |
SLIDEPREPPER_DRAFTS_ENABLED |
true | keep draft checkpoints for resumable generation |
SLIDEPREPPER_DESIGN_TOKENS_PATH |
SlidePrepper/design-tokens.json |
owner-relative path of the design tokens JSON that re-brands the nextcloud theme (branded-theme html/pdf decks only; missing file: instance theming; -/off: disabled instance-wide; see Design tokens) |
SLIDEPREPPER_CUSTOM_THEME_PATH |
SlidePrepper/custom-theme.css |
owner-relative path of the custom Marp theme CSS applied when a task asks for the custom theme (validated against a probe deck before use; missing file: custom behaves like default; -/off: disabled instance-wide; see Custom theme) |
Not admin-manageable (environment only, when relevant): APP_SECRET, APP_ID, APP_PORT, APP_HOST and NEXTCLOUD_URL (AppAPI wiring and bind surface, read by nc_py_api itself), SLIDEPREPPER_MARP_BIN and SLIDEPREPPER_POLL_INTERVAL (container- and daemon-coupled), and the internal per-round caps SLIDEPREPPER_LLM_TIMEOUT, SLIDEPREPPER_MARP_TIMEOUT and SLIDEPREPPER_MAX_DECK_BYTES (their admin-facing tuning axes are the surfaced total cap and slide count). The rule: a knob is surfaced when an instance admin plausibly tunes it at runtime; secrets, infra-coupled values and pipeline internals stay with the deployment. There is no LLM API key or endpoint to configure: the app schedules the instance's own core:text2text provider.
Auditing: changes made with occ are centrally audit-logged by the admin_audit app whenever it is enabled (it records every console command with its arguments). Form saves are not covered by admin_audit; they appear in nextcloud.log as standard request lines (user and URL, no payload).
The task type takes a required text prompt, an optional output_format enum (pptx default, html, pdf), an optional theme enum (nextcloud default — the branded theme; auto to let the model pick, or one of the three themes bundled with Marp: default, gaia, uncover), and an optional images list of Nextcloud file ids the server access-checks for the requesting user. It returns the generated deck as a file plus the retained Marp Markdown source. The canonical shape lives in marp_slides/task_definition.py.
output_format is a real ENUM shape with three registered values plus a default of pptx, and it is validated again inside the provider. So is theme: auto lets the model pick the best-fitting theme; any other value is a hard requirement the authoring prompt states and the validator enforces against the deck's frontmatter theme.
A failed (or resumed) generation keeps its completed slides checkpointed as a draft; the failed task's message names its draft_id, and re-running with that id regenerates only the missing slides. When SLIDEPREPPER_DRAFTS_FOLDER is set (for example SlidePrepper drafts), the draft's current state is also copied into a per-deck subdirectory of that folder of the requesting user's Files as <deck-stem>/<deck-stem>.draft.md: a comment naming the draft id leads the file, followed by the deck frontmatter and the completed slides. The copy is fail-soft (delivery problems are logged, never task failures), the newest draft of a stem overwrites older ones (Nextcloud keeps the versions), and the file carries the visible "Generated using AI" system tag when the tagging API is reachable. Successful deliveries follow the same per-deck layout: every generated format of a deck plus its Markdown source lands in its own SlidePrepper/<deck-stem>/ subdirectory instead of pooling one flat folder.
SUPPORTED_CONSTRUCTS in marp_slides/constructs.py is the single source of truth: the deck-authoring prompt (sourced from marp_slides/prompts/ at runtime) is rendered from the constant and the validator rejects anything the builder cannot map, so the two can never disagree.
- one
#or##heading per slide as its title, with rich inline runs rendered in the title placeholder ###and deeper headings inside a slide become bold sub-section text at stepped sizes- plain paragraphs, unordered and ordered lists (nested by 2-space indent, ordered lists honor their start number)
- inline
**bold**,*italic*and`code`as native run properties - inline, autolink and reference-style http(s) links as native text-run hyperlinks; URLs are validated, not just parsed, and only full
http://orhttps://passes - fenced code blocks as bordered monospace boxes with deterministic wrapping and a shrink-to-fit font ladder (11 to 8 pt); a block too large for one slide is rejected with a split-it hint
- blockquotes as indented italic paragraphs
- pipe tables with rich cell content (links, bold, code)
- speaker notes from
<!-- ... -->comments on their own lines, as native editable notes slides - deck-level
<!-- footer: ... -->and<!-- header: ... -->chrome on every slide, with per-slide_footerand_headeroverrides paginate: trueas real slide-number fields, deck-wide and per-slide solid background colors, two-column slides via<!-- columns: 2 -->plus<!-- column-break -->#file:Nimage references resolved against the task'simagesinput, downloaded with sniffed type and size caps (PNG or JPEG, 5 MB)- YAML frontmatter with exactly:
marp: true(the literal scalar, YAML 1.1 spellings likeyesreject on purpose),title(a string),theme(one of the three bundled Marp themes), optionalpaginateandbackgroundColor
Anything outside the list is rejected at validation time with an error that tells the model what to do instead: raw HTML, remote image URLs, math equations ($...$ and $$...$$ LaTeX; the message says to write the formula as plain text), strikethrough, underscore emphasis, footnotes, link schemes outside http/https, control characters in URLs, ragged tables, tables on column slides, oversized code blocks, unknown frontmatter keys, stray --- separators. There is no image fallback and no render-mode knob.
flowchart TD
P["user prompt"] --> A["Assistant UI or chat tool"]
A --> S["TaskProcessing schedule"]
S --> W["ExApp worker"]
W --> L["inner LLM: core:text2text"]
L --> V["strict Markdown validation"]
V -. "self-correcting retry" .-> L
V --> G["marp CLI syntax gate"]
G --> B["native PPTX build: python-pptx"]
G --> R["html or pdf render: marp CLI"]
B --> U["upload_result_file"]
R --> U
U --> D["download link"]
- The worker is a background thread polling
next_taskevery 5 s, woken immediately by AppAPI/triggerevents. Chromium is involved in exactly one path: onlyoutput_format=pdfrenders through the bundled browser; the syntax gate, the PPTX build and the HTML render are browserless. - When the inner LLM output fails extraction or validation, one self-correcting retry is scheduled with the validation error appended as feedback; gate, build and prompt failures are never retried. Progress reports at four phases (5% author, 50% validate, 80% build, 100% done) and both attempts share one total-time cap (
SLIDEPREPPER_TOTAL_LLM_TIMEOUT, default 1800 s, admin-adjustable; see Configuration). - Visual parity with a browser render is not a goal; nativeness and editability are.
- Every failure path ends in
report_resultwith an actionableuser_facing_error_message: invalid Markdown errors embed the parser output, inner LLM failures surface the nested task's error text, image-cap violations name the file id, the cap and the remedy.
The codebase is small enough to read top-down.
pptx (default) is rebuilt as native content with python-pptx on 16:9 title and Title+Content layouts: headings become title placeholders, body placeholders carry paragraphs, lists and quotes, code fences and tables become sequential native shapes, column slides become two side-by-side text boxes.
html is rendered by marp CLI as one standalone file: theme CSS and the viewer JavaScript are inlined, with no external stylesheet or script assets. Speaker notes stay inside as hidden elements and are available in the bundled presenter view. No browser is needed or spawned; the conversion is Node-only. Task #file:N images are materialized into the throwaway render workdir and embedded, with marp's local-files read enabled for that workdir only (it holds nothing but the app's own validated files).
pdf is the one format that uses the Chromium bundled in the base image, driven by marp CLI through puppeteer-core. The browserless syntax gate runs first, so malformed Markdown fails fast and only a validated deck reaches the slower browser render. Speaker notes are not part of marp's default PDF output (the retained Markdown source carries them); hyperlinks survive as clickable annotations. Task images are materialized into the render workdir exactly as for html.
ODP is deliberately not offered: neither the native builder nor marp CLI can emit it. If ODF output ever becomes a requirement, the path is PPTX to ODP conversion via Collabora.
The optional theme input styles the html and pdf outputs: nextcloud (the default) is the branded theme — this instance's theming, or the task owner's design tokens file when one exists — while auto has the model pick the best-fitting theme and any other value is a fixed requirement; the pptx build ignores the theme, since native decks carry no Marp theme. When the effective theme is nextcloud, a design tokens file in the owner's Files re-brands it (see Design tokens). custom applies the owner's own Marp theme CSS after it passes a geometry gate (see Custom theme); auto never picks it.
Every task also uploads the final validated Marp Markdown as <deckname>.md next to the deck, so a later turn can refeed the original prompt plus this source for small edits instead of a full recompute.
A user (or an organization) can re-brand the nextcloud theme for their own decks without touching the instance theming: a small JSON file in the task owner's Files, at SlidePrepper/design-tokens.json by default. The knob SLIDEPREPPER_DESIGN_TOKENS_PATH (relative to the owner's Files root) can point somewhere else — for example at a group folder mounted at the same path for every user; note it is resolved per task owner, so a "shared" location only works when every user sees that folder at the same relative path in their own Files. The v1 schema is deliberately shallow — two colors, a scrim opacity and one font family, exactly the branding the generated theme CSS parameterizes:
{
"color": "#3a1b5d",
"color_text": "#f5f0e8",
"font_family": "IBM Plex Sans"
}- Every key is optional; an absent
colorkeeps the stock Nextcloud blue and an absentfont_familythe bundled Inter. An absentcolor_textis derived from the color's luminance (dark text on light brand colors, white on dark), the same derivation the instance theming applies —{"color": "#f5f5f5"}alone produces dark-on-light, not white-on-near-white. No absent key ever pulls in the instance theming: the file replaces instance-derived branding, including the slogan and name, which are cleared rather than mixed in. The instance background image survives the tokens: the scrim is solved from the token color and its text pairing, so org branding composes with the instance's imagery (a plain-color admin background is itself a color choice, so it is replaced by the flat token color). An explicit pair below the WCAG large-text contrast floor (3:1) is honored but logs a warning naming the file and the measured contrast: no gate catches readability, so the choice at least stays visible. scrim_opacity(optional) is a number between0.0and1.0that overrides the auto-computed scrim alpha over a background image. The auto solve picks the weakest alpha in a 0.55–0.75 window that keeps the text readable over a worst-case (pure white or pure black) image; an explicit value takes full control — even outside that window — and is checked the same soft way: a chosen opacity under the 3:1 floor is honored with one warning in the ExApp log. Without a background image the knob does nothing. The value must be a JSON number (not a string or boolean) inside the range; anything else is a file error and the whole file is ignored, like any schema violation.- Colors are
#RRGGBB(or#RGB) strings;font_familyis a font family name (letters, digits, spaces and common name punctuation; the double quote", backslash\, backtick`,<,>,{,}and;characters and all control characters are rejected at parse time, so a tokens file can smuggle neither CSS nor HTML — apostrophes inside names likeBoss's Neware fine). - Unknown keys are a file error: strict validation means a typo'd key cannot silently do nothing.
- When the file exists and parses, its values apply instead of the server's theming capabilities whenever the effective theme is
nextcloud(picked explicitly or viaauto), on every surface that resolves that theme: the generation task, the chat tool's schedule of it, and the re-render task. The theme is still produced by the same generator with the same scrim/contrast handling; only the branding values differ. - Fail-soft by contract: a missing file is exactly the instance-theming behavior plus one debug log line; a malformed file (not JSON, unknown keys, invalid values, over 64 KiB) is ignored the same way with one warning naming the file and the reason. Neither ever fails a task. There are two off switches: the owner deletes (or renames) their file, and the admin sets the knob to
-oroffto disable token discovery instance-wide (no DAV call at all). Either applies to the next task; within a task the values are resolved once. - The font resolves by family name through CSS with the bundled Inter as the fallback: no font file is fetched in v1, so a font the render environment does not have installed silently falls through to Inter (install the font on the machines that render/view, or keep to widely available families).
- Geometry is never steerable: tokens change colors and the font family only; sizes, spacing and padding stay fixed in the template, so the overflow guarantee survives custom branding. A wide token font can still change text metrics — that is fine, because the per-slide overflow gates measure the actually rendered deck: a token font that overflows fails loudly at the gate exactly like an over-packed prompt would.
- The pptx output ignores the theme by design (python-pptx has no theme surface), so tokens affect html and pdf decks only.
Power users can bring their own Marp theme: a CSS file in the task owner's Files, at SlidePrepper/custom-theme.css by default (knob SLIDEPREPPER_CUSTOM_THEME_PATH, resolved per task owner like the tokens path). It applies when a task's theme input is custom; it is never picked by auto and never touches other themes. Unlike design tokens, a custom theme can change geometry, so it has to earn its place first:
- Geometry gate. Before the theme is used, a fixed, dense probe deck (single-line bullets at the teaching limit, a nested list under a subheading, a code block, a full-width table, long inline-code runs with a blockquote, and a slide of running prose) is rendered under it by marp and measured in headless Chromium with the same script and pixel budgets as the overflow gates. If any probe slide overflows by more than one rendered line (on either axis), the theme is rejected: it is never applied, the deck is generated under the
defaulttheme instead, and a warning in the ExApp log names each probe slide, the content pattern it exercises, the overflow in pixels and lines, and the first overflowing element. The probe is calibrated on the default theme (every slide fits at 0.78–0.96 of the safe area), and custom-theme decks are authored with the default theme's density teaching, so "passes the probe" means "fits what the model will write". The gate is deterministic: no LLM is involved. - Cost and caching. One gate run is one marp render plus one Chromium pass over six slides, about 0.7 s in the container image. The verdict is cached in memory by the file's SHA-256, so an unchanged theme is never re-validated, and any edit is. The gate runs before the first LLM round, so the model is asked for the theme the deck will actually ship with.
- Static lint first. The CSS is rendered server-side, so anything that could make the container fetch is refused before rendering:
url(...)must be adata:URI,@importmay only name a bundled theme (@import "default";), andimage-set()is not allowed. CSS escapes cannot get around this, because the checks run on a decoded copy.</styleis refused because the theme is embedded in a<style>element of the html deliverable. The file is capped at 1 MiB (it rides inside every html deck). - Theme name. Whatever
@themename the file declares is rewritten tocustom(one is added if missing), so start from@import "default";and override what you need. - Fallbacks. A theme file never fails a task. No file (or the knob set to
-/off), a file rejected by the lint or the probe gate, or a gate that cannot run at all (no headless Chromium):custombehaves likedefault, with one warning saying why. An unvalidated theme is never used. The file is read once per task, so editing or deleting it mid-task cannot split a deck between two themes. - The pptx output ignores the theme, as for every theme.
- The allow-list is the boundary. The deck-authoring prompt is generated from
SUPPORTED_CONSTRUCTSand the validator rejects anything outside it, so prompt and validator cannot drift. Raw HTML never reaches a render: the deck validator rejects it and marp additionally runs withhtmlandlooseYAMLoff. There is no fallback mode that quietly downgrades content. - Images enter only as Nextcloud file ids in the
imagesslot: the server authenticates the requesting user's access to every id before the task reaches the ExApp, and downloads go over the app-context API with sniffed type and size caps. Remote image URLs are rejected on purpose; fetching them would need its own egress design (redirects, private-IP ranges, DNS rebinding, content caps). - A custom theme file is user-supplied CSS rendered by the container's marp and Chromium, so it is linted before any render: no external
url(), no@importbeyond bundled theme names, noimage-set(), and no</style(see Custom theme). - marp's default emoji handling swaps every emoji for
cdn.jsdelivr.netimage references, fetched at render time or by the viewer's browser. The strict.marprcused for all conversions disables the conversion, so emoji stay local-font text and no render touches a CDN. - Run
https://forNEXTCLOUD_URL(the shared-secret header travels on every ExApp to server call), bindAPP_HOSTto the specific interface Nextcloud reaches instead of0.0.0.0on shared machines, firewall 9090 to that interface plus localhost, and egress-restrict the container toNEXTCLOUD_URL. - Deck-failure logs carry a 240-character excerpt of the generated Markdown only, never the user prompt;
SLIDEPREPPER_LOG_EXCERPT=falsesuppresses the excerpt while the error line always logs.
python3 -m venv .venv
.venv/bin/pip install -r requirements_dev.txt
.venv/bin/pre-commit install # same gates, client-side
scripts/check.sh # all quality gates + the full test suite
.venv/bin/pytest -q # tests alone: fakes only, no Nextcloud, no dockerThe default suite is hermetic (fakes only). Two opt-in lanes exist as registered pytest markers: pytest -m battery needs the real marp toolchain (marp-cli on PATH — locally npm install @marp-team/marp-cli@4.5.1 to match the Dockerfile base image — plus a headless Chromium pointed at by CHROME_PATH), and pytest -m nightly is the slow lane (mutation, LibreOffice smoke). CI runs both lanes on their own schedules (see below). Both lanes are empty until their first tests land; pytest exits with code 5 ("no tests collected") and the CI jobs treat that as green.
scripts/check.sh runs the full static gate suite (plus the tests) and stops
at the first failure; .pre-commit-config.yaml runs the same core gates on
every commit. What runs, and why it is in the suite:
Each gate exists because it caught real issues in this codebase. See scripts/check.sh and pyproject.toml for the configuration.
Continuous integration (.github/workflows/ci.yml) runs five jobs. On every push to main and every pull request:
- gates —
scripts/check.shverbatim on the pinnedrequirements_dev.txttoolchain, the same suite as the local and pre-commit runs. - coverage — the hermetic suite under
pytest --cov=marp_slides, then a changed-lines ratchet:diff-cover coverage.xml --compare-branch=origin/main --fail-under=100. Only lines a change actually touches must be covered, so the existing suite is grandfathered and new code cannot land below full changed-line coverage. - pip-audit — the network job the offline suite defers to (see below): it audits the runtime pins in
requirements.txt, resolving the full dependency tree exactly the way the Docker build installs it, with--strictso a dependency that cannot be collected fails the audit instead of being silently skipped.
On their own schedules:
- battery (weekly Mondays 03:23 UTC, plus manual
workflow_dispatch) — provisions the battery lane contract — python,@marp-team/marp-cli@4.5.1pinned to match the Dockerfile base image, and a headless Chromium — and runspytest -m battery. No docker. - nightly (daily 03:17 UTC) — runs
pytest -m nightly, the slow lane. Its provisioning grows as mutation and LibreOffice jobs land.
Documented exemptions, each inline in the code with a reason: process_task
carries the only complexity/size noqas (the 5%/50%/80% pipeline phases read
best sequentially) — everything else in marp_slides/ is at or under every
ceiling. Known non-goals: per-function nesting depth and module size are not
directly gated (branch count and complexity are the proxies), and dead
functions rely on review, not vulture.
Not standalone tools on purpose: pylint (fully covered by ruff + mypy at a
fraction of the noise), radon (ruff's C901 is the same cyclomatic check),
bandit (ruff's S rules cover it; the marp subprocess calls go through an
injected argv-list runner with no shell=True anywhere), and pip-audit
(dependency CVEs are a different, network-dependent job — the dedicated
pip-audit CI job audits the runtime pins in requirements.txt, outside the
offline gate suite).
Real-code probe against the built image:
docker build -t slideprepper:dev .
docker run --rm -v "$PWD/fixtures:/w" -e PYTHONPATH=/app --entrypoint python3 slideprepper:dev /w/probe.pyRender audit (build a fixture, convert with Collabora or host LibreOffice, verify code-text survival, slide bounds and monospace fonts via pdftotext):
.venv/bin/python scripts/lo_render_check.py fixtures/deck-code-audit.mdStandalone boot for debugging (the heartbeat serves even without a reachable Nextcloud; the worker retries):
NEXTCLOUD_URL=https://cloud.example.com APP_ID=slideprepper APP_VERSION=0.1.1 \
APP_SECRET=... AA_VERSION=2.2.0 APP_PORT=9090 .venv/bin/python main.pyAll knobs (poll interval, marp timeout, LLM timeouts, caps, retry, log excerpt, marp binary) are optional with defaults in marp_slides/settings.py.
Known limits: two columns maximum and no tables inside columns, code blocks capped at roughly 36 rendered lines, no math/equation support (LaTeX $...$ and $$...$$ in slide text is rejected with a write-it-as-plain-text hint; Collabora's formula editing only works in ODF, so OMML equations in PPTX degrade through the round trip — revisit when the platform supports them better; $...$ pairs on one line of slide text follow the Pandoc flanking rule (tex_math_dollars): a pair is math syntax only when the opening $ has non-space immediately to its right, the closing $ non-space to its left and no digit immediately after it — ordinary currency prose (a lone $, $5 and $10, $1,200 – $2,200, $200k–$500k) stays literal, while tight spans like $1-2$ still reject; $ in separate table cells, link URLs, code, speaker notes and the frontmatter title stays literal; a literal $$ in a text line rejects even inside inline code or a link URL, exactly as before the removal), default template only, horizontal scale means more containers.
Releases satisfy the Cyber Resilience Act's "every release ships a machine-readable SBOM" requirement: dependencies are locked with hashes, each vX.Y.Z tag produces a GitHub release carrying a CycloneDX SBOM generated from that lock, and versions are unique per release (never re-tag, never reuse a version).
Dependency lock. requirements.txt stays the direct-dependency manifest; requirements.lock is the committed full transitive closure with per-artifact sha256 hashes, generated by the pinned uv (in requirements_dev.txt):
.venv/bin/uv pip compile requirements.txt --generate-hashes \
--python-platform linux --python-version 3.11 --output-file requirements.lockThe Dockerfile installs from the lock with pip install --require-hashes (every wheel is hash-verified), the CI pip-audit job audits the lock (the whole closure, not just direct pins), and tests/test_requirements_lock.py fails if the lock drifts from the manifest or loses its hashes.
Cutting a release.
- Bump the version triple —
APP_VERSIONinmarp_slides/settings.py,<version>and the docker<image-tag>inappinfo/info.xml— the three are pinned together bytests/test_versions.py. If dependencies changed, regeneraterequirements.lock(above) in the same commit. - Tag
vX.Y.Zand push the tag..github/workflows/release.ymlthen:- fails unless the tag equals
APP_VERSIONinappinfo/info.xml; - fails if a GitHub release for that tag already exists (no re-releasing);
- builds the docker image
slideprepper:X.Y.Z(not pushed — see below); - generates
sbom.cyclonedx.jsonfromrequirements.lockwithcyclonedx-py(pinned in the job), adds the app itself as the root component (name and version fromAPP_VERSION), and checksums it; - creates the GitHub release with the SBOM, its
.sha256, andimage-digests.txt(digests of the built image and its pinned base).
- fails unless the tag equals
- Publishing the image to the registry
appinfo/info.xmladvertises (docker.io) is a deliberate manual step, run after reviewing the release's artifacts:docker tag/docker pushof the built image, thendocker manifest inspectto confirm the pushed digest matchesimage-digests.txt.
The SBOM is a per-release artifact attached to the GitHub release, not a committed file — it is regenerated deterministically from the committed lock (--output-reproducible, timestamp from the tagged commit), so the release asset always describes exactly the dependency set the tagged image installs.
This repo runs its own release pipeline rather than nextcloud's central automation: the org templates (appstore-build-publish.yml, docker-build-publish.yml in nextcloud/.github) only run under the nextcloud-releases owner with org secrets, and package PHP-app tarballs for the appstore. A third-party ExApp like this one builds its own; appstore publication (via nextcloud-libraries/nextcloud-appstore-push-action, which needs a registered app certificate) remains a possible future addition.
AGPL-3.0, see LICENSE. appinfo/info.xml declares agpl accordingly.