Skip to content

Add comprehensive zen-mode with configurable margins #774

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Add comprehensive zen-mode with configurable margins #774

wants to merge 6 commits into from

Conversation

@zach-is-my-name
Copy link

@zach-is-my-name zach-is-my-name commented May 30, 2025 •
edited
Loading

Summary

This PR adds comprehensive zen-mode support to glow with configurable margins for comfortable reading, plus PAGER environment variable support for seamless integration with custom pagers.

Key Features

  1. Zen-mode flag (-z, --zen): Enables zen-mode with auto margins or accepts optional value for fixed character margins
  2. Configurable margins: Support for percentage-based or fixed character margins
  3. Auto-detection: Intelligent content width calculation based on terminal size
  4. PAGER environment variable support: Respects user's preferred pager instead of hardcoded less -R
  5. 🆕 Session-only behavior: Zen mode prevents config file persistence for clean, temporary usage

Usage Examples

# Enable zen-mode with auto margins
glow -z README.md

# Fixed 12-character margins
glow -z=12 README.md

# Custom pager with zen-mode
PAGER="less -H" glow -zp README.md

# Session-only styling (no config file created/modified)
glow -z -s tokyo-night README.md

✨ Session-Only Zen Mode Behavior

Major Enhancement: When using zen-mode (-z or -z=12), glow now operates in session-only mode for style and width settings:

No Config File Pollution

  • Style flags like -s tokyo-night don't create or modify config files
  • Width settings are ignored (zen mode uses terminal width)
  • Perfect for temporary styling without persistent changes

Clean User Experience

# These commands never touch your config file when using -z:
glow -z -s tokyo-night document.md
glow -z=15 -s dracula -p document.md

# Config file remains clean, zen centering always works

Backward Compatibility

  • Normal mode unchanged: glow -s tokyo-night still saves to config as before
  • Only zen mode (-z) enables session-only behavior
  • Existing configs and workflows remain unaffected

Technical Implementation

Session-Only Config Handling

  • Conditional viper flag binding skips style/width persistence in zen mode
  • Manual flag parsing for zen mode bypasses automatic config writing
  • Clean separation between session-only and persistent modes

Margin Priority Order

  1. CLI explicit: -z=12 (uses 12% margins)
  2. CLI + config: -z with zenMarginPercent: 15 in config (uses 15%)
  3. CLI default: -z with no config margin (uses 20% default)

Maximally Minimal Zen-Mode

This PR pairs perfectly with gwsw/less#629 which adds the -H/--hide-prompt option to less for accessibility. Together, these PRs enable a maximally minimal zen-mode reading experience:

# Ultimate distraction-free reading
PAGER="less -H" glow -z=12 -p document.md
  • glow: Centers content with comfortable margins
  • less -H: Hides the status line for cleaner display
  • Result: Pure, focused reading with zero visual noise

Technical Details

  • Uses glamour's native Document margin system for clean zen-mode rendering
  • Maintains compatibility with existing width and style settings (except width override)
  • Follows Unix conventions for pager selection via PAGER environment variable
  • Graceful fallback to less -R when PAGER is not set
  • Properly handles pager commands with arguments using strings.Fields()
  • Custom flag type supports both boolean (-z) and valued (-z=12) syntax
  • Session-only behavior prevents unwanted config file creation/modification

Testing

Tested with various terminal sizes, margin configurations, custom pagers, and config file combinations. Verified that zen mode with style flags creates no config files while maintaining all functionality. Works seamlessly with accessibility-focused pagers and provides clean session-only operation.

🤖 Generated with Claude Code

@zach-is-my-name @claude
Implement comprehensive zen-mode with configurable margins
558bea8 
This commit adds a complete zen-mode feature for Glow with:

## Features
- `--zen`/`-z` flag for zen-mode reading experience
- `--zen-width` flag for custom line width (default: auto-detected)
- `--zen-margin` flag for margin percentage (default: 20%)

## Implementation
- Auto-detects terminal width and applies percentage-based margins
- Universal compatibility across all terminal sizes (80-200+ columns)
- Uses Glamour's WithMargins() for proper text layout
- Configurable width and margin percentages for customization

## Examples
```bash
# Default zen-mode (20% margins, auto width)
glow -z README.md

# Custom margins
glow -z --zen-margin=30 README.md

# Custom width and margins
glow -z --zen-width=100 --zen-margin=25 README.md
```

Provides VSCode/Neovim-style zen reading experience with centered text
and comfortable margins for focused markdown consumption.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@zach-is-my-name zach-is-my-name requested a review from a team as a code owner May 30, 2025 18:29
@zach-is-my-name zach-is-my-name requested review from kujtimiihoxha and removed request for a team May 30, 2025 18:29
zach-is-my-name and others added 5 commits May 31, 2025 11:23
@zach-is-my-name @claude
fix: restore WithZenMode for proper centering
b12b571 
- Change from WithMargins() back to WithZenMode()
- Restores true centering behavior using glamour's native Document margin system
- WithMargins() only sets individual element margins, WithZenMode() provides global centering

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@zach-is-my-name @claude
fix: implement proper PAGER environment variable support for -p flag
44347ef 
- Respect PAGER environment variable as documented in README
- Fall back to 'less -r' when PAGER is not set (upstream specification)
- Parse pager commands with arguments using strings.Fields()
- Maintain backward compatibility with existing behavior

This completes the zen-mode implementation with proper pager integration
as specified in the upstream documentation.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@zach-is-my-name @claude
Fix zen-mode width detection with config files
8fd127a 
Zen-mode now properly detects terminal width even when config files
set explicit width values. This ensures zen-mode margins are calculated
based on actual terminal size rather than fixed config values.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@zach-is-my-name @claude
Implement -z=12 syntax for zen mode with config override behavior
47fd868 
## New Features
- **Custom zen flag type**: Supports both -z and -z=12 syntax as documented in PR
- **Optional margin values**: -z uses config/default margin, -z=12 uses explicit margin
- **Config file integration**: Priority order: CLI -z=12 > CLI -z + config > default

## Config Override Behavior
- **Width override**: Zen mode ignores config width and uses terminal width for proper centering
- **Style preservation**: Config style settings (tokyo-night, etc.) still respected
- **Margin integration**: -z without value uses config zenMarginPercent if available

## Validation & Safety
- **Conflict prevention**: Cannot use --width with --zen (returns clear error message)
- **Help documentation**: Updated zen flag help to warn about config width override
- **Backward compatibility**: Preserves existing width detection for non-zen usage

## Usage Examples
```bash
# Default zen mode (uses config margin or 20% default)
glow -z README.md

# Explicit margin percentage
glow -z=12 README.md

# Config integration (if zenMarginPercent: 15 in config)
glow -z README.md  # Uses 15% margins from config

# Error case
glow -z -w 100 README.md  # Returns error: cannot use --width with --zen
```

## Recommendation for Config Users
When using zen mode, set style/pager preferences as CLI flags instead of config:
```bash
glow -z=12 -s tokyo-night -p document.md
```
This avoids relying on config file width settings that zen mode overrides.

Fulfills PR description promise of "glow -z=12" syntax while maintaining
compatibility with existing glow/glamour width detection systems.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@zach-is-my-name @claude
Prevent config persistence in zen mode for session-only behavior
e561e9f 
When using zen mode (-z), style and width flags now operate in session-only mode without creating or modifying config files. This addresses the issue where `glow -z -s tokyo-night` would persist settings to ~/.config/glow/glow.yml, breaking the zen experience.

Changes:
- Conditional viper flag binding skips style/width when zen mode enabled
- Manual style flag handling in zen mode bypasses viper persistence
- Maintains full compatibility for non-zen mode users
- Enables true session-only zen mode operation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
gustavosbarreto pushed a commit to drera-labs/glow that referenced this pull request Jun 9, 2025
@caarlos0
feat(spin): --show-stdout --show-stderr (charmbracelet#774)
32786f7 
closes charmbracelet#362
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kujtimiihoxha kujtimiihoxha Awaiting requested review from kujtimiihoxha kujtimiihoxha is a code owner automatically assigned from charmbracelet/everyone

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@zach-is-my-name