🦝 true-zen.nvim

Clean and elegant distraction-free writing for NeoVim

 

true_zen_demo.mp4

 

📋 Features

• has 4 different modes to unclutter your screen:
  • Ataraxis: good ol' zen mode
  • Minimalist: disable ui components (e.g. numbers, tabline, statusline)
  • Narrow: narrow a text region for better focus
  • Focus: focus the current window
• customizable lua callbacks for each mode
• works out of the box
• integratons:
  • tmux
  • kitty
  • alacritty
  • twilight.nvim
  • nvim-lualine

 

📚 Requirements

• Neovim >= 0.5.0

 

📦 Installation

Install the plugin with your favourite package manager:

Packer.nvim

use({
	"Pocco81/true-zen.nvim",
	config = function()
		 require("true-zen").setup {
			-- your config goes here
			-- or just leave it empty :)
		 }
	end,
})

vim-plug

Plug 'Pocco81/true-zen.nvim'
lua << EOF
	require("true-zen").setup {
		-- your config goes here
		-- or just leave it empty :)
	}
EOF

 

⚙️ Configuration

true-zen comes with the following defaults:

{
	modes = { -- configurations per mode
		ataraxis = {
			shade = "dark", -- if `dark` then dim the padding windows, otherwise if it's `light` it'll brighten said windows
			backdrop = 0, -- percentage by which padding windows should be dimmed/brightened. Must be a number between 0 and 1. Set to 0 to keep the same background color
			minimum_writing_area = { -- minimum size of main window
				width = 70,
				height = 44,
			},
			quit_untoggles = true, -- type :q or :qa to quit Ataraxis mode
			padding = { -- padding windows
				left = 52,
				right = 52,
				top = 0,
				bottom = 0,
			},
			callbacks = { -- run functions when opening/closing Ataraxis mode
				open_pre = nil,
				open_pos = nil,
				close_pre = nil,
				close_pos = nil
			},
		},
		minimalist = {
			ignored_buf_types = { "nofile" }, -- save current options from any window except ones displaying these kinds of buffers
			options = { -- options to be disabled when entering Minimalist mode
				number = false,
				relativenumber = false,
				showtabline = 0,
				signcolumn = "no",
				statusline = "",
				cmdheight = 1,
				laststatus = 0,
				showcmd = false,
				showmode = false,
				ruler = false,
				numberwidth = 1
			},
			callbacks = { -- run functions when opening/closing Minimalist mode
				open_pre = nil,
				open_pos = nil,
				close_pre = nil,
				close_pos = nil
			},
		},
		narrow = {
			--- change the style of the fold lines. Set it to:
			--- `informative`: to get nice pre-baked folds
			--- `invisible`: hide them
			--- function() end: pass a custom func with your fold lines. See :h foldtext
			folds_style = "informative",
			run_ataraxis = true, -- display narrowed text in a Ataraxis session
			callbacks = { -- run functions when opening/closing Narrow mode
				open_pre = nil,
				open_pos = nil,
				close_pre = nil,
				close_pos = nil
			},
		},
		focus = {
			callbacks = { -- run functions when opening/closing Focus mode
				open_pre = nil,
				open_pos = nil,
				close_pre = nil,
				close_pos = nil
			},
		}
	},
	integrations = {
		tmux = false, -- hide tmux status bar in (minimalist, ataraxis)
		kitty = { -- increment font size in Kitty. Note: you must set `allow_remote_control socket-only` and `listen_on unix:/tmp/kitty` in your personal config (ataraxis)
			enabled = false,
			font = "+3"
		},
		alacritty = { -- increment font size in Alacrity. Requires v 0.10.0 or higher. Uses `alacritty msg` subcommand to toggle font size
			enabled = false,
			font = "24"
		},
		twilight = false, -- enable twilight (ataraxis)
		lualine = false -- hide nvim-lualine (ataraxis)
	},
}

🍤 Tweaks

Setting up Key Mappings

Additionally you may want to set up some key mappings for each true-zen mode:

local api = vim.api

api.nvim_set_keymap("n", "<leader>zn", ":TZNarrow<CR>", {})
api.nvim_set_keymap("v", "<leader>zn", ":'<,'>TZNarrow<CR>", {})
api.nvim_set_keymap("n", "<leader>zf", ":TZFocus<CR>", {})
api.nvim_set_keymap("n", "<leader>zm", ":TZMinimalist<CR>", {})
api.nvim_set_keymap("n", "<leader>za", ":TZAtaraxis<CR>", {})

-- or
local truezen = require('true-zen')
local keymap = vim.keymap

keymap.set('n', '<leader>zn', function()
  local first = 0
  local last = vim.api.nvim_buf_line_count(0)
  truezen.narrow(first, last)
end, { noremap = true })
keymap.set('v', '<leader>zn', function()
  local first = vim.fn.line('v')
  local last = vim.fn.line('.')
  truezen.narrow(first, last)
end, { noremap = true })
keymap.set('n', '<leader>zf', truezen.focus, { noremap = true })
keymap.set('n', '<leader>zm', truezen.minimalist, { noremap = true })
keymap.set('n', '<leader>za', truezen.ataraxis, { noremap = true })

API

require("true-zen.ataraxis") --[[
	.toggle() - toggle on/off the mode
	.running - `true` if the mode is on / `false` if the mode is off
--]]

require("true-zen.minimalist") --[[
	.toggle() - toggle on/off the mode
	.running - `true` if the mode is on / `false` if the mode is off
--]]

require("true-zen.narrow") --[[
	.toggle(line1, line2) - toggle on/off the mode
	vim.b.tz_narrowed_buffer - `true` if the mode is on / `false` if the mode is off
--]]

require("true-zen.focus") --[[
	.toggle() - toggle on/off the mode
	.running - `true` if the mode is on / `false` if the mode is off
--]]

--[[
	Each one offers the following functions too:
		.on() - turn on the mode
		.off() - turn off the mode
--]]

Callbacks

Every mode has callbacks available in their conf:

callbacks = {
	open_pre = nil,
	open_pos = nil,
	close_pre = nil,
	close_pos = nil
},

If its needed to disable certain callbacks use:

vim.g.tz_disable_mode_status_when

Where:

• mode: ataraxis, minimalist, narrow or focus
• status: open or close
• when: pre or pos

For example: Ataraxis mode uses Minimalist mode to hide some of NeoVim's UI components, so to stop Minimalist mode from running its open_pre callback this could be set within Ataraxis' config:

callbacks = {
	open_pre = function()
		-- do some stuff
		vim.g.tz_disable_minimalist_open_pre = true
	end,
},

 

🪴 Usage

• TZAtaraxis: toggle ataraxis mode
• TZMinimalist: toggle minimalist mode
• TZNarrow: toggle narrow mode
• TZFocus: toggle focus mode

 

📜 License

Koy is released under the MIT license, which grants the following permissions:

• Commercial use
• Distribution
• Modification
• Private use

For more convoluted language, see the LICENSE.