From 029746a3d42c96e8a25b2ab3af32d6e94daf2c19 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Fri, 21 Nov 2025 10:25:34 -0500
Subject: [PATCH] README-emscripten: Added some initial notes about customizing
index.html.
Fixes #14485.
---
docs/README-emscripten.md | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/docs/README-emscripten.md b/docs/README-emscripten.md
index a75255fe9a8c7..71d8812aa9bff 100644
--- a/docs/README-emscripten.md
+++ b/docs/README-emscripten.md
@@ -344,6 +344,22 @@ all has to live in memory at runtime.
gives other options and details, and is worth a read.
+## Customizing index.html
+
+You don't have to use the HTML that Emscripten produces; the above examples
+use `emcc -o index.html`, but you can `-o index.js` instead to just output
+code without an HTML page, and then provide your own. This is desirable for
+shipping products, even though the Emscripten-provided HTML is fine for
+prototyping. Certain things _must_ be in the HTML file or your program will
+not function correctly (or function at all). The specifics are beyond the
+scope of this document, but it's likely best to start with the Emscripten HTML
+and customize it, instead of starting from scratch.
+
+The `<canvas>` element in the HTML _must not_ have a border or padding, or
+things will break in unexpected ways. This can be surprising when customizing
+the page's look. Plan accordingly.
+
+
## Debugging
Debugging web apps is a mixed bag. You should compile and link with