readme.md

🔧startup.nvim

The fully customizable greeter for neovim

✨Features

• Fully customizable
• Themes
• Easier customization with building blocks

📦Installation

Use your favourite package manager and call setup function. Plenary.nvim is a dependency and must be installed. For the default setup telescope.nvim and telescope-file-browser.nvim are needed.

• Packer

use {
  "startup-nvim/startup.nvim",
  requires = {"nvim-telescope/telescope.nvim", "nvim-lua/plenary.nvim", "nvim-telescope/telescope-file-browser.nvim"},
  config = function()
    require"startup".setup()
  end
}

• Lazy.nvim

{
  "startup-nvim/startup.nvim",
  dependencies = { "nvim-telescope/telescope.nvim", "nvim-lua/plenary.nvim", "nvim-telescope/telescope-file-browser.nvim" },
  config = function()
    require "startup".setup()
  end
}

⚙️Customization

Call the setup function with your configurations.

require"startup".setup({
  section_1 = <section> -- for the structure of a section see below
  section_2 = <section> -- as much sections as you like
  options = {
      mapping_keys = true, -- display mapping (e.g. <leader>ff)

      -- if < 1 fraction of screen width
      -- if > 1 numbers of column
      cursor_column = 0.5,

      after = function() -- function that gets executed at the end
        <lua commands>
      end,
      empty_lines_between_mappings = true, -- add an empty line between mapping/commands
      disable_statuslines = true, -- disable status-, buffer- and tablines
      paddings = {1,2}, -- amount of empty lines before each section (must be equal to amount of sections)
  },
  mappings = {
    execute_command = "<CR>",
    open_file = "o",
    open_file_split = "<c-o>",
    open_section = "<TAB>",
    open_help = "?",
  },
  colors = {
    background = "#1f2227",
    folded_section = "#56b6c2", -- the color of folded sections
      -- this can also be changed with the `StartupFoldedSection` highlight group
  },
  parts = {"section_1", "section_2"} -- all sections in order
})

You could also put the configurations into a file. For example /lua/config/startup_nvim.lua. The file should then look like this:

local settings = {<settings>}
return settings

The plugin setup should then require the file:

use {
  "startup-nvim/startup.nvim",
  requires = {"nvim-telescope/telescope.nvim", "nvim-lua/plenary.nvim"},
  config = function()
    require"startup".setup(require"configs.startup_nvim")
  end
}

The filetype of the startup screen is startup. You can use this to disable plugins like statuslines.

The Structure of a section

section = {
    -- "text" -> text that will be displayed
    -- "mapping" -> create mappings for commands that can be used
    -- use mappings.execute_command on the commands to execute
    -- "oldfiles" -> display oldfiles (can be opened with mappings.open_file/open_file_split)
    type = "text", -- can be mapping or oldfiles
    oldfiles_directory = false, -- if the oldfiles of the current directory should be displayed
    align = "center", -- "center", "left" or "right"
    fold_section = false, -- whether to fold or not
    title = "title", -- title for the folded section
    -- if < 1 fraction of screen width
    -- if > 1 numbers of column
    margin = 5, -- the margin for left or right alignment
    -- type of content depends on `type`
    -- "text" -> a table with string or a function that requires a function that returns a table of strings
    -- "mapping" -> a table with tables in the format:
    -- {
    --   {<displayed_command_name>, <command>, <mapping>}
    --   {<displayed_command_name>, <command>, <mapping>}
    -- }
    -- e.g. {" Find File", "Telescope find_files", "<leader>ff" }
    -- "oldfiles" -> ""
    content = <content>
    highlight = "String", -- highlight group in which the section text should be highlighted
    default_color = "#FF0000", -- a hex color that gets used if you don't specify `highlight`
    oldfiles_amount = 5, -- the amount of oldfiles to be displayed
}

User Mappings

You can easily add your own mappings with a function. You just have to provide a table with keys, command pairs like this:

require"startup".create_mappings({
  ["<leader>ff"]="<cmd>Telescope find_files<CR>",
  ["<leader>lg"]="<cmd>Telescope live_grep<CR>"
})

Those mappings will automatically be added to the help.

Buildingblocks

You can use some functions from lua/startup/functions.lua. For that you would use:

type = "text",
content = function()
    require("startup.functions").function_name()
  end,

The functions are documented in :help startup_nvim.functions.

Examples

Content for type = "text", table

content = {
    "This is:",
    "Startup.nvim",
    "by max397574"
}

Content for type = "text", function

content = function()
    local clock = " " .. os.date "%H:%M"
    local date = " " .. os.date "%d-%m-%y"
    return {clock,date}
end

With a separate function:

local function time()
    local clock = " " .. os.date "%H:%M"
    local date = " " .. os.date "%d-%m-%y"
    return {clock,date}
end

settings = {
    ...
    content = time()
    ...
}

Content for type = "mapping"

content = {
  [" Find File"] = { "Telescope find_files", "<leader>ff" },
  [" Find Word"] = { "Telescope live_grep", "<leader>lg" },
  [" Recent Files"] = { "Telescope oldfiles", "<leader>of" },
  [" File Browser"] = { "Telescope file_browser", "<leader>fb" },
  [" Colorschemes"] = { "Telescope colorscheme", "<leader>cs" },
  [" New File"] = { "lua require'startup'.new_file()", "<leader>nf" },
},

Check out the themes for full examples.

🎨Themes

At the moment there are three themes:

• dashboard (default)
• evil
• startify

You can use themes like this:

require("startup").setup({theme = "dashboard"}) -- put theme name here

Dashboard

The dashboard theme is a simple theme with some commands and a header.

Startify

The startify theme is a theme like vim-startify. It has oldfiles, bookmarks and a random quote. You can open the oldfiles with the number written before it ([2] ~/.config/nvim/init.lua can be opened by pressing 2). You can open a bookmark with the key written in front of it.

Customize bookmarks with vim.g.startup_booksmarks:

vim.g.startup_bookmarks = {
  ["Q"] = '~/.config/qtile/config.py',
  ["I"] = '~/.config/nvim/init.lua',
  ["F"] = '~/.config/fish/config.fish',
  ["K"] = '~/.config/kitty/kitty.conf',
  ["A"] = '~/.config/alacritty/alacritty.yml',
}

Evil

The evil theme is just a bloated theme with oldfiles, commands, additional info and a quote.

Custom theme

You can put your theme in lua/startup/themes/my_theme.lua The file has to return settings with the structure like you put them into setup(). You can also overwrite a theme (e.g. dashboard). Just copy all the setting from it and change whatever you want. You can use some functions from lua/startup/functions.lua with require("startup.functions").function_name(). They are documented in :help startup_nvim.functions. The same applies to headers. Here you can use them with require("startup.headers").header_name. They are documented in :help startup_nvim.headers. A good tool to create your own headers is image to braille.

Conflicts with other plugins like auto-session

If this plugin conflict with other plugins you can disable it on startup. For this you need to set vim.g.startup_disable_on_startup to true. You can do that like this:

config = function()
    vim.g.startup_disable_on_startup = true
    require("startup").setup(require("configs.startup_nvim"))
end

You can still display it later then with :Startup display.

👀 Screenshots

Easily open Files (in splits)

Builtin Key Help (user mappings included)

Folds and commands with mappings

Credits

• Thanks to Binx, for making that logo for free!
  • Github
  • Reddit

Similar plugins:

• dashboard-nvim
• alpha-nvim
• vim-startify

❤️ Support

If you like the projects I do and they can help you in your life you can support my work with github sponsors. Every support motivates me to continue working on my open source projects.