# Render a Quarto document to one self-contained HTML file

Canonical: https://githtml.com/guides/render-quarto-to-self-contained-html
Published: 2026-10-10
Publisher: WaveTech LLC / gitHtml

Set embed-resources: true under format: html in the document's YAML, then run quarto render report.qmd. Quarto inlines linked scripts, stylesheets, and images as data URIs so the report is one file instead of report.html plus a report_files folder. MathJax or KaTeX stay external unless you also set self-contained-math: true.

## Why the default output has a folder

A plain quarto render writes report.html and a sibling report_files directory with Bootstrap, scripts, and figures. That works on a website, but copying only the HTML file somewhere else leaves it unstyled and missing its images. It is the most common reason a Quarto report looks broken after someone commits just the .html.

The older self-contained option still appears in examples, but Quarto has deprecated it in favor of embed-resources, matching the Pandoc option of the same name.

## A portable configuration

Put the options in the document front matter so anyone rendering it gets the same result. A table of contents and folded code make a long analysis readable on a small screen; the code remains in the file for reviewers who want it.

````yaml
---
title: "Checkout latency review"
date: 2026-10-10
format:
  html:
    embed-resources: true
    toc: true
    toc-depth: 2
    code-fold: true
    code-summary: "Show code"
---

# Render from the project folder:
# quarto render latency-review.qmd --to html
````

## Know the remaining dependencies

Math is excluded from embedding by default because the libraries are large. Add self-contained-math: true if the report relies on equations and must work offline. Pandoc's manual also warns that resources loaded dynamically by JavaScript cannot be embedded, so anything fetched at runtime still needs a network.

Folded code, tabsets, and the floating table of contents use JavaScript. In a reader with scripts off, the content stays in the page but interactive controls may not respond. Interactive Jupyter widgets in published output run without a kernel, so check whether a chart is meaningful as a static image before relying on it.

1. Render, then move the HTML alone to an empty folder and open it there.
2. Disconnect from the network and confirm fonts, figures, and equations still appear.
3. Disable JavaScript and check that every conclusion is still visible in text.
4. Check the file size; very large embedded figures may need lower resolution.

## Commit a reading copy

Commit the .qmd source and the rendered single-file HTML together, and add the source commit or date near the title. The HTML then works as a reading artifact in a local browser and in gitHtml on iPhone or iPad without the report_files directory, while the .qmd stays the editable source of truth.

## Sources and further reading

- [Quarto: HTML publishing and embed-resources](https://quarto.org/docs/output-formats/html-publishing.html)
- [Quarto: HTML code blocks and folding](https://quarto.org/docs/output-formats/html-code.html)
- [Quarto: HTML format reference](https://quarto.org/docs/reference/formats/html.html)
- [Pandoc User's Guide](https://pandoc.org/MANUAL.html)

## Related guides

- [Embed resources in a Pandoc HTML export carefully](https://githtml.com/guides/embed-resources-in-pandoc-html-exports)
- [Convert a Jupyter notebook to a standalone HTML report](https://githtml.com/guides/convert-jupyter-notebook-to-html)
- [Use inline CSS for a dependable portable reading copy](https://githtml.com/guides/use-inline-css-for-portable-html)
- [Use Sphinx singlehtml without assuming a self-contained file](https://githtml.com/guides/use-sphinx-singlehtml-with-realistic-expectations)

Editorial approach: https://githtml.com/guides/about