Markdown, HTML, and URL encoding solve different problems, even though all three appear when content moves through a web application. This reference gives you a reusable checklist for converting text safely, choosing the right escaping method, diagnosing broken links and formatting, and avoiding double encoding. Use it when preparing API payloads, rendering user-generated content, migrating pages, or reviewing frontend and backend output.
Overview
Start by identifying the context in which a value will be used. Markdown is a human-friendly writing syntax. HTML is a document markup language. URL percent-encoding represents characters inside a URI component. They are related at the boundaries of a web workflow, but they are not interchangeable.
For example, *read this* is Markdown that may become <em>read this</em> after Markdown parsing. The text read this & that may need an HTML entity when placed directly in an HTML text node. A search value such as red shoes & socks needs URL encoding when inserted into a query parameter, where the ampersand otherwise separates parameters.
| Task | Use | Do not substitute |
|---|---|---|
| Format authored text | Markdown, then a trusted Markdown-to-HTML pipeline | Manually replacing every symbol with an HTML entity |
| Display text in HTML | Context-appropriate HTML escaping | URL encoding |
| Place a value in a URL | Encode the individual URL component or query value | Encoding the complete URL indiscriminately |
| Send structured data | JSON serialization | Concatenating strings with ad hoc escaping |
Encoding is not a security boundary by itself. Output must also be handled according to its destination: HTML text, an HTML attribute, a JavaScript string, a CSS value, a URL component, or a database query each has different rules. For a wider data-conversion workflow, see the developer data format and conversion guide.
Checklist by scenario
Writing Markdown that becomes HTML
- Confirm which Markdown dialect and extensions your renderer supports. Tables, task lists, raw HTML, and automatic links can vary between implementations.
- Keep the source as Markdown until the rendering step. Do not pre-convert ordinary punctuation into HTML entities unless the renderer requires it.
- Pass the result through the project’s established Markdown parser and sanitization process when content is untrusted.
- Inspect the generated HTML for heading structure, link destinations, image alternative text, and unexpected raw elements.
- Test both the visual result and the source output. A preview alone may hide incorrect semantics or unsafe attributes.
Markdown syntax is concise, but it does not remove the need for accessible HTML. Use headings in a logical order, descriptive link text, and meaningful alternative text for informative images. A repeatable accessibility testing checklist can help catch problems after conversion.
Displaying special characters in HTML
When inserting plain text into HTML, use your framework’s text-rendering or escaping API rather than concatenating markup. Common character references include:
| Character | Named reference | Numeric form | Typical reason |
|---|---|---|---|
| & | & | & | Prevents the character from being read as the start of a character reference |
| < | < | < | Displays a less-than sign instead of opening a tag |
| > | > | > | Useful when showing markup or code |
| " | " | " | Important inside double-quoted attributes |
| ' | ' | ' | Important inside single-quoted attributes |
Do not encode text merely because it contains Unicode. Modern HTML documents can represent characters such as accented letters and emoji when the document and transport use a compatible character encoding. Investigate the document encoding, response headers, database connection, and font support if characters appear as replacement symbols or question marks. The HTTP headers reference is useful when the response metadata may be part of the problem.
Building a URL or query string
- Build the base URL and path separately from the query parameters.
- Encode each path segment or query value with a URL-aware API.
- Let the API serialize separators such as
&and=rather than encoding the entire assembled URL. - Read the final URL back and verify that the server receives the intended values.
Reserved characters have structural meaning in URLs. A question mark commonly begins a query, an ampersand separates query parameters, an equals sign separates a name from its value, and a hash introduces a fragment. If one of these characters is part of the data, it must be encoded in that component. A space may appear as %20 in a percent-encoded component; form-style query serialization may represent it as +. Use the convention expected by the API or library rather than replacing characters manually.
| Input value | Encoded example | Why it matters |
|---|---|---|
red shoes | red%20shoes | The space must not split the URL value |
fish & chips | fish%20%26%20chips | The ampersand is data, not a parameter separator |
a/b as one segment | a%2Fb | The slash must not create a second path segment |
100% | 100%25 | The percent sign must not be mistaken for an existing escape |
Preparing API payloads and debugging output
Serialize structured values with the API’s JSON or form-data tooling. If a value is base64-encoded, decoded from a JWT, or placed in a URL, confirm which representation the receiving system expects. Do not treat base64 as encryption, and do not assume a decoded token is safe to trust. For browser-based inspection, compare the value at each boundary: user input, client request, server log, response payload, and rendered output. The API testing workflow provides a broader process for tracing those boundaries.
What to double-check
- Context: Is the value going into HTML text, an attribute, a URL, JavaScript, CSS, JSON, or a database query? Select the encoder for that context.
- Ownership: Is the content trusted application data, authored Markdown, or arbitrary user input? Untrusted content needs validation and safe rendering, not just cosmetic escaping.
- Order: Encode as close as possible to the final output context. Early, repeated conversions make it difficult to know what a value currently represents.
- Unicode: Test accented characters, emoji, combining characters, and non-Latin scripts. Check both what the browser displays and what the server receives.
- Path versus query: Encode a path segment differently from a complete path, and encode a query value differently from the complete query string.
- Line breaks: Decide whether a newline should remain a newline, become a paragraph, become an HTML
<br>, or be represented as\nin JSON. Do not assume one conversion fits every output. - Accessibility: Check link names, headings, focus behavior, and alternative text after Markdown or HTML conversion. Correct encoding does not guarantee usable markup.
- Headers and content type: Confirm that the response declares the format the client expects. A correctly encoded body can still be misread when its content type or character encoding is wrong.
Common mistakes
Double encoding
Double encoding happens when an already encoded value is encoded again. For example, % in %26 can become %25, producing %2526. The receiving system may then display the escape sequence instead of the intended character. Track whether each variable contains raw text or an encoded component, and encode only at the boundary where it is needed.
Encoding the whole URL
Passing a complete URL through a generic text encoder can turn separators into data. Instead, preserve the scheme, host, path structure, and query separators, while encoding only the relevant path segments and values. Prefer the platform’s URL and URLSearchParams-style APIs when available.
Using HTML entities as a security strategy
Replacing a few visible symbols does not safely handle every output context. An HTML entity may be appropriate for an HTML text node but insufficient for a JavaScript string or URL. Use context-aware framework APIs and avoid inserting untrusted strings as raw HTML.
Assuming Markdown is HTML
Markdown is input syntax, not the final browser document. A parser may permit raw HTML, interpret links differently, or support extensions that another parser does not. Pin the renderer behavior in tests and review generated markup after library or configuration changes.
Replacing newlines without deciding on semantics
Turning every newline into an HTML break can create awkward reading order and inaccessible output. Decide whether the source represents paragraphs, a code block, a list, or a literal line break, then render that meaning with the appropriate element.
When to revisit
Keep this checklist available whenever a workflow changes or its inputs change. Revisit it before a content migration, a redesign of rich-text editing, an API integration, a move to a different Markdown parser, or a framework upgrade that changes escaping and rendering defaults. It is also worth reviewing before seasonal planning cycles when teams often refresh landing pages, campaign URLs, tracking parameters, and scheduled content in batches.
For a practical review, choose representative test cases: plain text, quotation marks, ampersands, angle brackets, slashes, percent signs, spaces, Unicode characters, line breaks, and a value containing an existing percent escape. Trace each case from input to final display or request. Compare the raw value, serialized value, encoded value, and rendered result. Add the cases that exposed a bug to automated tests so the same problem is less likely to return.
Finally, document the boundary in code: state whether a function accepts raw text, Markdown, HTML, a URL component, or an already serialized value. Clear names and narrow responsibilities are often more reliable than a last-minute conversion utility. When you need related browser-based developer tools, the web developer tools toolbox collects references for formatting, testing, and data conversion tasks.
