Home

Typewriter.nvim: Advanced Cursor Centering for Neovim

Introduction

Welcome to Typewriter.nvim, a powerful Neovim plugin designed to emulate the classic typewriter experience while providing advanced code navigation features. This plugin keeps your cursor centered on the screen as you type or navigate, ensuring a focused and distraction-free environment for both writing and coding.

Inspired by typewriter scrolling modes found in tools like Obsidian, Scrivener, and JotterPad, Typewriter.nvim brings a refined typewriter experience to Neovim, tailored for modern users.

Overview

Typewriter.nvim is particularly beneficial for those who prefer a minimalist setup and want to maintain focus during long writing or coding sessions. By centering the cursor, the plugin eliminates constant scrolling, allowing you to immerse fully in your tasks.

The plugin seamlessly integrates with popular Neovim plugins like ZenMode and True Zen, known for creating distraction-free environments. It can automatically enable typewriter mode when entering these zen modes and disable it when exiting, ensuring an uninterrupted and efficient workflow.

Features

1. Centered Cursor: Maintains the cursor at the center of the screen during typing and navigation.
2. Integration: Seamless integration with Zen Mode and True Zen for an enhanced distraction-free environment.
3. Code Block Navigation: Advanced navigation features for code blocks using Tree-sitter.
4. Customizable Behavior: Flexible configuration options to tailor the plugin to your workflow.
5. State Management: Robust state tracking for programmatic control and integration with other plugins.

Core Modules

1. Commands (typewriter.commands)

Provides the core functionality:

• center_cursor(): Centers the cursor vertically on the screen.
• enable_typewriter_mode(): Activates typewriter mode.
• disable_typewriter_mode(): Deactivates typewriter mode.
• toggle_typewriter_mode(): Switches between enabled and disabled states.
• center_block_and_cursor(): Centers the current code block and cursor.
• move_to_top_of_block(): Aligns the top of the current code block with the top of the screen.
• move_to_bottom_of_block(): Aligns the bottom of the current code block with the bottom of the screen.

2. Configuration (typewriter.config)

Handles configuration options:

• default_config: Default configuration options.
• config: Current active configuration.
• config_setup(user_config): Merges user configuration with default options.
• get_config(): Retrieves the current configuration.

3. Utilities (typewriter.utils)

Provides utility functions:

• notify(message): Displays notifications to the user.
• center_cursor_horizontally(): Centers the cursor horizontally if enabled.
• is_typewriter_active(): Checks if Typewriter mode is active.
• set_typewriter_active(active): Sets the Typewriter mode state.
• toggle_typewriter_active(): Toggles Typewriter mode on/off.

4. Center Block Configuration (typewriter.utils.center_block_config)

Defines which code blocks should be centered:

• expand: Table mapping syntax tree node types to boolean values.
• should_expand(node_type): Checks if a given node type should be expanded and centered.

5. Autocommands (typewriter.autocommands)

Sets up user commands and autocommands:

• autocmd_setup(): Creates user commands and sets up autocommands for integration with other plugins.

Installation and Setup

Installation is straightforward using popular package managers like Packer or Lazy.nvim. Once installed, add the following to your Neovim configuration:

require('typewriter').setup({
    enable_with_zen_mode = true,
    keep_cursor_position = true,
    -- Add other configuration options as needed
})

User Commands

• :TWEnable: Enable typewriter mode
• :TWDisable: Disable typewriter mode
• :TWToggle: Toggle typewriter mode
• :TWCenter: Center the current code block and cursor
• :TWTop: Move the top of the current code block to the top of the screen
• :TWBottom: Move the bottom of the current code block to the bottom of the screen

Customization and Integration

Customize Typewriter.nvim by modifying configuration options:

require('typewriter.config').config_setup({
    enable_with_zen_mode = false,
    enable_notifications = true,
    -- Add other custom options here
})

Integrate with other plugins or custom scripts using the TypewriterStateChanged event:

vim.api.nvim_create_autocmd("User", {
    pattern = "TypewriterStateChanged",
    callback = function()
        -- Your custom logic here
    end
})

Conclusion

Typewriter.nvim enhances your Neovim editing experience by providing a focused, distraction-free environment with advanced code navigation features. Whether you're writing prose or code, this plugin helps keep your attention centered on your current task.

We hope you enjoy using Typewriter.nvim and find it beneficial to your workflow. Your feedback and contributions are always welcome as we strive to make this plugin even better. Happy typing!