Sentiers - minimal personal wiki manager in Neovim.

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:

= (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, 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 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:

{'thjbdvlt/sentiers.nvim', ft = 'sentiers', lazy = true},

You need to initialize/setup the plugin after you modified its options (see option list below).

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.

-- 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:

{
  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 to export to HTML, using a simple 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

OS

Only tested on Linux.

Alternatives

• vimwiki
• wiki.vim
• neowiki.nvim
• kiwi.nvim