package

github.com/amscotti/glimmer

0.1.0 / published Mar 8, 2026 / repository

A command-line tool and library for rendering Markdown documents with rich styling directly in the terminal. Inspired by Charmbracelet's Glow.

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 :smile: 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 :wave: welcome :rocket:"
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

  • [x] Phase 1: Project Foundation
  • [x] Phase 2: ANSI Styling Primitives
  • [x] Phase 3: Markdown Rendering Engine
  • [x] Phase 4: Syntax Highlighting
  • [x] Phase 5: CLI Interface
  • [ ] Phase 6: File Watching & Enhanced Rendering
  • [x] Phase 7: TUI Mode
  • [x] 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

API

  • Glimmer

    Glimmer ✨ — Stylized Markdown Rendering for the Terminal, Built in Crystal