Typewriter.nvim API

Table of Contents

1. Introduction
2. Core Functions
3. Utility Functions
4. Commands Module
5. Configuration Module
6. Center Block Configuration
7. User Commands
8. Events
9. Sample Keymap Examples
10. Further Documentation

Introduction

Typewriter.nvim is a Neovim plugin that provides typewriter-style scrolling and advanced code block navigation. This API documentation outlines the core functions, utilities, and configuration options available to users and developers.

Core Functions

Setup

require('typewriter').setup(opts)

Initializes the Typewriter.nvim plugin with the given options. This function must be called to configure the plugin and enable its features.

Options

• enable_with_zen_mode (boolean): Automatically enable typewriter mode when ZenMode is enabled.
• enable_with_true_zen (boolean): Automatically enable typewriter mode when True Zen is enabled.
• keep_cursor_position (boolean): Keep cursor position relative to text when centering the view or using TWTop/TWBottom.
• enable_notifications (boolean): Enable or disable notifications for actions like enabling/disabling typewriter mode, and aligning code blocks.
• enable_horizontal_scroll (boolean): Enable horizontal scrolling in Typewriter mode and center the cursor horizontally.

Example Usage

require('typewriter').setup({
    enable_with_zen_mode = true,
    enable_with_true_zen = true,
    keep_cursor_position = true,
    enable_notifications = true,
    enable_horizontal_scroll = false,
})

Utility Functions

State Management

local utils = require("typewriter.utils")

• utils.is_typewriter_active(): Check if Typewriter mode is currently active.
• utils.set_typewriter_active(active): Set the active state of Typewriter mode.
• utils.toggle_typewriter_active(): Toggle the active state of Typewriter mode.

Notifications

• utils.notify(message): Display a notification if enabled in the configuration.

Cursor Positioning

• utils.center_cursor_horizontally(): Center the cursor horizontally if horizontal scrolling is enabled.

Commands Module

local commands = require("typewriter.commands")

• commands.center_cursor(): Center the cursor on the screen.
• commands.enable_typewriter_mode(): Enable typewriter mode.
• commands.disable_typewriter_mode(): Disable typewriter mode.
• commands.toggle_typewriter_mode(): Toggle typewriter mode.
• commands.center_block_and_cursor(): Center the current code block and cursor.
• commands.move_to_top_of_block(): Move the top of the current code block to the top of the screen.
• commands.move_to_bottom_of_block(): Move the bottom of the current code block to the bottom of the screen.

Configuration Module

local config = require("typewriter.config")

• config.config_setup(user_config): Setup the configuration with user-provided options.
• config.get_config(): Get the current configuration.

Center Block Configuration

local center_block_config = require("typewriter.utils.center_block_config")

• center_block_config.expand: Table indicating which code blocks should be expanded and centered.
• center_block_config.should_expand(node_type): Get the expansion status for a given node type.

User Commands

Typewriter.nvim provides several commands to control the typewriter mode manually:

• :TWEnable: Enable typewriter mode.
• :TWDisable: Disable typewriter mode.
• :TWToggle: Toggle typewriter mode on and off.
• :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.

Events

Typewriter.nvim triggers a TypewriterStateChanged event when the state changes, which can be used for integration with other plugins or custom scripts:

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

Sample Keymap Examples

Here are some examples of how you can set up keymaps for Typewriter.nvim:

Basic Toggles

-- Enable Typewriter mode
vim.api.nvim_set_keymap('n', '<Leader>te', ':TWEnable<CR>', { noremap = true, silent = true })

-- Disable Typewriter mode
vim.api.nvim_set_keymap('n', '<Leader>td', ':TWDisable<CR>', { noremap = true, silent = true })

-- Toggle Typewriter mode
vim.api.nvim_set_keymap('n', '<Leader>tt', ':TWToggle<CR>', { noremap = true, silent = true })

Code Block Navigation

-- Center the current code block and cursor
vim.api.nvim_set_keymap('n', '<Leader>tc', ':TWCenter<CR>', { noremap = true, silent = true })

-- Move the top of the current code block to the top of the screen
vim.api.nvim_set_keymap('n', '<Leader>tT', ':TWTop<CR>', { noremap = true, silent = true })

-- Move the bottom of the current code block to the bottom of the screen
vim.api.nvim_set_keymap('n', '<Leader>tB', ':TWBottom<CR>', { noremap = true, silent = true })

Using Lua Functions Directly

local utils = require("typewriter.utils")
local commands = require("typewriter.commands")

-- Toggle Typewriter mode and print status
vim.api.nvim_set_keymap('n', '<Leader>tT', '', {
    noremap = true,
    silent = true,
    callback = function()
        local new_state = utils.toggle_typewriter_active()
        print("Typewriter mode is now: " .. (new_state and "active" or "inactive"))
    end
})

-- Center cursor with custom notification
vim.api.nvim_set_keymap('n', '<Leader>tC', '', {
    noremap = true,
    silent = true,
    callback = function()
        commands.center_cursor()
        utils.notify("Cursor centered")
    end
})

Integration with Other Plugins

-- Toggle Zen Mode and Typewriter mode together
vim.api.nvim_set_keymap('n', '<Leader>tz', '', {
    noremap = true,
    silent = true,
    callback = function()
        -- Assuming you're using the zen-mode plugin
        require("zen-mode").toggle()
        require("typewriter.commands").toggle_typewriter_mode()
    end
})

Further Documentation

For more detailed information about Typewriter.nvim's features, configuration options, and usage, you can access the comprehensive in-editor help documentation by running the following command in Neovim:

:help typewriter

This will open the full help file, which includes detailed explanations of all modules and their functions, a complete list of configuration options with descriptions, usage examples for each public function, information about integration with other plugins, and troubleshooting tips and best practices.

The help documentation is regularly updated to reflect the latest features and changes in Typewriter.nvim. It's an excellent resource for both new users looking to get started and experienced users seeking to maximize their use of the plugin.