THE GITHTML FIELD GUIDE
Embed resources in a Pandoc HTML export carefully
Pandoc can embed supported linked resources into HTML with its resource-embedding option. Use it on a controlled source document, review what will be fetched, and verify the result disconnected. Embedding is not a universal capture mechanism for arbitrary web applications, and resources loaded dynamically by scripts may still fall outside the generated file.
Inventory before embedding
List the images, stylesheets, and other resources referenced by the source document. Check ownership, licensing, confidentiality, and whether any URL requires authentication. Prefer known local assets when possible, especially for internal material.
A conversion command may fetch absolute resource URLs during the build. Review those destinations before running it on sensitive documents or untrusted source content. Do not disable certificate checking or expose credentials merely to make an export finish.
Build a separate portable copy
Run the example with Pandoc installed and guide.md available. Use a fresh output path and retain the source document for future edits. The command requests standalone HTML5 output with resources embedded where Pandoc supports the references.
If local assets are not found, check the working directory and documented resource-path behavior. Do not assume that a file located somewhere in the repository will automatically be discovered. Explicit paths make the export easier to reproduce on another machine.
pandoc guide.md --to=html5 --standalone --embed-resources --output=guide-portable.htmlUnderstand the remaining exceptions
Embedding resource bytes does not turn an interactive application into a static explanation. A script may still request additional data, and an ordinary link to another document is not the same as an embedded image. Review the output for remaining network dependencies.
Also watch file size. A small guide can become cumbersome when it embeds oversized screenshots or video. Include only assets that help the reading task, and use a text explanation for essential relationships that should survive visual failure.
Verify the promised reading boundary
Open the resulting HTML without connectivity and with scripts disabled when testing a reading-oriented copy. Check the largest figures, later sections, and internal navigation. A successful build message is not evidence that every important resource appears correctly.
For gitHtml, use the final .html artifact and confirm its behavior in the app. Document any accepted external references. The dependable outcome is a tested reading copy with a known boundary, not a blanket claim that all content reachable from the source page has been captured.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.