Notes about Markdown issues and solutions

Summary

Markdown Code Blocks: Horizontal Scroll Issue on GitHub

The Problem: Code blocks in Markdown don't wrap text—they preserve exact formatting, which is essential for executable code. However, on GitHub's responsive design, long lines in code blocks force horizontal scrolling even on desktop. On mobile, this severely impacts readability. Note that for this case, VSCode Markdown preview may wrap the text and not show horizontal scrollbar.

The Issue with Using Code Blocks for Everything: A common mistake is using code blocks for all code-like content, including example output, markup demonstrations, and non-executable examples. While code blocks provide syntax highlighting, they sacrifice user experience on narrower viewports or even wide viewports if the content has long lines exceeding viewport width.

The Solution: Choose Based on Semantic Intent

Use code blocks when:

Displaying executable code that requires exact formatting and indentation
Syntax highlighting improves clarity (e.g., python, javascript, html)
Readers will copy and execute the code

Use blockquotes for:

Example output or pasted text results
Markup demonstrations (not meant to execute)
Reference content readers will read, not run
Content that benefits from natural text wrapping

Implementation Tip

When displaying HTML markup as an example (not executable code), use HTML entities (< for < and > for >) inside blockquotes to escape special characters:

> Next I used my <a href="url">link text</a> in the HTML.

This renders cleanly on all platforms—desktop, mobile, and GitHub—without horizontal scrolling.

This horizontal scrollbar problem was faced and then solved in this README file in my bookmarklets GitHub repo (public).

==================================================================

Details

12 Feb 2026

Given below are parts of an exchange today between me and Claude AI (Cl) via GitHub CoPilot. The context for the discussion is this README file in my bookmarklets GitHub repo (public).

Me: The selected portion of the README [which had a code block] renders well in VSCode preview without a horizontal scrollbar. But in GitHub, a horizontal scrollbar is shown for it with only one line of display which the user has to horizontally scroll. Pl. comment and any solutions are welcome.

Cl: Good observation! The issue is that code blocks in Markdown don't wrap text—they preserve exact formatting, which includes very long lines. ...

Me: ... Just curious why does VSCode preview not show me such a horizontal scrollbar and single line display for this section?

[I am not convinced Cl's answer was right and so am skipping it.]

[Cl suggested dropping code block (and using blockquote).]

Me: I have dropped the code block. Now see the selected text. This was an HTML code block earlier. I need(ed) to escape the <a> and </a> tags individually using \. VSCode preview renders it correctly. Will GitHub handle this correctly? Is \ the right escape character for this purpose?

Cl: Good question! Actually, backslash is NOT the ideal escape character for HTML tags in this context. Here's why:

The issue:

In Markdown, \ escapes Markdown special characters (like *, _, [, etc.), not HTML
Backslashes before HTML tags like \<a> may render inconsistently across different renderers
VSCode preview might strip the backslash and display the tag, but GitHub might render it literally or differently

The correct approach: HTML entities

Use < for < and > for >:

> Next I wanted to generate a TOC for the anchor linked sections created above. For that I used my <a href="https://raviswdev.blogspot.com/2025/09/vscode-extension-to-auto-add-id.html">auto-header-ids-toc VSCode extension</a>. I had to add h3 to the extension's settings: auto-header-ids-toc.headersToProcess.

Why this is better:

HTML entities are universally recognized across all Markdown renderers (VSCode, GitHub, others)
They render consistently as literal < and > characters everywhere
This is the semantic HTML standard for displaying literal HTML code

...

Me: That fixed it on GitHub. Even for mobile width window all content is readable without need for horizontal scrolling. Hmm. Quite a significant UI improvement. But I am disappointed that such code blocks are not handled properly on GitHub. I expected them to be handled. Pl. comment and feel free to be critical of my views.

Cl: Your frustration is valid, but I'd also defend GitHub's approach—with caveats:

Why code blocks don't wrap on GitHub:

Intentional design decision: Code needs to preserve exact formatting. Indentation, spacing, and line alignment are semantic in code. Wrapping breaks that.
It's standard behavior: Most code editors and platforms (VS Code, GitHub, Stack Overflow, etc.) follow this principle because code must be read exactly as written.

But your point is fair:

The problem: GitHub doesn't distinguish between actual code and text output shown as code
When you display example command output or pasted text, the non-wrapping constraint is overly restrictive
A middle ground would be helpful: maybe a text or output code fence that wraps, separate from code fences that don't

Reality check:

For your use case (showing what pasted output looks like), code blocks were never the right semantic choice anyway
Blockquotes are actually MORE correct—they represent quoted/example content, which is exactly what your output is
So the "fix" wasn't just a workaround; it's semantically better Markdown

My take:

GitHub could be more flexible with code block rendering (optional wrapping toggle), but their conservative approach prevents accidentally breaking code display. Your solution using blockquotes is genuinely better—it solves both the GitHub UX problem and uses more appropriate Markdown semantics. Sometimes constraints push us toward better solutions.

Me: Oh! Good point. So the learning for me is that for this case I should have used HTML entities to escape HTML instead of using an HTML code block for it - which BTW was provided by another AI tool. Did I understand you correctly.

Cl: Not quite—let me clarify the nuance:

The learning is more specific:

When you want to show HTML markup as example/reference content (not actual code to execute), you have two approaches:

HTML code block – Will preserve formatting perfectly but causes GitHub's scrolling issue
HTML entities in blockquotes – Displays the markup as readable text, wraps naturally, and is semantically correct for "example content"

The key distinction:

Use code blocks for actual executable code that needs exact formatting preserved
Use HTML entities + blockquotes/regular text when you're showing markup as an example or reference—the user will read it, not run it

Why the other AI tool suggested a code block:

They probably categorized it as "code" rather than "example markup to display." That's a reasonable assumption, but contextually, since you're demonstrating what HTML looks like rather than providing code to use, blockquotes are more appropriate.

So the real learning:

Choose your Markdown format based on semantic intent, not just "this is HTML so it goes in a code block." If you're showing an example for readers to understand, blockquotes + entities work great. If you're sharing executable code, code blocks are essential.

This applies beyond HTML—same principle for JSON examples, configuration file snippets, etc.

Me: Got it. code block is suitable for executable code.

BTW what does html in ```html do? Why not simply use ```

Cl: Great question! The html part enables syntax highlighting.

...

Me: Hmm. so the other AI tool may have chosen to use a code block for the HTML markup in my README due to the syntax highlighting feature it provides. Am I on right track?

Cl: Yes, you're on the right track! The other AI tool probably reasoned:

"This is HTML markup" → should go in a code block
"HTML code block with syntax highlighting" → easier to read the markup structure
Result: colored tags, attributes, proper formatting

That logic is sound, but it missed the trade-off:

What they optimized for:

Syntax highlighting and visual structure clarity

What they didn't account for:

GitHub's narrow viewport causing horizontal scrolling on mobile/responsive views
That this was "example output" not "executable code"
The user experience degradation

The lesson:

When choosing Markdown formats, consider the complete user experience, not just one feature. Syntax highlighting is nice, but if it breaks readability on mobile or other contexts, it's not worth it.

In this case, blockquotes sacrificed highlighting but gained:

Proper wrapping on all devices
Semantic clarity (this is example content, not code to run)
Better mobile experience

So the other tool made a reasonable but incomplete decision. You caught the problem and chose the better solution. This kind of iterative improvement based on real-world feedback (like testing on GitHub) is exactly how documentation gets better.

Me: Please give me a short note explaining the issue we discussed above (code block causing horizontal scroll) and the solution. Also include your advice given earlier in this context. I will share this note on my blog post for future reference for myself (and perhaps may be useful to others too).

Cl:

Markdown Code Blocks vs. Blockquotes: When to Use Each

The Problem

Code blocks in Markdown don't wrap text—they preserve exact formatting, which is essential for executable code. However, on GitHub's responsive design, long lines in code blocks force horizontal scrolling even on desktop. On mobile, this severely impacts readability.

The Issue with Using Code Blocks for Everything

A common mistake is using code blocks for all code-like content, including example output, markup demonstrations, and non-executable examples. While code blocks provide syntax highlighting, they sacrifice user experience on narrower viewports.

The Solution: Choose Based on Semantic Intent

Use code blocks when:

Displaying executable code that requires exact formatting and indentation
Syntax highlighting improves clarity (e.g., python, javascript, html)
Readers will copy and execute the code

Use blockquotes for:

Example output or pasted text results
Markup demonstrations (not meant to execute)
Reference content readers will read, not run
Content that benefits from natural text wrapping

Implementation Tip

When displaying HTML markup as an example (not executable code), use HTML entities (< for < and > for >) inside blockquotes:

> Next I used my <a href="url">link text</a> in the HTML.

This renders cleanly on all platforms—desktop, mobile, and GitHub—without horizontal scrolling.

Key Learning

Choose your Markdown format based on semantic purpose, not just the type of content. This ensures better user experience across all viewing contexts

...

[For the below session, CoPilot changed the AI tool to GPT (5 mini) (GP).]

Me: An advantage of code block is that one does not need to escape special characters associated with that type of code block. So for HTML code block, we don't need to escape < or >. Am I right?

GP: Yes — within a fenced code block (html ... or just ```) you do not need to escape < or >; the fence makes the contents literal (shown as code, not parsed as HTML), so tags are displayed, not interpreted.

Caveats:

Fenced code blocks preserve formatting and typically do not wrap (hence GitHub’s horizontal scrollbar behavior).
Outside code blocks (plain paragraphs, blockquotes, or inline text), raw </> may be treated as HTML by the renderer — use </> there to show literal tags.
Inline code (`...`) also shows </> literally without escaping.or just ```) you do not need to escape < or >; the fence makes the contents literal (shown as code, not parsed as HTML), so tags are displayed, not interpreted.

Me: Hmm. I thought ... was used to hightlight words and phrases as that's how at least one AI tool uses it for generated Markdown content.

GP: You're right that some AI tools use backticks like inline "highlights," but technically:

Single backticks (`...`) create an inline code span — monospace, code semantics, and typically a gray background. Use it for code, filenames, commands, or literal tokens (e.g., run(), README.md).
Triple backticks ( ) create fenced code blocks — use for multi-line code with optional syntax highlighting (html, js).
For emphasis/visual highlighting of ordinary text use *italic* or **bold**, not backticks.

Notes:

Inline code is rendered differently (semantically and visually) from emphasis; using it for non-code is misleading to readers.
To include a backtick inside inline code, wrap with a longer fence, e.g. text [in earlier words, looks like some special characters were omitted] or use <code>...</code>.

Example:

Good: npm install (command), src/index.js (filename)
Emphasis: Important or note (not Important)) create fenced code blocks — use for multi-line code with optional syntax highlighting (html, js).
For emphasis/visual highlighting of ordinary text use *italic* or **bold**, not backticks.

Me: Oh! I need to correct myself. I thought a filename is not code. So I used such examples to say that some AI tools use inline code for highlighting.

GP: Yes — that's fine and common. Inline code spans (...) are appropriate for filenames, commands, flags, short code tokens, and literal values.

Quick guidance:

Use inline code for: README.md, npm install, --help, run().
Use bold/italic for emphasis or prose (not inline code).
Don’t overuse inline code for long sentences or non-literal phrasing — it signals "literal/technical" to readers.

Search This Blog

Ravi S. Iyer: Software Development