https://github.com/thjbdvlt/sentiers.nvim
Personal wiki with automated hyperrefs.
https://github.com/thjbdvlt/sentiers.nvim
hypertext knowledge neovim neovim-plugin static-website wiki
Last synced: 7 months ago
JSON representation
Personal wiki with automated hyperrefs.
- Host: GitHub
- URL: https://github.com/thjbdvlt/sentiers.nvim
- Owner: thjbdvlt
- License: mit
- Created: 2025-07-15T09:08:42.000Z (7 months ago)
- Default Branch: sea
- Last Pushed: 2025-07-16T21:59:15.000Z (7 months ago)
- Last Synced: 2025-07-16T22:02:57.339Z (7 months ago)
- Topics: hypertext, knowledge, neovim, neovim-plugin, static-website, wiki
- Language: Lua
- Homepage:
- Size: 33.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
__Sentiers__ - minimal personal wiki manager in [Neovim](https://neovim.io/).
In __Sentiers__, links are defined in the *referenced file* and not the *referencing file*.
In any file, you defined words or phrases that, if used in other files, will become links to this file.
For example, you can have a file about the sociologist Howard Becker, that would look like this:
```txt
= (Howard )?Becker
Howard Becker is a sociologist, born in...
Here are some sentences about him, is life, his work.
Then you want to talk about something more specific, e.g. his book "Art worlds"
= art worlds
In his book Art worlds, Becker says...
(All links are anchored.)
```
Now, in *any other* __Sentiers__ file (by default with extension `.se`) that are in the same [project](#Project), the words `Howard Becker` or just `Becker`, and `art worlds` would become links to this file (on the paragraph that follows the 'definition'). Such links will be highlighted as links, and are usable to jump to the referenced file (the buffer content won't change). You can think of an LSP enabling you to *jump to definition*, or as automatic hypertext.
You may chose to avoid multiple links to the same page, as in (e.g.) Wikipedia, and having a highlighted link only for the first occurrence in the file.
# Mappings
|Mapping name|Default value|Description|
|--|--|--|
|open|`gf`|Jump using the nearest link in line.|
|next|`]]`|Go to next link.|
|prev|`[[`|Go to previous link.|
|jump_leap|`\|`|Use [leap](https://github.com/ggandor/leap.nvim) to jump to visible links.|
|create|`gF`|Create (or open if exists) a file using word under cursor.|
|create_visual|`gf`|Create a file (or open if exists) using selected text.|
|export|`zf`|Export current file to markdown or html and open it.|
|back|`gD`|Show links pointing to current file and pick one with fzf.|
# Commands
All commands are defined as subcommand of a main command, which is by default `:Sentiers` (configurable). For now, there is only a few commands:
- `:Sentiers export`: export whole project.
- `:Sentiers search`: pick a link definition using fzf-lua and jump to file.
- `:Sentiers update`: update links in current buffer (automatically used on save).
- `:Sentiers back`: list *backlink*, i.e. a links referencing the current file, and pick one with fzf to jump on file.
# Installation
Using Lazy:
```lua
{'thjbdvlt/sentiers.nvim', ft = 'sentiers', lazy = true},
```
You need to initialize/setup the plugin *after* you modified its options (see option list [below](#Configuration)).
```lua
local sentiers = require "sentiers"
sentiers.opts.map.open = "gd"
sentiers.opts.fzf_color = false
sentiers.opts.prefix_definition = "-> "
sentiers.opts.git_project = true
sentiers.setup() -- Initialize the plugin
```
And you need to associate the plugin to a file extension. __Sentiers__ by itself doesn't provide syntax outside of links. You can either use it in plain text files, or upon another format, like Markdown.
```lua
-- File endings with `.se` will use Sentiers only
vim.api.nvim_create_autocmd(
{'BufEnter'}, {
pattern='*.se',
command=':setlocal filetype=sentiers'
}
)
-- File endings with `*.md.se` will use Markdown + Sentiers
vim.api.nvim_create_autocmd(
{'BufEnter'}, {
pattern=*'.md.se',
command=':setlocal filetype=markdown.sentiers'
}
)
-- File endings with `*.htlm.se` will use HTML + Sentiers
vim.api.nvim_create_autocmd(
{'BufEnter'}, {
pattern='*.html.se',
command=':setlocal filetype=html.sentiers'
}
)
```
## Configuration
The default configuration is as follow:
```lua
{
ext = ".se", -- Extension for Sentiers files
map = {
open = "gd", -- Follow nearest link (go to definition)
next = "]]", -- Put cursor on next link
prev = "[[", -- Put cursor on previous link
jump_leap = "|", -- Follow a link chosen with leap.nvim
create = "gF", -- Create a link from word under cursor
create_visual = "gf", -- Create a link from visual selection
export = "zf", -- Export current file to markdown or html and open it
back = "gD", -- Show links pointing to current file and pick one with fzf
},
cmd_filename = { -- Commands to generate filename from visual or word under cursor
{ "iconv", "-f", "utf-8", "-t", "ascii//translit" },
{ "sed", "s/[^-a-zA-Z0-9]/_/g" }
},
hl_urls = true, -- Highlight URLs, too, with minimal regex
prefix_definition = "= ", -- Line prefix that define link names (not regex!)
comma_comment = true, -- Comments with ",," until the end of line
grep_exclude = "https\\?://\\S*|www\\.\\S*|^#.*|<[^>]+>",
default_export_ft = 'md', -- Currently accept only "md" or "html"
anchor = true, -- Export links using anchors (produces empty divs)
git_project = false, -- Use Git to define project instead of ".sentiers"
head = false, -- Show file head as virtual text when using "[[" and "]]"
head_timeout = 1000,
usr_cmd = 'Sentiers', -- ":Sentiers export", etc.
fzf_color = true, -- Highlighted color on ":Sentiers back"
}
```
# Project
There are two ways to define project. If the option `git_project` is set to `true`, __Sentiers__ will use Git. Else, it will look for a file named `.sentiers`. Either the `.git` directory or the `.sentiers` file will determined the root directory of you project.
# Exportation
Having a personal wiki is cool. But you may want to export it, e.g. as a website.
__Sentiers__ offer a convenient way to achieve this: the command `:Sentiers export`. It takes three optional parameters:
- `ext`: the extension (and filetype) to use. (Markdown or HTML)
- `link_prefix`: the prefix to put at the start of links; this is useful if you're exporting a wiki that will be put, e.g. in `/doc/wiki` in your website.
- `only_first_link`: subsequent links pointing to a same file are not rendered.
As an example, I use __Sentiers__ with Markdown format, and then I use [Pandoc](https://pandoc.org/) to export to HTML, using a simple makefile:
```makefile
src := $(shell fdfind "\.se$$")
md := $(src:.se=.md)
html := $(src:.se=.html)
all:
nvim -c 'Sentiers export' -c 'q'
make $(html)
%.html: %.md
pandoc -i $< -o $@
clean:
rm -f $(html) $(md)
.PHONY: all clean
```
# Dependencies
- [rg](https://github.com/BurntSushi/ripgrep)
# OS
Only tested on Linux.
# Alternatives
- [vimwiki](https://github.com/vimwiki/vimwiki)
- [wiki.vim](https://github.com/lervag/wiki.vim)
- [neowiki.nvim](https://github.com/echaya/neowiki.nvim)
- [kiwi.nvim](https://github.com/serenevoid/kiwi.nvim)