Single-file vs multi-file HTML presentations: choose the right artifact

A single-file HTML presentation puts the document, styles, runtime, and required media into one upload object. A multi-file presentation keeps index.html beside local scripts, styles, fonts, and media. Prefer one file when it is genuinely self-contained and manageable; preserve a build directory when inlining would hide dependencies, inflate the document, or fight the framework.

File shape and delivery format are separate decisions. After packaging the browser artifact, use the HTML presentation vs PDF benchmark to decide whether the recipient should receive the interactive deck, a fixed document, or both. For the larger hosting decision, return to the HTML presentation hosting guide.

Decide between single-file and multi-file in one minute

Start with the output you already have, not with a preference for ZIP files or self-contained HTML. The correct unit is the finished browser artifact—not your Markdown, TypeScript, package-lock, or development server.

This decision is not “simple deck versus serious deck.” A three-slide deck can have a complex local runtime, while a framework can generate one large but self-contained file. File count is an artifact property, not a quality score.

What five verified artifacts actually produced

On August 25, 2026, we downloaded the current production index for five maintained presentation fixtures and compared its exact byte count and SHA-256 with the repository's proof contract. All five indexes matched. The corpus contains three single-file outputs and two multi-file outputs:

Download the complete machine-readable artifact record, then inspect the framework compatibility matrix for source and live-reader links.

The useful result is not that single-file outputs are smaller. They were not: the verified Quarto file is more than four times the total uncompressed size of the verified 49-file Slidev build. The result is that artifact shape and artifact size are separate decisions. Measure both.

The corpus also disproves a common shortcut: framework name alone does not determine file count. Reveal.js can run from a directory of local assets, while Quarto can embed a Reveal.js presentation into one document. The build configuration and used features decide the delivered resource graph.

What a single-file HTML presentation optimizes

A genuinely self-contained HTML file reduces packaging state. There is no archive root to place incorrectly, no sibling asset to omit, and no relative file path that can point outside the upload. It is easy to hash, download, attach to a release record, and republish as one object.

Single-file is usually the better shape when:

1. your agent or authoring tool already produces one browser-ready file;
2. all required CSS and JavaScript are inline;
3. images, fonts, and data are embedded or intentionally absent;
4. the finished file fits the selected plan's exact byte limit; and
5. you have inspected the document for secrets and required network requests.

Embedding a resource commonly uses a data: URL. MDN's data URL reference describes these as files embedded inside another document and notes practical encoding and length limits. That makes inlining a packaging tool, not a mandate to encode every video or data set into one enormous HTML line.

The HTML presentation preflight checklist separates file count, external dependencies, secrets, navigation, and hosted-reader verification so the word “single” does not hide those independent checks.

What a multi-file HTML presentation optimizes

A multi-file presentation preserves a resource graph: one root index.html plus the local runtime, styles, fonts, images, media, and generated chunks it references. This is the natural output for many static-app and framework builds.

Multi-file is usually the better shape when:

1. the official build emits a directory and its relative URLs already work under static HTTP;
2. the presentation contains large local media that would make inlining hard to inspect;
3. plugins, themes, or generated chunks are versioned as separate files;
4. your publishing plan accepts archives and the complete output fits its file and byte limits; and
5. you can preserve index.html at the archive root.

Slidev's official hosting guide says slidev build creates a static single-page application in dist and documents --base for sub-path deployment. The verified fixture uses --base ./ because the hosted reader serves assets below a versioned path. Root-based URLs such as /assets/app.js would leave that path.

Reveal.js documents a browser-only basic setup and a fuller local runtime setup in its installation guide. Its markup references dist/reveal.js, theme CSS, and optional plugins as real resources. If your deck uses that structure, package those used resources instead of describing the HTML entry point as the whole deck.

Multi-file does add release obligations: archive the contents of the build directory, keep the entry point at the root, reject parent traversal and symlinks, enforce extracted byte/file limits, and verify every browser request after upload. The failure-recovery guide includes a nested-ZIP root failure because a valid build can still be packaged incorrectly.

Compare the failure modes before choosing

For both shapes, successful upload and HTTP 200 are intermediate facts. Verify visible slides, keyboard and touch navigation, fonts, media, external links, narrow-screen behavior, and the exact sharing policy on the returned reader URL.

Choose the artifact your framework actually built

The Marp CLI source repository and Quarto's Reveal.js documentation are the authoritative owners for their build options. Recheck those owners when upgrading. A fixture that passed for one pinned version is evidence for that version and configuration, not a promise about every future plugin or export.

Package and verify either artifact shape

Use the same release sequence for both paths:

1. Freeze the build identity. Record source commit, framework version, build command, and output path.
2. Inventory the output. Record file count, total extracted bytes, entry-point bytes, and required remote requests.
3. Validate paths. Reject local-machine paths, traversal, symlinks, root-relative mistakes, and a nested archive entry point.
4. Scan the finished artifact. Check HTML, JavaScript, source maps, metadata, and media for credentials or private data.
5. Test under local HTTP. A double-clicked file: URL has different URL and security behavior from a hosted document.
6. Publish the exact inspected output. Do not rebuild between approval and upload.
7. Verify the returned reader. Use a clean session and test the smallest interaction sequence that proves the deck.
8. Record the release. Save the artifact hash, reader URL, date, known limitations, and owner.

If the chosen shape fails, repair the build configuration rather than flattening it blindly. A broken multi-file output does not prove every deck should be inlined; an oversized embedded file does not prove every deck needs a ZIP.

What this artifact corpus does not prove

The five-fixture corpus proves that the retrieved production indexes matched the maintained byte and SHA-256 records on August 25, 2026. It provides real file counts and sizes for the listed pinned versions. It does not compare load speed, caching, compression across arbitrary decks, every plugin, every media type, accessibility, access control, analytics, or business value.

We also did not rebuild or republish these fixtures during this review. The recheck read existing production assets without creating synthetic viewer or product events. Secondary asset identity and full interaction behavior remain governed by each linked framework Proof Pack.

Use the result as a packaging decision aid. Use your own build inventory and reader verification as the release gate.

Frequently asked questions

Is a single HTML file always more portable?

No. It is more portable only when every required resource is embedded or deliberately absent. A single uploaded document that requires a remote runtime, private image URL, web font, or API can still fail when that dependency changes or the reader policy blocks it.

Is a multi-file presentation always a Pro upload?

On Slidesfly, multi-file presentation artifacts use the ZIP path and the current product page owns the applicable plan and size limits. Other hosts have different packaging models. Check current pricing and limits instead of copying a number from an old article.

Should I convert a Slidev build into one file?

Not by default. Start with Slidev's official static build and the verified relative-base workflow. Convert only if you have a maintained bundling process and can prove that all used runtime, assets, fonts, and media survived without introducing new remote dependencies.

Can Reveal.js be a single file?

It can be bundled or authored with inline resources, but the standard local setup commonly uses separate CSS, runtime, theme, and plugin files. Choose from the resource graph of your finished deck, not from what is theoretically possible.

Do data URLs eliminate every asset problem?

No. They embed bytes into another document, but encoding size, browser limits, content policy, maintainability, and the original asset's licensing or privacy still matter. They also do not inline an API response that must exist at viewing time.

What should I send to an agent that will publish the deck?

Send the exact final artifact, its type (single-file or root-level ZIP), expected entry point, byte/file limits, required interaction check, intended visibility, and a stop rule for unexpected remote requests or secret findings. Do not send only the source directory and ask the publishing agent to guess which files belong in production.

Continue with the Quickstart or browse all HTML presentation publishing guides.