|
| 1 | +--- |
| 2 | +title: Add Syntax Highlighting to Code Blocks in the Blog's CSS |
| 3 | +date: 2025-12-22 |
| 4 | +category: Technical Note |
| 5 | +description: A clear guide on how to implement syntax highlighting for code blocks in a blog using CSS and client-side highlighting libraries. |
| 6 | +tags: [css] |
| 7 | +recommended: true |
| 8 | +thumbnail: assets/img/ogp.png |
| 9 | +--- |
| 10 | + |
| 11 | +Hello! This is Pan. |
| 12 | + |
| 13 | +In this post I summarize what I did to add syntax highlighting to code blocks on my blog. |
| 14 | + |
| 15 | +The build process only formats and outputs the structure of code blocks; the visual styling is handled on the client side via CSS and a highlighting library. Below I describe the actual implementation I confirmed and the CSS and setup steps I added or adjusted, with concrete examples. |
| 16 | + |
| 17 | +## Build overview |
| 18 | + |
| 19 | +The custom renderer in the build script outputs Markdown code blocks as the following HTML structure: |
| 20 | + |
| 21 | +- `<figure class="code-block" data-lang="xx">`: wraps the entire code block |
| 22 | +- `div.code-header`: displays a language label at the top |
| 23 | +- The intended build output shape is `<pre><code class="language-xx">...</code></pre>` |
| 24 | + |
| 25 | +That's it. |
| 26 | + |
| 27 | +For chart outputs using Mermaid, emit something like: |
| 28 | +- `<div class="mermaid-wrapper"><div class="mermaid">...</div></div>` |
| 29 | + |
| 30 | +and let the client initialize Mermaid to render it. |
| 31 | + |
| 32 | +In short, the build side's responsibility is to attach "which language" and "visual hooks" — actual coloring is delegated to a client-side library. |
| 33 | + |
| 34 | +This design has the following benefits: |
| 35 | + |
| 36 | +- Lighter site builds (no tokenization or server-side highlighting) |
| 37 | +- Easier client-side theme switching |
| 38 | +- Easier handling of blocks that require client rendering (like Mermaid) |
| 39 | + |
| 40 | +## Steps I actually took (overview) |
| 41 | + |
| 42 | +1. Create CSS that matches the HTML structure emitted (`.code-block` family of rules). |
| 43 | +2. Add Prism.js (or highlight.js) to highlight `<code class="language-...">` elements. |
| 44 | +3. If there are Mermaid blocks, call `mermaid.initialize()` on the client to render them. |
| 45 | +4. Implement line numbers, line highlighting, and dark-mode support in CSS (and add JS helpers if needed). |
| 46 | + |
| 47 | +Below I include the sample CSS and Prism setup examples I used in the article. Adjust them to fit your project's conventions. |
| 48 | + |
| 49 | +### Sample CSS |
| 50 | + |
| 51 | +An example I actually used. Change colors and fonts as you like. |
| 52 | + |
| 53 | + /* Blog: base styles for code blocks */ |
| 54 | + figure.code-block { |
| 55 | + margin: 1.2em 0; |
| 56 | + border-radius: 8px; |
| 57 | + overflow: hidden; |
| 58 | + background: #0b0f14; /* example dark background. Override for light theme via another class */ |
| 59 | + color: #e6eef6; |
| 60 | + box-shadow: 0 1px 0 rgba(0,0,0,0.15); |
| 61 | + font-size: 0.9rem; |
| 62 | + } |
| 63 | + |
| 64 | + figure.code-block .code-header { |
| 65 | + display: flex; |
| 66 | + align-items: center; |
| 67 | + gap: 8px; |
| 68 | + padding: 8px 12px; |
| 69 | + background: linear-gradient(90deg, rgba(255,255,255,0.03), rgba(255,255,255,0.01)); |
| 70 | + border-bottom: 1px solid rgba(255,255,255,0.04); |
| 71 | + } |
| 72 | + |
| 73 | + figure.code-block .lang-icon { display: inline-flex; align-items: center; } |
| 74 | + figure.code-block .lang-label { font-weight: 600; font-size: 0.85rem; color: #cfe3ff; } |
| 75 | + |
| 76 | + figure.code-block pre { |
| 77 | + margin: 0; |
| 78 | + padding: 12px; |
| 79 | + overflow: auto; |
| 80 | + font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, "Roboto Mono", "Courier New", monospace; |
| 81 | + line-height: 1.6; |
| 82 | + background: transparent; |
| 83 | + color: inherit; |
| 84 | + } |
| 85 | + |
| 86 | + /* Prepare for line numbers or line highlighting (can be used with Prism plugins) */ |
| 87 | + pre[data-line] { |
| 88 | + position: relative; |
| 89 | + } |
| 90 | + |
| 91 | + /* Prism token colors are intended to be overridden per theme */ |
| 92 | + .token.comment { color: #6a737d; } |
| 93 | + .token.keyword { color: #ff7b72; font-weight: 600; } |
| 94 | + .token.function { color: #79b8ff; } |
| 95 | + |
| 96 | +### Loading Prism.js via CDN (example) |
| 97 | + |
| 98 | +For quick testing you can load from a CDN. For production, prefer bundling or hosting locally. |
| 99 | + |
| 100 | + <!-- Prism CSS and JS (example: CDN) --> |
| 101 | + <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@latest/themes/prism-tomorrow.css" /> |
| 102 | + <script src="https://cdn.jsdelivr.net/npm/prismjs@latest/prism.min.js"></script> |
| 103 | + <!-- Load language components you need --> |
| 104 | + <script src="https://cdn.jsdelivr.net/npm/prismjs@latest/components/prism-javascript.min.js"></script> |
| 105 | + <script src="https://cdn.jsdelivr.net/npm/prismjs@latest/components/prism-python.min.js"></script> |
| 106 | + |
| 107 | + <!-- Prism plugins (line numbers, etc.) --> |
| 108 | + <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@latest/plugins/line-numbers/prism-line-numbers.css" /> |
| 109 | + <script src="https://cdn.jsdelivr.net/npm/prismjs@latest/plugins/line-numbers/prism-line-numbers.min.js"></script> |
| 110 | + |
| 111 | + <!-- Initialization is usually not required (Prism often runs on DOMContentLoaded automatically) --> |
| 112 | + |
| 113 | +Note: `tools/build-blog.js` emits `<code class="language-xxx">`, so loading the corresponding Prism language components should color them automatically. |
| 114 | + |
| 115 | +### Handling Mermaid |
| 116 | + |
| 117 | +Because the build emits a dedicated wrapper for Mermaid blocks, initialize Mermaid on the client. |
| 118 | + |
| 119 | + <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script> |
| 120 | + <script> |
| 121 | + mermaid.initialize({ startOnLoad: false, theme: 'base' }); |
| 122 | + // build-blog.js outputs .mermaid elements, so after DOM is ready initialize each |
| 123 | + document.addEventListener('DOMContentLoaded', () => { |
| 124 | + document.querySelectorAll('.mermaid').forEach((el) => { |
| 125 | + try { |
| 126 | + mermaid.parse(el.textContent); |
| 127 | + // Simple render call |
| 128 | + mermaid.init(undefined, el); |
| 129 | + } catch (e) { |
| 130 | + console.warn('mermaid parse failed', e); |
| 131 | + } |
| 132 | + }); |
| 133 | + }); |
| 134 | + </script> |
| 135 | + |
| 136 | +## Extra improvements worth adding |
| 137 | + |
| 138 | +- Line numbers |
| 139 | +- Line highlighting |
| 140 | +- Copy button |
| 141 | +- Light / dark theme switching |
| 142 | +- Server-side prerendering: since highlighting is client-side in this approach, consider running Prism during build to produce highlighted HTML if you want better first-paint performance or SEO. |
| 143 | + |
| 144 | +## Summary |
| 145 | + |
| 146 | +- Emit well-structured code blocks (labels, classes, data-lang) from the build, and let CSS + a client-side highlighting library handle coloring and fine visual adjustments. This makes implementation straightforward and easier to maintain. |
| 147 | +- For small blogs, using Prism and Mermaid from a CDN is a fast way to get things working; after testing, bundle them into your production build. |
| 148 | +- You can easily add user-friendly features like line numbers, copy buttons, and theme switching. |
| 149 | + |
| 150 | +Thanks for reading! If you want, I can add a concrete CSS file to the project or explain how to integrate Prism into your build pipeline. Let me know which you'd prefer. |
0 commit comments