From 44ccece2878c1f6cbd5deaaadbaef6e18691e806 Mon Sep 17 00:00:00 2001 From: Charly Abraham Date: Fri, 20 Nov 2026 07:53:58 +0530 Subject: [PATCH] docs: add HTML preview troubleshooting guide --- .../index.md | 323 ++++++++++++++++++ .../02-quick-start-project.md | 2 + scripts/tutorial-media-manifest.json | 82 ++++- scripts/verify-tutorials.cjs | 7 +- src/components/Video/HtmlPreviewVideo.js | 7 + src/css/html-preview-guide.css | 29 ++ src/data/html-preview-videos.json | 50 +++ .../videos/html-viewer-hosted-resources.js | 7 + .../videos/html-viewer-inline-javascript.js | 7 + .../html-preview-hosted-resources-poster.png | Bin 0 -> 222816 bytes .../media/html-preview-hosted-resources.mp4 | Bin 0 -> 182405 bytes .../media/html-preview-hosted-resources.vtt | 10 + .../media/html-preview-hosted-result.png | Bin 0 -> 246810 bytes .../html-preview-inline-javascript-poster.png | Bin 0 -> 106563 bytes .../media/html-preview-inline-javascript.mp4 | Bin 0 -> 185867 bytes .../media/html-preview-inline-javascript.vtt | 16 + .../media/html-preview-inline-result.png | Bin 0 -> 86451 bytes .../media/html-preview-mobile-settings.png | Bin 0 -> 15991 bytes 18 files changed, 537 insertions(+), 3 deletions(-) create mode 100644 blog/2026-11-19-html-preview-missing-assets/index.md create mode 100644 src/components/Video/HtmlPreviewVideo.js create mode 100644 src/css/html-preview-guide.css create mode 100644 src/data/html-preview-videos.json create mode 100644 src/pages/videos/html-viewer-hosted-resources.js create mode 100644 src/pages/videos/html-viewer-inline-javascript.js create mode 100644 static/tutorials/media/html-preview-hosted-resources-poster.png create mode 100644 static/tutorials/media/html-preview-hosted-resources.mp4 create mode 100644 static/tutorials/media/html-preview-hosted-resources.vtt create mode 100644 static/tutorials/media/html-preview-hosted-result.png create mode 100644 static/tutorials/media/html-preview-inline-javascript-poster.png create mode 100644 static/tutorials/media/html-preview-inline-javascript.mp4 create mode 100644 static/tutorials/media/html-preview-inline-javascript.vtt create mode 100644 static/tutorials/media/html-preview-inline-result.png create mode 100644 static/tutorials/media/html-preview-mobile-settings.png diff --git a/blog/2026-11-19-html-preview-missing-assets/index.md b/blog/2026-11-19-html-preview-missing-assets/index.md new file mode 100644 index 000000000..c4b00bd78 --- /dev/null +++ b/blog/2026-11-19-html-preview-missing-assets/index.md @@ -0,0 +1,323 @@ +--- +slug: html-preview-missing-css-images-javascript +title: "Why Your HTML Preview Is Missing CSS, Images or JavaScript" +description: "Fix CSS not loading, missing images and JavaScript that won't run in an HTML preview. Check file paths and permissions with working examples." +image: /tutorials/media/html-preview-hosted-result.png +date: 2026-11-19 +authors: [charly] +tags: [Tools, HTML, CSS, JavaScript] +--- + +import TutorialIcon from '@site/src/components/TutorialIcon'; +import HtmlPreviewVideo from '@site/src/components/Video/HtmlPreviewVideo'; +import '@site/src/css/html-preview-guide.css'; + +An HTML file can link to CSS, images, and JavaScript without copying those files +into it. If a preview is missing styles or images, first check the file paths and +the preview permissions. If a button does nothing, check whether scripts are allowed. +This guide also helps when CSS is not loading, HTML images are not showing, or +JavaScript is not working in HTML. + +The examples below use [Phoenix HTML Viewer](https://phcode.dev/tools/html-viewer.html). +HTML and CSS written inside the document work by default. Hosted files and +JavaScript each need permission in the Viewer. The Viewer reads the HTML file you open; +it does not import the files beside it. + + + +**You will need:** your HTML text or an `.html` file. The Viewer is free and runs +in your browser. For the last steps, keep any separate CSS, JavaScript, and image +files with your HTML. You can use file editing and Live Preview. These features +are in both Phoenix Pro and the free Community edition. + +## Identify what is missing + +| What you see | First check | Next step | +|---|---|---| +| Hosted CSS is not loading | Is external access enabled? | For trusted content, turn on **Allow external resources**. Then [try the hosted example](#distinguish-hosted-addresses-from-relative-paths). | +| A local `styles.css` file is not loading | Did you open only the HTML file? | [Open the full project folder](#open-the-complete-project-in-phoenix-code) in Phoenix Code. | +| An image is not showing | Is its address a hosted URL or a local path? | [Check the path and filename](#keep-local-files-in-the-expected-folders). | +| A hosted file still does not load | What URL did the browser request? | [Check the failed request](#check-a-failed-resource). | +| A button does nothing | Is JavaScript allowed? | [Test a small inline script](#check-a-small-javascript-interaction) before you debug a bigger one. | + +If the stylesheet loads but the page still looks wrong, check whether the CSS +rule targets the right element or another rule overrides it. + +## Test HTML and inline CSS {#check-a-self-contained-html-example} + +1. Open the [HTML Viewer](https://phcode.dev/tools/html-viewer.html). +2. Click inside **HTML source** and paste the complete document below, replacing + any sample text already there. It needs no downloaded stylesheet, image, or + JavaScript. + +```html + + + + + + Preview check + + + +

HTML and inline CSS are working.

+ + +``` + +3. Look at the **Rendered preview** panel. On a narrow screen, switch from **Source** to + **Preview** to see the result. + +You should see a blue paragraph on a pale background. + +
+ + HTML Viewer showing the example's blue paragraph on a pale background, with Allow external resources unchecked. + +
The complete example works with external resources off. Select the image to inspect the source and preview it at full size.
+
+ +If this works, add parts of your original page a little at a time: HTML first, +then styles, images, and scripts. When the preview breaks, check the last part +you added. + +To check your own file, choose **Open .html file** above the source editor. This +replaces the current source. To keep your edits, use **Download .html** in the +source toolbar first. On desktop, this is the download-arrow button with that tooltip. + +If changes stop appearing, check whether **Live preview** is on. Its checkbox +and **Allow external resources** are above the editor on a wide screen. On a +narrow screen, open **Preview settings** below the workspace. When **Live +preview** is off, use **Refresh preview** after you edit. + +
+ + Expanded mobile Preview settings showing Live preview and Allow external resources checked, with Run scripts unchecked. + +
On mobile, open Preview settings. There, external resources are on and scripts stay off.
+
+ +## Keep local files in the expected folders + +For a working example, download the [image-and-text practice project](/tutorials/image-text-layout.zip) +used in our [image layout tutorial](/docs/tutorials/image-text-layout). Extract the +ZIP first. Keep these files together in the extracted folder: + +```text +image-text-layout/ +├── index.html +├── styles.css +└── images/ + └── woodland.jpg +``` + +Inside `index.html`, a stylesheet reference belongs in the `head`: + +```html + +``` + +An image reference belongs where the image should appear in the body: + +```html +A sunlit path between tall trees +``` + +The first path expects `styles.css` beside the HTML file. The second expects +`woodland.jpg` inside an `images` folder. Check that the +filenames and case match the files you have. For your own project, +use your image's filename, dimensions, and description. + +Opening only `index.html` in the Viewer leaves those files behind. +**Allow external resources** cannot give the Viewer access to other files on +your computer. Keep the files together and use +the [full-project workflow below](#open-the-complete-project-in-phoenix-code). + +## Check hosted URLs and relative paths {#distinguish-hosted-addresses-from-relative-paths} + +A full URL such as `https://example.com/images/logo.png` points to a file on a +website. This is an example URL; replace it with your own image URL when testing. +Hosted images, stylesheets, and fonts need **Allow external resources** in the Viewer. + +To see the difference, replace the Viewer source with this complete example. +It loads the same practice stylesheet and woodland photo from the docs website: + +```html + + + + + + Hosted resource check + + + +

A woodland walk

+
+ A sunlit path between tall trees +
+ + +``` + +1. With **Allow external resources** off, the heading is unstyled and the photo + does not load. +2. Turn on **Allow external resources** for this example. You should see a dark + green heading, a pale background, and the woodland photo. Leave scripts off; + this example needs only HTML, CSS, and an image. + +
+ +
Someone has already pasted the example into the Viewer. The recording shows that external access is off, someone turned on the setting, and the hosted files are loading.
+
+ +The photo is by [Johannes Plenio on Unsplash](https://unsplash.com/photos/pathway-of-trees-during-daytime-P1Iz3unD6Po), +as credited in the practice project. This example uses complete hosted addresses; +it does not access files on your computer. + +A relative path starts from another location. For paths in your HTML: + +- `styles.css` and `./styles.css` resolve from the current directory. +- `../styles.css` resolves from the parent directory. +- The server resolves `/styles.css` from the site root when it serves the page + over HTTP or HTTPS. + +A relative path does not mean 'find this file anywhere on my computer.' +[MDN explains how relative references are resolved](https://developer.mozilla.org/en-US/docs/Web/API/URL_API/Resolving_relative_references). + +For a background image in an external CSS file, a relative `url(...)` starts +from [the stylesheet's location](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/url_function), +which may be a different folder from the HTML file. + +### If a hosted file still will not load {#check-a-failed-resource} + +Permission alone will not fix a wrong URL or a missing file. Open the image or +stylesheet URL in a new tab. It should show the image or CSS itself, not a sign-in screen or a sharing page. + +To see what the preview actually requested in Chrome on desktop: + +1. Open Chrome's three-dot menu, then **More tools > Developer tools**. Select + **Network** in the developer tools panel. +2. In the Viewer, turn **Live preview** off and click **Refresh preview**. Keep + **Allow external resources** on only for content you trust. +3. Find the image or CSS request in **Network**. Select it and open **Headers** + to check **Request URL** and **Status Code**. + +| What you find | What to check | +|---|---| +| `404` | The server could not find that URL. Check the filename, case, and folder path. | +| A blocked request | Read the browser's **Console** message for the reason. Renaming the file will not fix a preview restriction. | +| `200`, but the page is still unstyled | Check that the response contains the expected CSS, then check which rules apply to the element. | + +[Chrome's Network guide](https://developer.chrome.com/docs/devtools/network) +explains the request details. Turn **Live preview** back on when you are done. +External resources can contact other websites, so leave them off for HTML you +do not trust. Do not disable browser security to make a preview work. + +## Test a button with inline JavaScript {#check-a-small-javascript-interaction} + +Paste the [first, self-contained example](#check-a-self-contained-html-example) +back into the Viewer. Add this button inside its `body`, after the paragraph and +before . Start with **Allow external resources** off: + +```html + +``` + +With scripts off, the button appears, but clicking it does not change its label. +Turn on **Allow external resources**, then select **Run scripts — +enable external resources first**. Click the **Test button** in the preview again; +its label should change to **Clicked**. + +
+ +
The button is already in the source. Its first click does nothing. After you enable both settings, click it again and the label changes to Clicked.
+
+ +Changing these permission settings refreshes the preview and resets the button. +Click it again after you change a setting. + +This tests JavaScript written inside the HTML. In pasted HTML, the Viewer can +run inline scripts, but it blocks external `