Refactor and Expand Code Block and Markdown Rendering System

Summary

Refactored and expanded the code block and markdown rendering system, introducing new utilities, improved component structure, and enhanced styling for better code presentation and maintainability.

Why Care

This update significantly improves the developer and user experience by providing more robust, maintainable, and extensible code block rendering. The changes enable easier addition of new languages, more consistent styling, and better markdown handling, which is critical for documentation-heavy and developer-facing sites.

Implementation

Changes Made

  • Refactored src/components/basics/Hero.astro for layout and style improvements.
  • Enhanced src/components/codeblocks/BaseCodeblock.astro for advanced syntax highlighting and UI improvements.
  • Improved src/components/markdown/AstroMarkdown.astro for better markdown support.
  • Added new CSS theme: src/styles/shiki-github-dark.css for unified codeblock appearance.
  • Implemented shell language normalization utilities: src/utils/markdown/normalizeShellLangs.ts and src/utils/markdown/remarkNormalizeShellLangs.ts.
  • Updated configuration in astro.config.mjs and dependencies in package.json to support new features and plugins.
  • Added new message card components: src/components/basics/messages/IconHeaderMessageCard.astro and IconHeaderMessageCardGrid.astro.
  • Created new demonstration content: src/content/messages/vibeCodingIconHeaderMessages.json and new page src/pages/vibe-with/us.astro.
Tree structure of impacted files:
text 
site/
├── astro.config.mjs
├── package.json
├── src/
│   ├── components/
│   │   ├── basics/
│   │   │   ├── Hero.astro
│   │   │   └── messages/
│   │   │       ├── IconHeaderMessageCard.astro
│   │   │       └── IconHeaderMessageCardGrid.astro
│   │   ├── codeblocks/
│   │   │   └── BaseCodeblock.astro
│   │   └── markdown/
│   │       └── AstroMarkdown.astro
│   ├── content/
│   │   └── messages/
│   │       └── vibeCodingIconHeaderMessages.json
│   ├── layouts/
│   │   └── Layout.astro
│   ├── pages/
│   │   └── vibe-with/
│   │       └── us.astro
│   ├── styles/
│   │   └── shiki-github-dark.css
│   └── utils/
│       └── markdown/
│           ├── normalizeShellLangs.ts
│           └── remarkNormalizeShellLangs.ts
  • Added: shiki-github-dark.css, normalizeShellLangs.ts, remarkNormalizeShellLangs.ts
  • No removals or deprecations in this commit.

Technical Details

  • Adopted Shiki for syntax highlighting in astro.config.mjs, supporting custom languages.
  • BaseCodeblock.astro now features a copy-to-clipboard button and language indicator.
  • Markdown rendering improved via AstroMarkdown.astro and new normalization utilities.
  • New CSS ensures consistent dark theme for codeblocks across the site.
  • Configuration and dependency updates to support new features and maintain compatibility.

Integration Points

  • Codeblock rendering system integrates with markdown content throughout the site.
  • New utilities enable future extension for additional languages and markdown features.
  • No migrations or breaking changes required for existing content.

Documentation

  • See src/content/specs/Code-Block-Rendering-System.md for technical specification.
  • Usage examples in src/pages/vibe-with/us.astro and message cards in src/content/messages/vibeCodingIconHeaderMessages.json.
  • No API changes.