remark vs. shiki

remark is a powerful and extensible Markdown processor designed for transforming Markdown into various other formats. Its core philosophy revolves around the concept of the Markdown Abstract Syntax Tree (AST) and a plugin-driven architecture, making it ideal for developers who need fine-grained control over the Markdown parsing and transformation pipeline. This approach appeals to those building custom content processing systems, static site generators, or tooling that requires deep integration with Markdown.

Shiki, on the other hand, is primarily a syntax highlighter. Its focus is on taking code snippets, often within a Markdown context, and rendering them with beautiful, accurate, and themeable syntax highlighting. Shiki's target audience includes developers building documentation sites, blogs, or any application where code presentation is a critical user experience factor. It aims to provide a seamless and visually appealing way to display code.

A fundamental architectural difference lies in their primary responsibilities. remark operates on a full Markdown document, parsing it into an AST that can then be traversed and modified by plugins. This makes it a general-purpose Markdown manipulation tool. Shiki, while it might process Markdown to find code blocks, fundamentally operates on the code itself, applying highlighting rules based on TextMate grammars.

Another significant technical difference is their extension and plugin models. remark boasts a vast ecosystem of plugins that extend its capabilities for parsing, transforming, and serializing Markdown. This allows for adding support for different Markdown flavors, custom syntaxes, or complex transformations. Shiki's extensibility focuses more on themes and language support, allowing users to customize the visual appearance and recognize a wide array of programming languages.

In terms of developer experience, remark offers a flexible but potentially steeper learning curve due to its AST-centric approach and the sheer volume of available plugins. Understanding how to chain plugins and manipulate the AST is key. Shiki generally provides a more straightforward developer experience for its core function; integrating syntax highlighting is often a matter of configuration and theme selection, making it quicker to get started with its primary use case.

Performance and bundle size considerations reveal a notable divergence. remark is remarkably lightweight, with a very small unpacked and gzipped size, indicating a minimal dependency footprint for its core functionality. This is crucial for applications where package size is a significant concern. Shiki, while still performant for its task, is considerably larger due to its inclusion of language grammars and theme data, which are necessary for its comprehensive highlighting capabilities.

Practically speaking, choose remark when you need to process, convert, or generate Markdown content in a programmatic and controlled manner. This is suitable for building custom Markdown parsers, transforming Markdown to HTML with specific rules, or integrating Markdown processing into a larger content pipeline. Consider remark for its robust AST manipulation and extensive plugin ecosystem.

Select Shiki when your primary goal is to display code snippets with high-quality syntax highlighting across various programming languages. It excels in documentation sites, educational platforms, or any web application where code readability and aesthetic presentation are paramount. Shiki's strength lies in its accurate language parsing and theme support, offering a visually polished developer experience for code presentation.

For scenarios involving both Markdown processing and code highlighting, a common pattern is to use remark to parse and transform the Markdown document, potentially extracting code blocks, and then pass those code blocks to Shiki for syntax highlighting. This complementary usage allows developers to leverage the strengths of each package: remark for content structure and Shiki for code presentation. The flexibility of remark's plugin system might even allow for direct integration of Shiki's highlighting capabilities within the remark processing pipeline, though this would require custom plugin development.