Skip to content

Commit

Permalink
docs: update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@shellRaining
shellRaining committed May 1, 2023
1 parent 12e4e4d commit d9f5515
Show file tree
Hide file tree
Showing 4 changed files with 81 additions and 77 deletions.
69 changes: 36 additions & 33 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,70 +1,68 @@
<h1 align="center">hlchunk.nvim</h1>
<center><img width='400px' src='https://raw.githubusercontent.com/shellRaining/img/main/2305/01_hlchunk_logo.png'></center>
<h1 align='center'>hlchunk.nvim</h1>

<p align='center'>
<b>English</b> | <a href="https://github.com/shellRaining/hlchunk.nvim/blob/main/README.zh-CN.md">简体中文</a>
</p>

This is the lua implementation of [nvim-hlchunk](https://github.com/yaocccc/nvim-hlchunk), and add some new features like highlighting indentline, specially thanks [indent-blankline.nvim](https://github.com/lukas-reineke/indent-blankline.nvim), during the process of writing this plugin, this repo provided a lot of help and inspiration for me
## What can this plugin do

## brief
similar to [indent-blankline](https://github.com/lukas-reineke/indent-blankline.nvim), this plugin can highlight the indent line, and highlight the code chunk according to the current cursor position.

this plugin now have four parts (future will add more... `^v^`)
## What is the advantage of this plugin

1. hl_chunk
2. hl_indent
3. hl_line_num
4. hl_blank
1. more extensible
2. faster rendering speed (0.04 seconds per thousand renderings, with a line height of 50 lines)
3. more active maintenance (the author is a student with a lot of time to maintain this plugin, haha)

the first one is to highlight the current chunk, a chunk is defined as `the closest pair of curly braces and the code in between`, so it might not work very well in lua or python source code. In the future, I might define a chunk by using indentation (so, this plugin may become another `indent_blankline` in the future 😊)
## Brief introduction

the second one is to highlight indentline like `indent_blankline`, you can choose a different indent render mode, one is base treesitter, another is base on the number of blank. the advantage of treeitter is that it is very accurate, but it may have low performance, and doesn't support some filetype, such as markdown, if you choose the latter mode, it will render faster (maybe), but will have some issues in particular situation, example below.
this plugin now have five parts (future will add more... `^v^`)

<img width="400" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2303/01_hlchunk5.png">
1. chunk
2. indent
3. line_num
4. blank
5. context (experimental)

base on blank number
one picture to understand what these mods do

<img width="400" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2303/01_hlchunk6.png">
<img width='500' src='https://raw.githubusercontent.com/shellRaining/img/main/2305/01_intro.png'>

base on treesitter

the third one is similar to hl_chunk, the difference is that it will highlight line number, you can set front color or background color for it

the last one is hl_blank, which can highlight the blank with some funny char and style, you can see in the example below, you can find many useful chars in this website [Unicode Plus](https://unicodeplus.com/)

## example
## more details about each mod

<b><font color='red'> NOTE: you can click the picture to get more information about how to configure like this </font></b>

### hl_chunk
### chunk

<a href='./docs/en/chunk.md'>
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2303/08_hlchunk8.gif">
</a>

### hl_indent
### indent

<a href='./docs/en/indent.md'>
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2302/23_hlchunk2.png">
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2302/27_hlchunk4.png">
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2303/13_hlindent_bg.png">
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2305/01_indent.png">
</a>

### hl_line_num
### line_num

<a href='./docs/en/line_num.md'>
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2302/25_hlchunk3.png">
</a>

### hl_blank
### blank

<a href='./docs/en/blank.md'>
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2303/08_hlblank1.png">
<img width='500' src='https://raw.githubusercontent.com/shellRaining/img/main/2303/11_hlblank2.png'>
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2303/08_hlblank1.png">
</a>

## Requirements

neovim version `>= 0.7.0` (maybe, just test at this version)
neovim version `>= 0.7.0`

## Installation

Expand Down Expand Up @@ -97,6 +95,7 @@ The script comes with the following defaults:
{
chunk = {
enable = true,
use_treesitter = true,
support_filetypes = {
"*.ts",
"*.tsx",
Expand Down Expand Up @@ -126,13 +125,11 @@ The script comes with the following defaults:
indent = {
enable = true,
use_treesitter = false,
-- You can uncomment to get more indented line look like
chars = {
"│",
},
-- you can uncomment to get more indented line style
style = {
vim.fn.synIDattr(vim.fn.synIDtrans(vim.fn.hlID("Whitespace")), "fg", "gui"),
FN.synIDattr(FN.synIDtrans(FN.hlID("Whitespace")), "fg", "gui"),
},
exclude_filetype = {
dashboard = true,
Expand All @@ -150,7 +147,7 @@ The script comes with the following defaults:
line_num = {
enable = true,
support_filetypes = {
"..."
"..." -- same as chunk
},
style = "#806d9c",
},
Expand All @@ -170,7 +167,11 @@ The script comes with the following defaults:

<hr>

example:
</details>

<hr>

setup example:

```lua
require('hlchunk').setup({
Expand All @@ -181,10 +182,12 @@ require('hlchunk').setup({
"#8B00FF",
},
},
blank = {
enable = false,
}
})
```

</details>

## command

Expand Down
65 changes: 35 additions & 30 deletions README.zh-CN.md
View file
Original file line number Diff line number Diff line change
@@ -1,68 +1,68 @@
<center><img width='400px' src='https://raw.githubusercontent.com/shellRaining/img/main/2305/01_hlchunk_logo.png'></center>
<h1 align="center">hlchunk.nvim</h1>

<p align='center'>
<a href="https://github.com/shellRaining/hlchunk.nvim/blob/main/README.md">English</a> | <b>简体中文</b>
</p>

这是 [nvim-hlchunk](https://github.com/yaocccc/nvim-hlchunk) 的一个 lua 实现，并且添加了例如缩进高亮的功能，本项目特别感谢 [indent-blankline.nvim](https://github.com/lukas-reineke/indent-blankline.nvim)，在我编写这个插件的时候，这个仓库给我提供了很多帮助和灵感
## 这个插件可以做什么

## 简要概述

这个插件由四个部分组成，未来会添加更多的功能（笑）

1. hl_chunk
2. hl_indent
3. hl_line_num
4. hl_blank

第一部分是用来高亮当前代码块，在本项目中代码块的定义是当前光标所处位置最近的一对括号及其中间的代码段，所以这个插件可能不是很适合 lua 和 python 代码。在未来我会用缩进来定义一个代码块（所以这个项目未来可能会变成类似 `indent_blankline` 的项目 😊）
和 [indent-blankline](https://github.com/lukas-reineke/indent-blankline.nvim) 类似,这个插件可以用来高亮缩进线,并且还可以根据当前光标所处的位置,高亮所在代码块.

第二部分是用来高亮缩进，就像是 `indent_blankline` 一样，这个功能可以选择基于 treesitter 或者是空格个数来进行渲染。treesitter 的优点是非常精确，但是可能速度上比较慢，而且有些不支持缩进的文件类型，比如 markdown，如果选择基于空格个数的渲染，速度上会有优势，但是在某些特殊情况下可能渲染不精确，如下所示
## 这个插件优势在哪里

<img width="400" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2303/01_hlchunk5.png">
1. 更具有拓展型
2. 更快的渲染速度 (每千次渲染花费 0.04 秒, 行高 50 行情况下)
3. 维护更积极 (作者是个带学生, 有大把的时间来维护这个插件, 笑)

基于空格个数的渲染
## 简要概述

<img width="400" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2303/01_hlchunk6.png">
这个插件由五个部分组成，未来会添加更多的功能（笑）

基于 treesitter 的渲染
1. chunk
2. indent
3. line_num
4. blank
5. context (处于实验阶段)

第三部分和 hl_chunk 的功能差不多，唯一不同之处在于他高亮的部分是行号而不是编辑器的内容，你可以设置行号的前景颜色和背景颜色
一张图搞懂这些功能分别是做什么的

第四部分是用来将空格使用你指定的字符来进行填充的，你可以指定很多有趣的图标和样式，下面这网站中你可以找到很多这样的图标 [Unicode Plus](https://unicodeplus.com/)
<img width='500' src='https://raw.githubusercontent.com/shellRaining/img/main/2305/01_intro.png'>

## 例子
## 详细展示

<b><font color='red'>注意：可以点击图片获取配置信息～</font></b>

<a href='./docs/zh_CN/chunk.md'>
### chunk

<a href='./docs/zh_CN/chunk.md#chunk_gif'>
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2303/08_hlchunk8.gif">
</a>

### hl_indent
### indent

<a href='./docs/zh_CN/indent.md'>
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2302/23_hlchunk2.png">
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2302/27_hlchunk4.png">
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2303/13_hlindent_bg.png">
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2305/01_indent.png">
</a>

### hl_line_num
### line_num

<a href='./docs/zh_CN/line_num.md'>
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2302/25_hlchunk3.png">
</a>

### hl_blank
### blank

<a href='./docs/zh_CN/blank.md'>
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2303/08_hlblank1.png">
<img width='500' src='https://raw.githubusercontent.com/shellRaining/img/main/2303/11_hlblank2.png'>
<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2303/08_hlblank1.png">
</a>

## 需求

neovim 版本 `>= 0.7.0` (也许，因为我是在这个版本的 neovim 中编写的)
neovim 版本 `>= 0.7.0`

## 安装

Expand Down Expand Up @@ -96,6 +96,7 @@ Plug "shellRaining/hlchunk.nvim"
{
chunk = {
enable = true,
use_treesitter = true,
support_filetypes = {
"*.ts",
"*.tsx",
Expand Down Expand Up @@ -125,11 +126,9 @@ Plug "shellRaining/hlchunk.nvim"
indent = {
enable = true,
use_treesitter = false,
-- You can uncomment to get more indented line look like
chars = {
"│",
},
-- you can uncomment to get more indented line style
style = {
FN.synIDattr(FN.synIDtrans(FN.hlID("Whitespace")), "fg", "gui"),
},
Expand All @@ -149,7 +148,7 @@ Plug "shellRaining/hlchunk.nvim"
line_num = {
enable = true,
support_filetypes = {
"..."
"..." -- same as chunk
},
style = "#806d9c",
},
Expand All @@ -167,6 +166,10 @@ Plug "shellRaining/hlchunk.nvim"
}
```

</details>

<hr>

配置文件像下面这样：

```lua
Expand All @@ -178,10 +181,12 @@ require('hlchunk').setup({
"#8B00FF",
},
},
blank = {
enable = false,
}
})
```

</details>
<hr>

## command
Expand Down
14 changes: 2 additions & 12 deletions docs/init.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,12 @@
lua
└── hlchunk
├── base_mod.lua
├── global.lua
├── init.lua
├── mods
│   ├── blank.lua
│   ├── chunk.lua
│   ├── indent.lua
│   └── line_num.lua
├── options.lua
└── utils
├── string.lua
├── table.lua
Expand All @@ -30,18 +28,10 @@ the project src files is under `lua/hlchunk` dir, we will introduce them one by

we will start from this file because the plugin loads here, when we call `require('hlchunk').setup()`, the `setup` function will execute and merge user config and default config, then judge what features are available, the unused features will not cost memory and CPU time, at last, it will load global variables, usercmds, highlights and autocmds

2. global.lua

this file contains some global variables could be used when rendering, it will be updated in `autocmd.lua`

3. base_mod.lua
2. base_mod.lua

this file defines the base mod behavior, as user you need not to care it

4. options.lua

this file contains the default settings for all mods

5. utils/
3. utils/

this dir contains some useful functions to render and deal with strings...
10 changes: 8 additions & 2 deletions docs/zh_CN/chunk.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,10 @@
# 怎样配置 hl_chunk
# chunk

## chunk 用来做什么

是用来高亮当前代码块，在本项目中代码块的定义是当前光标所处位置最近的一对括号及其中间的代码段，所以这个插件可能不是很适合 lua 和 python 代码。在未来我会用缩进来定义一个代码块（所以这个项目未来可能会变成类似 `indent_blankline` 的项目 😊）

# 怎样配置 chunk

## 配置项

Expand Down Expand Up @@ -51,7 +57,7 @@ chunk = {
},
```

你可以按照下面的配置来使你的样式看起来像是 GIF 里演示的那样
<a id='chunk_gif'>你可以按照下面的配置来使你的样式看起来像是 GIF 里演示的那样</a>

<img width="500" alt="image" src="https://raw.githubusercontent.com/shellRaining/img/main/2303/08_hlchunk8.gif">

Expand Down

0 comments on commit d9f5515

Please sign in to comment.