Glimmer ✨

Stylized Markdown Rendering for the Terminal, Built in Crystal.

Glimmer is a command-line tool and library that renders Markdown documents with rich styling directly in the terminal. Inspired by Charmbracelet's Glow, Glimmer brings beautiful markdown rendering to the Crystal ecosystem.

Features

• Beautiful Rendering: Rich ANSI-styled output with support for headings, code blocks, lists, and more
• Syntax Highlighting: Language-aware highlighting for Crystal, Ruby, JavaScript, JSON, Shell, and more
• Multiple Themes: Built-in themes (dark, light, ascii) with custom theme support
• TUI Mode: Interactive file browser and pager for browsing markdown files
• Flexible Input: Read from files, URLs, GitHub/GitLab repos, or stdin
• Terminal Detection: Automatic color profile detection and adaptive styling
• GitHub/GitLab Integration: Fetch READMEs directly from repository URLs
• Emoji Support: Expand emoji shortcodes like 😄 to 😊
• Lightweight: Single binary with no runtime dependencies

Installation

From Source

git clone https://github.com/amscotti/glimmer
cd glimmer
shards build --release

The binary will be available at bin/glimmer.

Prerequisites

• Crystal >= 1.19.1

Usage

Basic Usage

# Render a markdown file
glimmer README.md

# Read from stdin
echo "# Hello World" | glimmer -

# Fetch from GitHub
glimmer github.com/crystal-lang/crystal

# Use a specific theme
glimmer -s light README.md

# Set custom width (default is 78)
glimmer -w 60 README.md

# Use system pager
glimmer -p README.md

TUI Mode

Run without arguments to launch the interactive file browser:

glimmer

This will:

• Show markdown files in the current directory
• Allow navigation with arrow keys or vim-style (j/k)
• Filter files with /
• Browse and read files in a scrollable pager
• Support less-compatible keybindings

TUI Keybindings

File Browser:

• ↑/↓ or k/j: Navigate files
• Enter or l: Open file/enter directory
• h: Go to parent directory
• g: Go to top of list
• G: Go to bottom of list
• /: Filter files
• ?: Show help
• q or Ctrl+C: Quit

Pager:

• ↑/↓ or k/j: Scroll up/down
• Space/PgDn: Page down
• b/PgUp: Page up
• d/Ctrl-D: Half page down
• u/Ctrl-U: Half page up
• Home/End: Go to top/bottom
• g: Go to top
• G: Go to bottom
• ?: Show help
• q or Esc: Return to browser

Configuration

Create and edit the config file:

glimmer config

Configuration options (stored in ~/.config/glimmer/glimmer.yml):

# Glimmer configuration file
# Available styles: auto, dark, light, ascii
# Set width to 0 for automatic detection

style: auto
width: 0
pager: false

Themes

Available themes:

• dark: Dark theme optimized for dark terminal backgrounds (default)
• light: Light theme optimized for light terminal backgrounds
• ascii: Plain ASCII output with no colors or Unicode characters
• auto: Defaults to dark theme (terminal background detection planned)

Supported Markdown Elements

Glimmer supports standard CommonMark Markdown plus:

• Headings (H1-H6)
• Paragraphs and text formatting
• Bold and italic text
• Inline code and code blocks
• Syntax highlighting in code blocks
• Unordered and ordered lists (including nested lists)
• Task lists (- [ ] and - [x])
• Blockquotes
• Links and images
• Horizontal rules
• Emoji shortcodes (:emoji_name:)

Code Block Syntax Highlighting

Highlighting is supported for:

• Crystal (crystal, cr)
• Ruby (ruby, rb)
• JavaScript/TypeScript (javascript, js, typescript, ts)
• JSON (json)
• Shell/Bash (shell, bash, sh, zsh)
• Python (python, py)
• Go (go, golang)
• Rust (rust, rs)
• C (c, h)
• SQL (sql)
• YAML (yaml, yml)
• HTML (html, htm)
• CSS (css)
• Dockerfile (dockerfile)
• Makefile (makefile, make)

Performance

Glimmer is designed to be fast and efficient:

• Parses and renders typical markdown files (< 100KB) in under 100ms
• Minimal memory footprint
• Efficient ANSI output generation
• Optimized for large terminal displays

Library Usage

Glimmer can be used as a library in your own Crystal applications.

Add the Dependency

Add Glimmer to your shard.yml:

dependencies:
  glimmer:
    github: amscotti/glimmer

Then run shards install.

Basic Rendering

require "glimmer"

markdown = "# Hello World\n\nThis is **bold** and *italic* text."

renderer = Glimmer::Renderer::TermRenderer.new(
  theme: Glimmer::Style::Theme.dark,
  width: 80
)
puts renderer.render(markdown)

Choosing a Theme

# Dark theme (default) - for dark terminal backgrounds
renderer = Glimmer::Renderer::TermRenderer.new(theme: Glimmer::Style::Theme.dark)

# Light theme - for light terminal backgrounds
renderer = Glimmer::Renderer::TermRenderer.new(theme: Glimmer::Style::Theme.light)

# ASCII theme - no colors or unicode, plain text only
renderer = Glimmer::Renderer::TermRenderer.new(theme: Glimmer::Style::Theme.ascii)

Color Profile Control

By default, Glimmer auto-detects your terminal's color capabilities. You can override this:

# Force 256-color output
renderer = Glimmer::Renderer::TermRenderer.new(
  profile: Glimmer::Style::ColorProfile::ANSI256
)

# Force true color (24-bit)
renderer = Glimmer::Renderer::TermRenderer.new(
  profile: Glimmer::Style::ColorProfile::TrueColor
)

# Force plain ASCII (no ANSI codes)
renderer = Glimmer::Renderer::TermRenderer.new(
  profile: Glimmer::Style::ColorProfile::Ascii
)

Syntax Highlighting

Code blocks with a language fence are automatically highlighted:

markdown = <<-MD
```ruby
def greet(name)
  puts "Hello, #{name}!"
end
```
MD

renderer = Glimmer::Renderer::TermRenderer.new
puts renderer.render(markdown)

You can also use the highlighting system directly:

code = "def hello; puts 'hi'; end"
lexer = Glimmer::Highlight::LexerRegistry.for_language("ruby")

if lexer
  tokens = lexer.tokenize(code)
  output = Glimmer::Highlight::Formatter.format(
    tokens,
    Glimmer::Style::Theme.dark,
    Glimmer::Style::ColorProfile::TrueColor
  )
  puts output
end

Emoji Expansion

text = "Hello 👋 welcome 🚀"
puts Glimmer::Emoji.expand(text)
# => "Hello 👋 welcome 🚀"

Development

Setup

# Clone the repository
git clone https://github.com/amscotti/glimmer
cd glimmer

# Install dependencies
shards install

# Run tests
crystal spec

# Run linter
bin/ameba

# Format code
crystal tool format

# Run all checks
make check

# Build for development
shards build

# Build optimized release binary
shards build --release

Running Locally

# Build and run
crystal run src/glimmer/cli.cr -- README.md

# Or build then run
shards build
./bin/glimmer README.md

Project Structure

.
├── src/
│   ├── glimmer.cr              # Main entry point
│   └── glimmer/
│       ├── style.cr            # ANSI styling system
│       ├── style/              # Color profiles, themes, style primitives
│       ├── emoji.cr            # Emoji shortcode expansion
│       ├── highlight.cr        # Syntax highlighting
│       ├── highlight/          # Lexers for various languages
│       ├── renderer.cr         # Markdown rendering engine
│       ├── renderer/           # TermRenderer, WordWrapper
│       ├── tui.cr              # Terminal UI module
│       ├── tui/                # Input, Screen, FileBrowser, Pager, App
│       ├── cli.cr              # Command-line interface
│       ├── cli/                # Config management
│       └── source.cr           # Input source handlers
│           ├── file_source.cr
│           ├── stdin_source.cr
│           └── url_source.cr
├── spec/                       # Test files
├── Makefile                    # Build tasks
└── shard.yml                   # Dependencies

Architecture

Glimmer is structured in layers:

1. Style Layer (Glimmer::Style): ANSI color profiles, style primitives, and themes
2. Emoji Layer (Glimmer::Emoji): Emoji shortcode expansion
3. Highlight Layer (Glimmer::Highlight): Syntax highlighting for code blocks
4. Renderer Layer (Glimmer::Renderer): Markdown AST to ANSI transformation
5. TUI Layer (Glimmer::TUI): Interactive terminal user interface
6. CLI Layer (Glimmer::CLI): Argument parsing, configuration, and coordination
7. Source Layer (Glimmer::Source): Input abstraction for files, URLs, and stdin

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork it (https://github.com/amscotti/glimmer/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Development Guidelines

• Follow Crystal's official style guide
• Run make check before committing; it validates formatting, lint, specs, and a development build
• Add tests for new features
• Update documentation as needed

Changelog

v0.1.0 (2026-02-06)

• Initial release
• Full CommonMark Markdown support
• Syntax highlighting for 15 languages
• Three built-in themes (dark, light, ascii)
• Interactive TUI with file browser and pager
• GitHub/GitLab URL support
• Emoji shortcode expansion
• Configuration file support

Roadmap

• Custom theme loading from JSON
• File watching for live reload
• Full-text search in TUI
• Export to HTML/PDF

Development Phases

• Phase 1: Project Foundation
• Phase 2: ANSI Styling Primitives
• Phase 3: Markdown Rendering Engine
• Phase 4: Syntax Highlighting
• Phase 5: CLI Interface
• Phase 6: File Watching & Enhanced Rendering
• Phase 7: TUI Mode
• Phase 8: Polish & Release

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by Glow from Charmbracelet
• Uses markd for Markdown parsing
• Built with Crystal

Contributors

• Anthony Scotti - creator and maintainer