Why Jekyll Renders HTML as Code Blocks (and How to Fix It)

2026-06-10 · jekyll / markdown · #liquid #kramdown #troubleshooting
When writing Jekyll pages with Liquid and HTML, you may see raw tags such as <section> rendered as a code block instead of normal HTML.
This issue is common in category or tag archive pages where loop output is mixed with Markdown content.
Symptom

The page shows literal HTML like <section class="card archive-group">.
Sidebar anchor links do not jump to the expected section.
The page looks like a large <pre><code> block.
Root Cause

In Markdown (Kramdown), block content indented by 4+ spaces can be interpreted as a code block.
When Liquid loops output HTML with leading indentation, the final rendered content can accidentally enter code-block context.
That means your intended DOM nodes are not created, so anchors (for example #history or #jekyll) cannot find target IDs.
Fix

Keep loop-generated block HTML left-aligned (no extra leading spaces before <section>, <ul>, <li>, etc.).
Add explicit IDs to each category/tag section.
Make sidebar links point to those IDs.
Example:
<section id="cuda" class="card archive-group">
	<h2>#cuda</h2>
</section>


<section id="nvidia" class="card archive-group">
	<h2>#nvidia</h2>
</section>


<section id="ubuntu" class="card archive-group">
	<h2>#ubuntu</h2>
</section>


<section id="python" class="card archive-group">
	<h2>#python</h2>
</section>


<section id="torch" class="card archive-group">
	<h2>#torch</h2>
</section>


<section id="regex" class="card archive-group">
	<h2>#regex</h2>
</section>


<section id="history" class="card archive-group">
	<h2>#history</h2>
</section>


<section id="perl" class="card archive-group">
	<h2>#perl</h2>
</section>


<section id="vim" class="card archive-group">
	<h2>#vim</h2>
</section>


<section id="liquid" class="card archive-group">
	<h2>#liquid</h2>
</section>


<section id="kramdown" class="card archive-group">
	<h2>#kramdown</h2>
</section>


<section id="troubleshooting" class="card archive-group">
	<h2>#troubleshooting</h2>
</section>


<section id="jekyll" class="card archive-group">
	<h2>#jekyll</h2>
</section>


<section id="prompt" class="card archive-group">
	<h2>#prompt</h2>
</section>


<section id="llm" class="card archive-group">
	<h2>#llm</h2>
</section>


<section id="trl" class="card archive-group">
	<h2>#trl</h2>
</section>


<section id="sft" class="card archive-group">
	<h2>#sft</h2>
</section>


<section id="finetuning" class="card archive-group">
	<h2>#finetuning</h2>
</section>


<section id="huggingface" class="card archive-group">
	<h2>#huggingface</h2>
</section>


<section id="oom" class="card archive-group">
	<h2>#oom</h2>
</section>


<section id="lora" class="card archive-group">
	<h2>#lora</h2>
</section>


<section id="qlora" class="card archive-group">
	<h2>#qlora</h2>
</section>


<section id="lookahead" class="card archive-group">
	<h2>#lookahead</h2>
</section>


<section id="pattern-matching" class="card archive-group">
	<h2>#pattern-matching</h2>
</section>


<section id="github-copilot" class="card archive-group">
	<h2>#github-copilot</h2>
</section>


<section id="copilot-cli" class="card archive-group">
	<h2>#copilot-cli</h2>
</section>


<section id="npm" class="card archive-group">
	<h2>#npm</h2>
</section>


<section id="windows" class="card archive-group">
	<h2>#windows</h2>
</section>


<section id="powershell" class="card archive-group">
	<h2>#powershell</h2>
</section>


<section id="ragas" class="card archive-group">
	<h2>#ragas</h2>
</section>


<section id="asyncio" class="card archive-group">
	<h2>#asyncio</h2>
</section>


<section id="debugging" class="card archive-group">
	<h2>#debugging</h2>
</section>


<section id="evaluation" class="card archive-group">
	<h2>#evaluation</h2>
</section>


<section id="transformer" class="card archive-group">
	<h2>#transformer</h2>
</section>


<section id="pytorch" class="card archive-group">
	<h2>#pytorch</h2>
</section>


<section id="attention" class="card archive-group">
	<h2>#attention</h2>
</section>


<section id="os" class="card archive-group">
	<h2>#os</h2>
</section>


<section id="pathlib" class="card archive-group">
	<h2>#pathlib</h2>
</section>


<section id="mkdir" class="card archive-group">
	<h2>#mkdir</h2>
</section>


<section id="makedirs" class="card archive-group">
	<h2>#makedirs</h2>
</section>


<section id="deep-learning" class="card archive-group">
	<h2>#Deep Learning</h2>
</section>


<section id="pytorch" class="card archive-group">
	<h2>#PyTorch</h2>
</section>


<section id="tensorflow" class="card archive-group">
	<h2>#TensorFlow</h2>
</section>


<section id="jax" class="card archive-group">
	<h2>#JAX</h2>
</section>


<section id="market-share" class="card archive-group">
	<h2>#Market Share</h2>
</section>


<section id="data" class="card archive-group">
	<h2>#Data</h2>
</section>


<section id="machine-learning" class="card archive-group">
	<h2>#Machine Learning</h2>
</section>


<section id="framework" class="card archive-group">
	<h2>#Framework</h2>
</section>


<section id="nlp" class="card archive-group">
	<h2>#nlp</h2>
</section>


<section id="training" class="card archive-group">
	<h2>#training</h2>
</section>


<section id="transformers" class="card archive-group">
	<h2>#transformers</h2>
</section>


<section id="torchtune" class="card archive-group">
	<h2>#torchtune</h2>
</section>


<section id="gqa" class="card archive-group">
	<h2>#gqa</h2>
</section>


<section id="flashattention" class="card archive-group">
	<h2>#flashattention</h2>
</section>


<section id="blog" class="card archive-group">
	<h2>#blog</h2>
</section>


<section id="community" class="card archive-group">
	<h2>#community</h2>
</section>


<section id="documentation" class="card archive-group">
	<h2>#documentation</h2>
</section>


<section id="china" class="card archive-group">
	<h2>#china</h2>
</section>


<section id="tech" class="card archive-group">
	<h2>#tech</h2>
</section>


<section id="safetensors" class="card archive-group">
	<h2>#safetensors</h2>
</section>


<section id="model-analysis" class="card archive-group">
	<h2>#model-analysis</h2>
</section>


<section id="firmware" class="card archive-group">
	<h2>#firmware</h2>
</section>


<section id="driver" class="card archive-group">
	<h2>#driver</h2>
</section>


<section id="application" class="card archive-group">
	<h2>#application</h2>
</section>


<section id="web" class="card archive-group">
	<h2>#web</h2>
</section>


<section id="terminal" class="card archive-group">
	<h2>#terminal</h2>
</section>


<section id="gui" class="card archive-group">
	<h2>#gui</h2>
</section>


<section id="compiler" class="card archive-group">
	<h2>#compiler</h2>
</section>


<section id="interpreter" class="card archive-group">
	<h2>#interpreter</h2>
</section>


<section id="html" class="card archive-group">
	<h2>#html</h2>
</section>


<section id="javascript" class="card archive-group">
	<h2>#javascript</h2>
</section>


<section id="c" class="card archive-group">
	<h2>#c</h2>
</section>


<section id="cpp" class="card archive-group">
	<h2>#cpp</h2>
</section>


<section id="lpddr" class="card archive-group">
	<h2>#lpddr</h2>
</section>


<section id="ram" class="card archive-group">
	<h2>#ram</h2>
</section>


<section id="mobile" class="card archive-group">
	<h2>#mobile</h2>
</section>


<section id="memory-training" class="card archive-group">
	<h2>#memory-training</h2>
</section>


<section id="pop" class="card archive-group">
	<h2>#pop</h2>
</section>


<section id="package" class="card archive-group">
	<h2>#package</h2>
</section>


<section id="ascii" class="card archive-group">
	<h2>#ascii</h2>
</section>


<section id="font" class="card archive-group">
	<h2>#font</h2>
</section>


<section id="bitmap-font" class="card archive-group">
	<h2>#bitmap-font</h2>
</section>


<section id="character-encoding" class="card archive-group">
	<h2>#character-encoding</h2>
</section>


<section id="graphics" class="card archive-group">
	<h2>#graphics</h2>
</section>


<section id="cache" class="card archive-group">
	<h2>#cache</h2>
</section>


<section id="cache-coherency" class="card archive-group">
	<h2>#cache-coherency</h2>
</section>


<section id="tlb" class="card archive-group">
	<h2>#tlb</h2>
</section>


<section id="mmu" class="card archive-group">
	<h2>#mmu</h2>
</section>


<section id="dma" class="card archive-group">
	<h2>#dma</h2>
</section>


<section id="snooping" class="card archive-group">
	<h2>#snooping</h2>
</section>


<section id="multimodal" class="card archive-group">
	<h2>#multimodal</h2>
</section>


<section id="embedding" class="card archive-group">
	<h2>#embedding</h2>
</section>


<section id="vision-transformer" class="card archive-group">
	<h2>#vision-transformer</h2>
</section>


<section id="linux" class="card archive-group">
	<h2>#linux</h2>
</section>


<section id="shell" class="card archive-group">
	<h2>#shell</h2>
</section>


<section id="bash" class="card archive-group">
	<h2>#bash</h2>
</section>


<section id="dash" class="card archive-group">
	<h2>#dash</h2>
</section>


<section id="sh" class="card archive-group">
	<h2>#sh</h2>
</section>


<section id="debian" class="card archive-group">
	<h2>#debian</h2>
</section>


<section id="coreutils" class="card archive-group">
	<h2>#coreutils</h2>
</section>


<section id="users" class="card archive-group">
	<h2>#users</h2>
</section>


<section id="groups" class="card archive-group">
	<h2>#groups</h2>
</section>


<section id="id" class="card archive-group">
	<h2>#id</h2>
</section>


<section id="whoami" class="card archive-group">
	<h2>#whoami</h2>
</section>


<section id="logname" class="card archive-group">
	<h2>#logname</h2>
</section>


<section id="distribution" class="card archive-group">
	<h2>#distribution</h2>
</section>


<section id="centos" class="card archive-group">
	<h2>#centos</h2>
</section>


<section id="fedora" class="card archive-group">
	<h2>#fedora</h2>
</section>


<section id="suse" class="card archive-group">
	<h2>#suse</h2>
</section>


<section id="dpkg" class="card archive-group">
	<h2>#dpkg</h2>
</section>


<section id="apt" class="card archive-group">
	<h2>#apt</h2>
</section>


<section id="packages" class="card archive-group">
	<h2>#packages</h2>
</section>


<section id="usr-merge" class="card archive-group">
	<h2>#usr-merge</h2>
</section>


<section id="process" class="card archive-group">
	<h2>#process</h2>
</section>


<section id="procps" class="card archive-group">
	<h2>#procps</h2>
</section>


<section id="top" class="card archive-group">
	<h2>#top</h2>
</section>


<section id="ps" class="card archive-group">
	<h2>#ps</h2>
</section>


<section id="procfs" class="card archive-group">
	<h2>#procfs</h2>
</section>


<section id="who" class="card archive-group">
	<h2>#who</h2>
</section>


<section id="w" class="card archive-group">
	<h2>#w</h2>
</section>


<section id="ssh" class="card archive-group">
	<h2>#ssh</h2>
</section>


<section id="session" class="card archive-group">
	<h2>#session</h2>
</section>


<section id="utmp" class="card archive-group">
	<h2>#utmp</h2>
</section>


<section id="ragflow" class="card archive-group">
	<h2>#ragflow</h2>
</section>


<section id="retriever" class="card archive-group">
	<h2>#retriever</h2>
</section>


<section id="retrieval" class="card archive-group">
	<h2>#retrieval</h2>
</section>


<section id="elasticsearch" class="card archive-group">
	<h2>#elasticsearch</h2>
</section>


<section id="rag" class="card archive-group">
	<h2>#rag</h2>
</section>


<section id="cpu" class="card archive-group">
	<h2>#cpu</h2>
</section>


<section id="flip-flop" class="card archive-group">
	<h2>#flip-flop</h2>
</section>


<section id="latch" class="card archive-group">
	<h2>#latch</h2>
</section>


<section id="sram" class="card archive-group">
	<h2>#sram</h2>
</section>


<section id="register" class="card archive-group">
	<h2>#register</h2>
</section>


<section id="memory" class="card archive-group">
	<h2>#memory</h2>
</section>


<section id="environment" class="card archive-group">
	<h2>#environment</h2>
</section>


<section id="profile" class="card archive-group">
	<h2>#profile</h2>
</section>


<section id="rope" class="card archive-group">
	<h2>#rope</h2>
</section>


<section id="positional-encoding" class="card archive-group">
	<h2>#positional-encoding</h2>
</section>


<section id="docker" class="card archive-group">
	<h2>#docker</h2>
</section>


<section id="watchdog" class="card archive-group">
	<h2>#watchdog</h2>
</section>


<section id="mcp" class="card archive-group">
	<h2>#mcp</h2>
</section>


<section id="vscode" class="card archive-group">
	<h2>#vscode</h2>
</section>


<section id="authentication" class="card archive-group">
	<h2>#authentication</h2>
</section>


<section id="access-token" class="card archive-group">
	<h2>#access-token</h2>
</section>


<section id="logout" class="card archive-group">
	<h2>#logout</h2>
</section>


<section id="security" class="card archive-group">
	<h2>#security</h2>
</section>


<section id="mysql" class="card archive-group">
	<h2>#mysql</h2>
</section>


<section id="docker-compose" class="card archive-group">
	<h2>#docker-compose</h2>
</section>


<section id="upgrade" class="card archive-group">
	<h2>#upgrade</h2>
</section>


<section id="proxy" class="card archive-group">
	<h2>#proxy</h2>
</section>


<section id="no-proxy" class="card archive-group">
	<h2>#no-proxy</h2>
</section>


<section id="httpx" class="card archive-group">
	<h2>#httpx</h2>
</section>


<section id="http-proxy" class="card archive-group">
	<h2>#http-proxy</h2>
</section>


<section id="superuser" class="card archive-group">
	<h2>#superuser</h2>
</section>


<section id="admin" class="card archive-group">
	<h2>#admin</h2>
</section>


<section id="initialization" class="card archive-group">
	<h2>#initialization</h2>
</section>


<section id="database" class="card archive-group">
	<h2>#database</h2>
</section>


<section id="migration" class="card archive-group">
	<h2>#migration</h2>
</section>


<section id="model-provider" class="card archive-group">
	<h2>#model-provider</h2>
</section>


<section id="ai" class="card archive-group">
	<h2>#ai</h2>
</section>


<section id="performance" class="card archive-group">
	<h2>#performance</h2>
</section>


<section id="feature-development" class="card archive-group">
	<h2>#feature-development</h2>
</section>


<section id="requirements" class="card archive-group">
	<h2>#requirements</h2>
</section>


<section id="testing" class="card archive-group">
	<h2>#testing</h2>
</section>


<section id="architecture" class="card archive-group">
	<h2>#architecture</h2>
</section>


<section id="http" class="card archive-group">
	<h2>#http</h2>
</section>


<section id="https" class="card archive-group">
	<h2>#https</h2>
</section>


<section id="tls" class="card archive-group">
	<h2>#tls</h2>
</section>


<section id="ssl" class="card archive-group">
	<h2>#ssl</h2>
</section>


<section id="certificate" class="card archive-group">
	<h2>#certificate</h2>
</section>


<section id="certifi" class="card archive-group">
	<h2>#certifi</h2>
</section>


<section id="requests" class="card archive-group">
	<h2>#requests</h2>
</section>


<section id="urllib" class="card archive-group">
	<h2>#urllib</h2>
</section>


<section id="aiohttp" class="card archive-group">
	<h2>#aiohttp</h2>
</section>


<section id="react" class="card archive-group">
	<h2>#react</h2>
</section>


<section id="svg" class="card archive-group">
	<h2>#svg</h2>
</section>


<section id="iconfont" class="card archive-group">
	<h2>#iconfont</h2>
</section>


<section id="typescript" class="card archive-group">
	<h2>#typescript</h2>
</section>


<section id="aws" class="card archive-group">
	<h2>#aws</h2>
</section>


<section id="confluence" class="card archive-group">
	<h2>#confluence</h2>
</section>


<section id="enterprise" class="card archive-group">
	<h2>#enterprise</h2>
</section>


<section id="kerberos" class="card archive-group">
	<h2>#kerberos</h2>
</section>


<section id="kinit" class="card archive-group">
	<h2>#kinit</h2>
</section>


<section id="klist" class="card archive-group">
	<h2>#klist</h2>
</section>


<section id="dsregcmd" class="card archive-group">
	<h2>#dsregcmd</h2>
</section>


<section id="probability" class="card archive-group">
	<h2>#probability</h2>
</section>


<section id="poisson" class="card archive-group">
	<h2>#poisson</h2>
</section>


<section id="gamma" class="card archive-group">
	<h2>#gamma</h2>
</section>


<section id="negative-binomial" class="card archive-group">
	<h2>#negative-binomial</h2>
</section>


<section id="pascal" class="card archive-group">
	<h2>#pascal</h2>
</section>


<section id="claude" class="card archive-group">
	<h2>#claude</h2>
</section>


<section id="amazon-bedrock" class="card archive-group">
	<h2>#amazon-bedrock</h2>
</section>


<section id="litellm" class="card archive-group">
	<h2>#litellm</h2>
</section>


<section id="openai-compatible-api" class="card archive-group">
	<h2>#openai-compatible-api</h2>
</section>


<section id="prompting" class="card archive-group">
	<h2>#prompting</h2>
</section>


<section id="skill" class="card archive-group">
	<h2>#skill</h2>
</section>


<section id="mkcert" class="card archive-group">
	<h2>#mkcert</h2>
</section>


<section id="datasource" class="card archive-group">
	<h2>#datasource</h2>
</section>


<section id="document-parsing" class="card archive-group">
	<h2>#document-parsing</h2>
</section>


<section id="redis" class="card archive-group">
	<h2>#redis</h2>
</section>


<section id="minio" class="card archive-group">
	<h2>#minio</h2>
</section>


<section id="microsoft" class="card archive-group">
	<h2>#microsoft</h2>
</section>


<section id="entra-id" class="card archive-group">
	<h2>#entra-id</h2>
</section>


<section id="azure" class="card archive-group">
	<h2>#azure</h2>
</section>


<section id="microsoft-graph" class="card archive-group">
	<h2>#microsoft-graph</h2>
</section>


<section id="oauth" class="card archive-group">
	<h2>#oauth</h2>
</section>


<section id="msal" class="card archive-group">
	<h2>#msal</h2>
</section>


<section id="sharepoint" class="card archive-group">
	<h2>#sharepoint</h2>
</section>


<section id="onedrive" class="card archive-group">
	<h2>#onedrive</h2>
</section>


<section id="cloud" class="card archive-group">
	<h2>#cloud</h2>
</section>


<section id="domain" class="card archive-group">
	<h2>#domain</h2>
</section>


<section id="vps" class="card archive-group">
	<h2>#vps</h2>
</section>


<section id="hosting" class="card archive-group">
	<h2>#hosting</h2>
</section>


<section id="dataset" class="card archive-group">
	<h2>#dataset</h2>
</section>


<section id="document" class="card archive-group">
	<h2>#document</h2>
</section>


<section id="filtering" class="card archive-group">
	<h2>#filtering</h2>
</section>


<section id="metadata" class="card archive-group">
	<h2>#metadata</h2>
</section>


<section id="frontend" class="card archive-group">
	<h2>#frontend</h2>
</section>


<section id="env" class="card archive-group">
	<h2>#env</h2>
</section>


<section id="dotenv" class="card archive-group">
	<h2>#dotenv</h2>
</section>


<section id="git-bash" class="card archive-group">
	<h2>#git-bash</h2>
</section>


<section id="connector" class="card archive-group">
	<h2>#connector</h2>
</section>


<section id="api" class="card archive-group">
	<h2>#api</h2>
</section>


<section id="routes" class="card archive-group">
	<h2>#routes</h2>
</section>


<section id="administration" class="card archive-group">
	<h2>#administration</h2>
</section>


<section id="environment-variables" class="card archive-group">
	<h2>#environment-variables</h2>
</section>


<section id="path" class="card archive-group">
	<h2>#path</h2>
</section>


<section id="setx" class="card archive-group">
	<h2>#setx</h2>
</section>


<section id="psreadline" class="card archive-group">
	<h2>#psreadline</h2>
</section>


<section id="command-line" class="card archive-group">
	<h2>#command-line</h2>
</section>
Best Practices for Jekyll Blog Pages

Prefer Liquid-driven HTML sections for archive pages.
Avoid mixing deeply indented HTML blocks inside Markdown list contexts.
Use slugify for stable anchor IDs.
Validate generated HTML by checking browser dev tools.
Takeaway

If Jekyll pages unexpectedly render as code blocks, check indentation first.
In most cases, moving Liquid-generated HTML to top-level alignment resolves both rendering and navigation issues immediately.