THE GITHTML FIELD GUIDE
Stop HTML examples from being interpreted as page markup
Escape HTML-sensitive characters when inserting source code into an HTML document. A code element provides semantics and styling hooks, but it does not automatically turn raw tags into literal text. Fix the export or insertion step so examples remain readable and untrusted sample content cannot become active page markup.
Recognize the symptom
An article may intend to show an image tag but instead display a broken picture, or intend to show a heading tag but unexpectedly create another heading. This happens when source examples are inserted as markup rather than text. Wrapping the sample in pre and code elements preserves whitespace but does not neutralize nested HTML syntax.
Inspect the delivered source around the example. If literal opening angle brackets introduce real elements, the export has not escaped the sample correctly. A syntax highlighter may conceal this distinction during authoring, especially if the preview uses a different insertion method from the final export. Check the artifact that readers receive, not only the editor's code view.
Repair the content boundary
For a manually authored example, represent angle brackets and ampersands with the appropriate character references. In a generator, use its text-escaping mechanism rather than concatenating untrusted strings into HTML. The goal is to preserve the sample as data. Do not solve the issue by taking screenshots of code; that sacrifices selection and creates readability problems on phones.
Be careful with double escaping. If a generator already escapes input and you pre-escape it again, readers may see reference text such as ampersand-lt instead of an opening bracket. Establish which layer is responsible for escaping and apply it once at the correct boundary. Keep test cases containing tags, ampersands, and quoted attributes.
Check fidelity and safety together
The corrected example should look like the intended source and copy back to the intended text. Review it with scripts disabled, but do not treat that setting as a substitute for proper escaping. Other HTML elements can still alter structure, load resources, or mislead readers even when scripting is unavailable.
- Compare the sample's original text with the exported markup.
- Use the authoring tool's text-escaping function or correct character references.
- Check that escaping occurs exactly once.
- Copy the rendered example into a plain-text editor and compare it.
- Include a sample containing an ampersand and a closing tag in regression checks.
- Keep source samples separate from any intentional trusted HTML rendering feature.
<pre><code><img src="diagram.png" alt="Request flow"></code></pre>Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.