joshuadanpeterson/typewriter.nvim

A Neovim plugin that emulates a typewriter, keeping the cursor centered on the screen for a focused writing experience.

Typewriter ✍️

A Neovim plugin that emulates a typewriter, keeping the cursor centered on the screen for a focused writing experience, and provides advanced code block navigation. 📝✨

Features ✨

• Keeps the cursor centered on the screen while you type or navigate. 📌
• Simple commands to enable, disable, and toggle the typewriter mode. 🔄
• Integrates with ZenMode and True Zen for a seamless distraction-free environment. 🧘
• :TWCenter command to center the view around the current code block or function using Tree-sitter. 🌳
• :TWTop command to move the top of the current code block to the top of the screen. ⬆️
• :TWBottom command to move the bottom of the current code block to the bottom of the screen. ⬇️
• Set keep_cursor_position to true in plugin config to keep cursor position relative to text when centering the view or using TWTop/TWBottom. 📌
• Set enable_notifications to true in plugin config to enable or disable notifications for actions like enabling/disabling typewriter mode, and aligning code blocks. 🔔
• Enable horizontal scrolling in Typewriter mode and center the cursor by setting enable_horizontal_scroll to true in the plugin configuration. ↔️
• Robust state tracking with is_typewriter_active(), set_typewriter_active(), and toggle_typewriter_active() functions for programmatic control. 🎛️
• TypewriterStateChanged event for reacting to Typewriter mode state changes in your own scripts or plugins. 🔄
• Comprehensive in-editor help documentation accessible via :help typewriter. 📚

TWCenter Demo 🎥

TWTop/TWBottom Demo 🎥

Horizontal Scrolling Demo 🎥

Installation 🔧

Dependencies 📦

Typewriter requires the following dependencies:

nvim-treesitter: Typewriter uses Tree-sitter to determine the current code block or function for the :TWCenter, :TWTop, and :TWBottom commands.

Make sure to install and configure nvim-treesitter before using Typewriter.

Using Packer

Add the following to your Packer configuration:

use {
    'nvim-treesitter/nvim-treesitter',
    run = ':TSUpdate'
}

use {
    'joshuadanpeterson/typewriter',
    requires = 'nvim-treesitter/nvim-treesitter',
    config = function()
        require('typewriter').setup()
    end
}

Using Lazy.nvim

Add the following to your Lazy.nvim configuration:

local lazy = require('lazy')

lazy.setup({
    -- Other plugins...

    {
        'nvim-treesitter/nvim-treesitter',
        build = ':TSUpdate',
    },

    {
        'joshuadanpeterson/typewriter',
        dependencies = {
            'nvim-treesitter/nvim-treesitter',
        },
        config = function()
            require('typewriter').setup()
        end,
        opts = {}
    },
})

Commands

Here is a markdown table that summarizes the commands available in Typewriter.nvim:

Command	Description
:TWEnable	Enable typewriter mode
:TWDisable	Disable typewriter mode
:TWToggle	Toggle typewriter mode on and off
:TWCenter	Center the view around the current code block or function using Tree-sitter
: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

These commands allow you to control the typewriter mode in Neovim and navigate code blocks, enhancing your writing and coding experience by maintaining focus and reducing distractions. The :TWCenter, :TWTop, and :TWBottom commands leverage Tree-sitter to intelligently manipulate the view of your code blocks, providing a more focused and flexible coding experience.

Supported Filetypes/Languages 🌐

Typewriter.nvim supports a variety of filetypes and languages, ensuring that your code navigation and centering experience is smooth across different programming environments. Below is a list of supported filetypes and languages. If you don't see your filetype listed, we still encourage you to download the plugin, as the common significant blocks section of the center_block_config.lua file supports many filetypes by default. If you download the plugin and it doesn't work as expected even with Treesitter installed and set up as a dependency, please open up an issue.

• PHP
• Go
• Rust
• JavaScript
• Python
• HTML
• CSS
• Bash
• SQL
• YAML
• JSON
• Dart
• Swift
• C++
• C#
• C
• Zig
• OCaml
• Java

If you don't see your filetype supported, propose it via issue or a pull request!

ZenMode and True Zen Configuration

ZenMode 🧘

ZenMode is a plugin for Neovim written by folke that provides a distraction-free coding environment by opening the current buffer in a new full-screen floating window. It hides various UI elements, works well with other floating windows, and integrates with plugins like Telescope and gitsigns. Typewriter integrates with ZenMode to automatically enable typewriter mode when entering ZenMode and disable it when exiting.

True Zen 🧘

True Zen is another plugin for Neovim written by pocco81 that offers multiple modes to unclutter your screen, including Ataraxis (a zen mode), Minimalist, Narrow, and Focus. True Zen allows you to disable UI components, narrow a text region for better focus, and customize callbacks for each mode. Typewriter integrates with True Zen, particularly the Ataraxis mode, to automatically enable typewriter mode when entering Ataraxis and disable it when exiting.

Packer

-- ~/.config/nvim/init.lua

require('packer').startup(function()
    -- Other plugins...

    use {
        'joshuadanpeterson/typewriter',
        config = function()
            require('typewriter').setup({
                enable_with_zen_mode = true,
                enable_with_true_zen = true,
                keep_cursor_position = true,
                enable_notifications = true,
                enable_horizontal_scroll = true,
            })
        end
    }

    use {
        'folke/zen-mode.nvim',
        opts = {
            on_open = function()
                vim.cmd('TWEnable')
            end,
            on_close = function()
                vim.cmd('TWDisable')
            end
        }
    }

    use {
        'pocco81/true-zen.nvim',
        config = function()
            require("true-zen").setup {
                modes = {
                    ataraxis = {
                        callbacks = {
                            open_pre = function()
                                vim.cmd('TWEnable')
                            end,
                            close_pos = function()
                                vim.cmd('TWDisable')
                            end
                        }
                    }
                }
            }
        end
    }
end)

Lazy.nvim

-- ~/.config/nvim/lua/plugins/init.lua

local lazy = require('lazy')

lazy.setup({
    -- Other plugins...

    {
        'joshuadanpeterson/typewriter',
        config = function()
            require('typewriter').setup({
                enable_with_zen_mode = true,
                enable_with_true_zen = true,
                keep_cursor_position = true,
                enable_notifications = true,
                enable_horizontal_scroll = true,
            })
        end,
        opts = {}
    },

    {
        'folke/zen-mode.nvim',
        opts = {
            on_open = function()
                vim.cmd('TWEnable')
            end,
            on_close = function()
                vim.cmd('TWDisable')
            end
        }
    },

    {
        'pocco81/true-zen.nvim',
        config = function()
            require("true-zen").setup {
                modes = {
                    ataraxis = {
                        callbacks = {
                            open_pre = function()
                                vim.cmd('TWEnable')
                            end,
                            close_pos = function()
                                vim.cmd('TWDisable')
                            end
                        }
                    }
                }
            }
        end,
        opts = {}
    }
})

Documentation 📚

Typewriter.nvim now comes with comprehensive documentation to help you make the most of its features:

• In-Editor Help: Access detailed documentation directly in Neovim by running :help typewriter.
• API Documentation: For developers looking to integrate with Typewriter.nvim, check out our API wiki article.
• State Tracking: Learn about the new state tracking functionality in our State Tracking wiki article.

Wiki 📚

• Home: Overview
• Commands
• Demos
• Enable Notifications
• Enabling Horizontal Scrolling
• Help Documentation
• Installation Guide
• Integration Guide
• Media
• State Tracking
• Tree‐sitter Integration for :TWCenter Command
• TW keep_cursor_position Feature
• Typewriter.nvim API

Inspiration 💡

This plugin was inspired by:

• stay-centered.nvim
• ZenMode
• True Zen
• Twilight
• Reddit comment by geckothegeek42

Credits 🙏

Special thanks to the following for their inspiration and ideas:

• The Reddit post "Typewriter Scrolling".
• The Obsidian plugin "Typewriter Mode".
• JotterPad Typewriter Scrolling
• Scrivener Typewriter Scrolling

License 📄

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

Contributing 🤝

Feel free to open up an issue or a pull request to contribute to the project.

typewriter.nvim's Issues

TWTop & TWBottom not working

Running either TWTop or TWBottom results in the following error

Error executing Lua callback: ...l/share/nvim/lazy/typewriter/lua/typewriter/commands.lua:141: attempt to call global 'get_expand_r
oot' (a nil value)
stack traceback:
        ...l/share/nvim/lazy/typewriter/lua/typewriter/commands.lua:141: in function 'move_to_top_of_block'
        ...are/nvim/lazy/typewriter/lua/typewriter/autocommands.lua:49: in function <...are/nvim/lazy/typewriter/lua/typewriter/aut
ocommands.lua:48>

The function get_expand_root is defined locally inside a previous code block and is therefore unavailable.

typewriter.nvim/lua/typewriter/commands.lua

Line 93 in 9e15168

local function get_expand_root(node)

BUG - Breaks default nvim behaviour which retains column when moving between lines

When moving between lines with j and k, and:

1. the next line has a shorter length than the current column
2. then the cursor moves to the end of the line.
3. when moving to the next line which has enough columns for the original cursor position (from 1)) -- vim will set it to that column instead of the max length of the previous line.

Step 3 is broken, which means the cursor follows this path:

Instead of:

Hopefully that makes sense

I've tried changing the config but its broken no matter what i set horizontal scroll and keep cursor position to:

modules["joshuadanpeterson/typewriter"] = {
  dependencies = {
    'nvim-treesitter/nvim-treesitter',
  },
  version = false,
  config = editor_config.typewriter,
}

....

function config.typewriter()
  local opts = {
    enable_horizontal_scroll = false,
    keep_cursor_position = true,
  }
  require("typewriter").setup(opts)
  vim.cmd(":TWEnable")
end

TWCenter centers the line, not the code block

It might be that I'm not using this plugin right, but when calling TWCenter the plugin centers the current line and not the code block as per documentation. I have treesitter installed and parsers installed.

Center horizontally?

I like this implementation you went with here! Listening to cursor events instead of remapping individual bindings is a cool idea

Could add zs and zH to center horizontally in addition to vertically (code). When in 'centering mode' I prefer also have the cursor horizontally centered as well

[Bug] TWDisable doesnt disable the autocmd that modifies the column

[Request] Option to silence notifications when toggling TW?

As the title says, could there be a config option that silences notifications? I just leave TW on and don't want to see the notification every time I start nvim

In normal mode with plugin installed using command $ - end of line not reached.

Using neovim v0.10.0, and installing the plugin using lazyvim with the following configuration:

return {
  {
    "joshuadanpeterson/typewriter",
    dependencies = "nvim-treesitter/nvim-treesitter",
    tag = "v0.1.5",
    opts = {},
    init = function()
      require("typewriter").enable()
    end,
  },
}

In later versions (0.2.0+) in normal mode, $ only moves the cursor to one less character than the end of the line. In version v0.1.5 the behaviour is correct.

v0.1.5:

abcd
   ^

v0.2.0+:

abcd
  ^

This for example $A results in insert mode before end of line. meaning the result in v0.2.0+ would be abc<inserted characters here>d instead of abcd<inserted characters here>.

Correct behaviour is restored either by using v0.1.5 or uninstalling the plugin.

Docs are missing

Tried to run :help typewriter but got an error E429: File "/home/rasmus/.local/share/nvim/lazy/typewriter/doc/typewriter.txt" does not exist. Looked in the repo and there seems to be only tags-file in the docs folder.

[Bug] Conflict with nvim-flash

Sometimes when using fFtT Ss motions -- the cursor is not placed next to the target match. Is there a way this could be fixed please? I tried configuring flash myself but there's no hooks to listen for a search being started or ending so couldn't use an autocmd

I think the autocmd in this plugin adjusts the column, the line is never wrong so it might be to do with the code that remembers a target column

https://github.com/folke/flash.nvim

Searching doesn't move cursor to the correct place

I think #17 introduced a bug which makes the cursor stay in it's place even when searching.

Steps to reproduce:

1. Open the config file
2. Search for M with /M
3. Jump to next result with n
4. Cursor is in the wrong place

My config file:

local M = { 'joshuadanpeterson/typewriter.nvim' }

M.opts = {}

return M

local M = { 'joshuadanpeterson/typewriter.nvim' }
      ^
      First match

M.opts = {}

return M

local M = { 'joshuadanpeterson/typewriter.nvim' }

M.opts = {}
^     ^
|     Cursor position
Second match

return M