Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add clearer guide for statusline and tabuffline customization #212

Merged
merged 7 commits into from
Mar 30, 2024
Merged
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 34 additions & 21 deletions src/routes/docs/config/nvchad_ui.mdx
Original file line number Diff line number Diff line change
@@ -1,44 +1,55 @@
export const meta = {
title: "NvChad UI Configuration",
desc: "Manage NvChad's UI plugin configuration",
}
};

## Overview

NvChad's Ui plugin handles the following modules:

- Statusline
- Tabufline ( bufferline + tablist )
- NvDash ( Minimal dashboard )
- Term ( terminal handling )

## Statusline & tabufline
## Tabufline and Statusline

- Both of the plugins share the same way to customize their appearance.
- The order is a list of module names from default modules + your modules
- Removing a word in the order will remove that module
- Modules expect all its keys to be a function that returns a string.
- Statusline modules can also have strings!
- To highlight a string in statusline/tabufline,
wrap it with your highlight group, or the existing ones from the theme.

```lua
M.ui = {
tabufline = {
-- more opts
order = { "treeOffset", "buffers", "tabs", "btns", 'abc' },
modules = {
-- You can add your custom component
abc = function()
return "hi"
end,
}
},

statusline = {
-- more opts
modules = {
-- The default cursor module is override
cursor = function()
return "%#BruhHl#" .. " bruh " -- the highlight group here is BruhHl end,
}
}
}
```

<br/>
<br />

- Same goes for statuslines, but check its module order tables at [ui repo](https://github.com/NvChad/ui/blob/v2.5/lua/nvchad/stl/utils.lua)
- Statusline modules can also have strings!
- To highlight a string in statusline/tabufline, wrap it with your highlight group:
- For more customization, you should **read carefully** the default default sets of options in the [nvconfig.lua](https://github.com/NvChad/NvChad/blob/6833c60694a626615911e379d201dd723511546d/lua/nvconfig.lua#L21), then check the source code of their module order tables at [ui repo](https://github.com/NvChad/ui/blob/v2.5/lua/nvchad/stl/utils.lua).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you should mention that you're talking about statusline here ( for the order ) @LittleLegend-Pengiun


```lua
"%#BruhHl#" .. " bruh " -- the highlight group here is BruhHl
```

## Term

Expand All @@ -51,17 +62,17 @@ M.ui = {
size = 0.5 -- will work for split windows only

-- this will highlight the term window differently
hl* = "Normal:term,WinSeparator:WinSeparator",
hl* = "Normal:term,WinSeparator:WinSeparator",

id = "any string" -- needed for toggle/runner func
float_opts* = {} -- floating window options
clear_cmd = true -- needed for runner func*
}
```

<br/>
<br />

- *ones are optional
- \*ones are optional
- **pos** is required.
- **id** is needed for toggleable/runner terminals only
- If the optional opts are not provided then they will be taken from the `ui.term` table of your chadrc.
Expand All @@ -70,7 +81,7 @@ M.ui = {

- Create new terminal windows

```lua
```lua
require("nvchad.term").new { pos = "sp", size = 0.3 }
require("nvchad.term").new { pos = "vsp", cmd = "neofetch"}
```
Expand All @@ -79,7 +90,7 @@ require("nvchad.term").new { pos = "vsp", cmd = "neofetch"}

- Create toggleable terminal windows

```lua
```lua
require("nvchad.term").toggle({ pos = "float", id = "floatTerm", float_opts = {
border = "double",
}})
Expand All @@ -89,12 +100,13 @@ require("nvchad.term").toggle { pos = "sp", id = "xyz" }
require("nvchad.term").toggle { pos = "sp", id = "xyz2" }
require("nvchad.term").toggle { pos = "vsp", id = "floo" }
```
<br/>

<br />

- Mapping example
- We are mapping in "t" terminal mode too or else we'd have to go to normal mode and press `<A-i>` to toggle terminal.
- We are mapping in "t" terminal mode too or else we'd have to go to normal mode and press `<A-i>` to toggle terminal.

```lua
```lua
local map = vim.keymap.set

map({ "n", "t" }, "<A-i>", function()
Expand All @@ -108,19 +120,20 @@ end, { desc = "Terminal Toggle Floating term" })
- Calling the function again will run the `cmd` in that terminal window
- This can be seen as a code runner too! Usually useful if you want to see the result of some command

```lua
```lua
require("nvchad.term").runner {
pos = "vsp",
cmd = "python test.py",
id = "ekk",
clear_cmd = false
}
```
<br/>

<br />

- As Cmd can be a function too, here's a complex example :

```lua
```lua
require("nvchad.term").runner {
id = "boo",
pos = "sp",
Expand Down Expand Up @@ -149,6 +162,6 @@ These are few telescope extensions present in the UI plugin.

### Hidden Term picker

- If you close any terminal window by our close_buffer func i.e `<leader>x` then it'll just hide it
- If you close any terminal window by our close_buffer func i.e `<leader>x` then it'll just hide it
- You can un-hide them back by using `<leader>pt` keymap + press enter
- Command `Telescope terms`