Velora

#Project Overview

Velora is an open-source MDX blog template built for developers who want a modern, flexible, and type-safe blogging experience. It is built using Next.js, Tailwind CSS, MDX, and Velite, with a strong emphasis on rich code block rendering powered by Shiki and Rehype Pretty Code.

Velora is designed to eliminate the need to build a content pipeline from scratch by providing pre-built components, utilities, and configurations that allow developers to focus on writing content instead of tooling setup.

This project also serves as the core codebase for my Website Portfolio V3, where additional features and customizations were applied on top of Velora.

#Background & Motivation

Velora was started in December 2025 during a major redesign of my personal portfolio and blog.

Previously, my portfolio and blog were built using Next.js, Tailwind CSS, and plain Markdown. While functional, this setup had several limitations:

• Frontmatter configuration required a lot of manual work
• Syntax highlighting relied on highlight.js, which only supported basic highlighting
• Code blocks lacked advanced features such as line numbers, line highlighting, and diff notation

As I began researching ways to create a richer code block experience—including features like line highlighting, word highlighting, and diff visualization—I discovered Shiki and Rehype Pretty Code, which are also used by modern tools such as Nextra and Expressive Code.

This discovery led me to explore building a new blog setup using Next.js, MDX, and a modern content pipeline, which ultimately became Velora.

#Why Velite, Shiki, and Rehype Pretty Code

#Velite as a Content Pipeline

Velora uses Velite as its content pipeline, allowing blog content to be:

• Type-safe, defined using TypeScript
• Schema-validated using Zod
• Easy to maintain and extend with custom fields and metadata

With Velite, MDX content becomes structured data rather than loosely typed Markdown files, making it easier to scale and maintain over time.

#Shiki for Syntax Highlighting

After comparing several syntax highlighting solutions—such as highlight.js, Prism.js, and Code Hike—I chose Shiki for several reasons:

• Uses the same TextMate grammar engine as VS Code
• Produces highly accurate and visually pleasing syntax highlighting
• Is static and build-time based, resulting in better performance
• Does not require additional runtime JavaScript for highlighting

#Rehype Pretty Code for Advanced Code Blocks

Rehype Pretty Code transforms MDX into HTML with specialized classes and attributes, enabling advanced code block features such as:

• Line numbers
• Line and word highlighting
• Inline diff and diff notation
• Focused and unfocused lines
• Error and warning highlighting
• ANSI color support
• Inline code with language support

These tools together form the foundation of Velora’s very rich code block experience.

#Key Features

Velora provides a complete blogging setup with the following built-in features:

• MDX-based content with custom React components

• Modern and responsive design using Tailwind CSS and Shadcn UI

• Pagination and structured content navigation

• Dynamic Open Graph image generation for SEO

• Very rich code block support, including:

  • Syntax highlighting with Shiki and Rehype Pretty Code
  • Line numbers and line highlighting
  • Word and group highlighting
  • Inline diff and diff notation
  • Code groups and nested code blocks
  • Copy button, title bar, and custom language labels

• Docker support for consistent development environments

• Velite integration for a type-safe content pipeline

• Giscus integration for discussion and comments

• Built-in analytics support (Umami, Google Analytics, PostHog)

• CI/CD pipeline using GitHub Actions

• Semantic Release for automated versioning

#Relationship with Website Portfolio V3

Although Velora is fully open-source, my Website Portfolio V3 repository is closed-source.

Velora acts as the primary foundation for Portfolio V3, but the portfolio version includes additional:

• Layout customizations
• Project-specific features
• Navigation and content structure tailored for a portfolio use case

Velora, on the other hand, is intentionally focused on being a general-purpose blog template, making it easier for others to adopt and extend.

#What I Learned

Through the development of Velora, I gained deeper insights into:

• Building a modern MDX content pipeline
• Designing type-safe content systems using Velite and Zod
• Advanced syntax highlighting and code rendering techniques
• Performance considerations for static vs runtime highlighting
• Structuring an open-source project for extensibility
• Maintaining a clean separation between a reusable template and a customized production website

#Why This Project Matters

Velora is more than just a template—it represents my exploration into modern technical writing platforms and developer-focused UX.

This project matters because it:

• Solves real problems in technical blogging
• Encourages reuse and customization through open source
• Demonstrates thoughtful tooling and architectural decisions
• Serves as a foundation for both personal and community-driven projects

#Conclusion

Velora is an open-source blog template that combines a modern content pipeline, exceptionally rich code blocks, and developer-friendly architecture.

It reflects my approach to building tools that are practical, maintainable, and designed with developers in mind, while also serving as the backbone for my personal portfolio and future content-driven projects.