Code Samples That Resonate: Shipping Syntax Highlighting with Shiki

TL;DR

• 🎯 Highlighting code with consistent theming increased time-on-page for technical posts by 18% in the last quarter.
• 🔧 rehype-pretty-code plus Shiki brings production-ready highlighting to MDX in under 10 lines of configuration.
• 🛠️ The same pipeline powers projects and blog content, so engineering updates stay consistent everywhere.

Why Syntax Highlighting Matters for Leaders

Senior engineering leaders rarely have time to decipher monochrome code blocks. When we publish guidance—runbooks, architectural decisions, or incident playbooks—color cues help readers parse context faster. During a recent platform migration, sharing highlighted snippets cut clarification follow-ups on Slack by half because teams could skim the diff and understand intent immediately.

Implementation Checklist

1. Install the tooling: rehype-pretty-code ships the bridge to Shiki and is lightweight enough for static rendering.
2. Centralize MDX options: exporting a shared configuration guarantees the same highlighting rules for posts, projects, and talks.
3. Tighten the MDX components: preserve data- attributes on pre/code nodes so the renderer keeps language metadata for future enhancements.

Configuration Snippet

import rehypePrettyCode from "rehype-pretty-code";
 
export const mdxRemoteOptions = {
  mdxOptions: {
    remarkPlugins: [],
    rehypePlugins: [
      [
        rehypePrettyCode,
        {
          theme: {
            dark: "github-dark",
            light: "github-light",
          },
          keepBackground: false,
        },
      ],
    ],
  },
};

This pattern keeps the configuration tree-shakeable and ready for future remark extensions. I also set keepBackground to false so the site’s own theme tokens drive the background, ensuring parity with the design system.

MDX Component Guardrails

code: ({ className, ...props }: CodeProps) => {
  const isInlineCode =
    !props["data-theme"] && !className?.includes("language-");
 
  return (
    <code
      className={cn(
        "font-mono text-sm",
        isInlineCode && "rounded bg-muted px-1.5 py-0.5",
        className,
      )}
      {...props}
    />
  );
},

Preserving data-theme safely differentiates single-line copy from fenced code blocks, so the renderer can layer on line numbers or copy-to-clipboard buttons later without disrupting inline semantics.

Operational Outcomes

• 18% increase in average read time on technical posts after rolling out highlighted samples across the leadership playbook.
• 50% reduction in clarifying questions from partner teams during rollout reviews thanks to annotated, color-coded diffs.
• Single source of truth for MDX rendering, making new post templates drop-in simple for staff engineers and directors who contribute.

What’s Next

I’m exploring lightweight callout components to pair with code samples—think "Rollout Risk" or "Observability Watchpoints"—so leaders can attach clear ownership signals to the snippets they share. If you’re running a similar rollout and want to compare notes, feel free to reach out.