From 73b7e671e0d95430e4bc5f1538e804bdbe96580f Mon Sep 17 00:00:00 2001 From: max397574 Date: Fri, 10 Dec 2021 17:57:12 +0100 Subject: docs(readme): rewrite --- readme.md | 262 ++++++++++++++++++++++++++++---------------------------------- 1 file changed, 118 insertions(+), 144 deletions(-) (limited to 'readme.md') diff --git a/readme.md b/readme.md index 971b407..0142759 100644 --- a/readme.md +++ b/readme.md @@ -1,10 +1,10 @@
- + # 🔧startup.nvim The fully customizable greeter for neovim - +
✨Features @@ -12,10 +12,11 @@ The fully customizable greeter for neovim * Fully customizable * Themes -* Easy Customization with building blocks +* 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 is needed. @@ -33,12 +34,8 @@ use { ⚙️Customization ------------- - - -Call the setup function with your configurations - -It is recommended to use a file in the setup function. This can be done like this: +Call the setup function with your configurations. ```lua -- lua and packer.nvim @@ -47,154 +44,104 @@ use { "startup-nvim/startup.nvim", requires = {"nvim-telescope/telescope.nvim", "nvim-lua/plenary.nvim"}, config = function() - require"startup".setup(require"configs.startup") -- recommended to use a file for this + require"startup".setup({ + section_1 =
-- for the structure of a section see below + section_2 =
-- as much sections as you like + options = { + mapping_keys = true, -- display mapping (e.g. ff) + + -- if < 0 fraction of screen width + -- if > 0 numbers of column + cursor_column = 0.5 + + after = function() -- function that gets executed at the end + + 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 = "", + open_file = "o", + open_file_split = "", + open_section = "", + 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 + }) end } ``` -Here the file would be located at `/lua/configs/startup.lua`. -The file has to return settings. - -For one of the default themes this can be done like this: (example with the startify theme) - +You could also put the configurations into a file. +For example `/lua/config/startup_nvim.lua`. +The file should then look like this: +```lua +local settings = {} +return settings +``` +The plugin setup should then require the file: ```lua - require"startup".setup({theme = "evil"}) +use { + "startup-nvim/startup.nvim", + requires = {"nvim-telescope/telescope.nvim", "nvim-lua/plenary.nvim"}, + config = function() + require"startup".setup(require"configs.startup_nvim") + end +} ``` -This searches for themes in lua/startup/themes. -You can also put your own themes in there or override one of the default themes. - -These themes are currently available: -* dashbaord -* startify -* evil The filetype of the startup screen is `startup`. You can use this to disable plugins like statuslines. -### 🏗️The basic structure of the settings +### The Structure of a section ```lua --- General structure of the settings -settings = { - section_1 =
-- as much sections as you like - section_2 =
- options = { - mapping_keys = true/false, -- display mapping (e.g. ff) - -- if < 0 fraction of screen width - -- if > 0 numbers of column - cursor_column = - after = function() end -- function that gets executed at the end - empty_lines_between_mappings = true/false, -- add an empty line between mapping/commands - disable_statuslines = true/false -- disable status and bufferlines - paddings = , - } - mappings = { - -- keys in normal vim mapping format e.g. - -- string - execute_command = , - open_file = , - open_file_split = , - open_section = , - open_help = , - }, - colors = { - background = , -- hex color code - folded_section = , -- the colors of the folded section titles - -- this can also be changed with the `StartupFoldedSection` highlight group - } - parts = {"section_1", "section_2"} -- all sections in order -} - --- Structure of a section section = { - type = , - oldfiles_directory = true/false, - align = , - fold_section = true/false, --whether to fold or not - title = , - margin = <margin>, - content = <content>, - highlight = <highlight>, - default_color = <color>, - oldfiles_amount = <amount>, + -- "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 mappings 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 < 0 fraction of screen width + -- if > 0 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 in the format: + -- {[<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 } +``` --- the padding before each section --- table with integers -paddings = { - <padding_before_section_1>, -- for as as many sections as you have - <padding_before_section_2>, -} - --- a hex color --- e.g. "#FF000D" --- string -color = <color> - --- text: just text will be displayed - --- mapping: commands/mapping which will be displayed --- those can be executed with <CR> --- the mappings can be used - --- oldfiles: oldfiles will be displayed --- those can be opened with 'o' --- you can specify the amount of oldfiles and whether to display only one from the current directory --- string -type = "text"/"mapping"/"oldfiles" - --- display only oldfiles of current directory --- only relevant if type = "oldfiles" --- boolean -oldfiles_directory = true/false - --- how to align the section --- string -align = "left"/"center"/"right" - --- whether the section should be "folded" with the title <title> --- title must be set --- string -fold_section = true/false - --- title of folded section --- string -title = <title> - --- only relevant if alignment is left or right --- if < 0 fraction of screen width --- if > 0 numbers of column --- integer or float -margin = <margin> - --- when type = "olfiles" -> leave empty --- when type = "mapping" -> table with the format -{ - [<displayed_command_name>] = {<command>, <mapping>} -} - --- when type = "text" -> table with strings of text --- those can be returned by a function -content = <content> - --- the highlight group to highlight the section with --- leave empty to use a color --- string -highlight = highlight_group - --- color used if no highlight group is specified (highlight = "") --- hex color --- string -default_color = <color>, +### Buildingblocks --- the amount of oldfiles to be displayed --- integer -oldfiles_amount = <amount>, +You can use some functions from `lua/startup/functions.lua`. +For that you would use: +```lua +type = "text", +content = function() + require("startup.functions").function_name() + end, ``` -### Buildingblocks -<!-- TODO: --> +The functions are documented in `:help startup_nvim.functions`. ### Examples <details> @@ -236,7 +183,7 @@ local function time() return {clock,date} end -setting = { +settings = { ... content = time() ... @@ -268,17 +215,33 @@ content = { Check out the [themes](https://github.com/startup-nvim/startup.nvim/tree/master/lua/startup/themes) for full examples. -👀Screenshots ---------------- -### The themes +🎨The themes +---------- + +At the moment there are three themes: +- dashboard (default) +- evil +- startify + +You can use themes like this: + +```lua +require("startup").setup({theme = "dashboard"}) -- put theme name here +``` #### Dashbaord +The dashboard theme is a simple theme with some commands and a header. + #### Startify -Customize bookmarks with vim.g.startup_booksmarks -e.g. +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`: ```lua vim.g.startup_bookmarks = { ["Q"] = '~/.config/qtile/config.py', @@ -289,7 +252,18 @@ vim.g.startup_bookmarks = { } ``` -#### Evil Startup +#### 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`. Credits ------- -- cgit v1.2.3