yaml-tags.nvim

Tags facilitator for markdown files.

Features

This plugin offers the following features:

Tag Scanning and Storage:
- Scans markdown files for tags within the YAML front-matter.
- Creates a .my_tags.json file with a unique list of tags.
Completion Source:
- Adds a new completion source with the tags.
- The completion source is available only when the cursor is in the YAML front-matter tags: section.
Tag Sanitization:
- Sanitizes tags in the YAML front-matter by removing duplicate tags and sorting them alphabetically.
- This feature can be switched off via the configuration.
Tag-based File Search:
- Provides a command to get the list of files containing the tag under the cursor.
- Displays the list of tags and the files containing them.

Installation

You can install yaml-tags.nvim using your preferred package manager. For example, with lazy:

 {
  "praczet/yaml-tags.nvim",
  config = function()
    require("yaml-tags").setup({
      sanitizer = true, -- Set to false to disable the sanitizer
    })
  end,
  dependencies = {
    "nvim-telescope/telescope.nvim", -- for file and tag search
  }
}

Dependency

nvim-cmp: For completion.
telescope.nvim: For fuzzy finding and file search.
lspkind-nvim: For icons in completion.
luafilesystem: To interact with the file system.
lua-cjson: For JSON handling.

Configuration

You can configure the plugin by passing options to the setup function:

require("yaml-tags").setup({
  sanitizer = true,
 tag_formatting = {
  allow_camel_case = false,
  allowed_characters = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
 },
 forbidden_words = { "and", "is", "or", "a", "the", "not" },
 excluded_directories = {},
 included_directories = {},
})

Options

sanitizer: Enable or disable the sanitizer (default: true).
tag_formatting: Table to configure tag formatting options.
- allow_camel_case Allow camel case in tags (default: false ).
- allowed_characters: String of allowed characters in tags (default: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789").
forbidden_words: List of words that should not be allowed as tags (default: { "and", "is", "or", "a", "the", "not" }).
extend_forbidden_words: Allow to extend the forbidden words list rather then replacing it. (default: false).
excluded_directories: List of directories to exclude (default: {}).
included_directories: List of directories to include (default: {}).

Included and Excluded directories

Absolute and Relative paths

Directory can be absolute or relative to the current working directory
If included_directories and excluded_directories are empty, all directories are included
If included_directories is not empty, only directories in the list are included
If excluded_directories is not empty, only directories not in the list are included

Usage

The yaml-tags plugin is enabled by default only for the markdown files. Most of the "job" are done in section tags: in the yaml front-matter.

Completion

To activate completion the cursor has to be in the YAML front-matter tags: section:

Calling `tag under the cursor` and `tag list` commands

When the cursor is in the YAML front-matter tags: section over the tag plugin allow to view markdown files containing that tag <leader>nt.

To see list off all tags just press <leader>nl.

Key Mappings

This plugin registers the following key bindings using which-key:

Normal Mode

<leader>ya: Add tags from selection.
<leader>yl: List tags and files containing them.
<leader>yt: Search files by tag under cursor.

Visual Mode

<leader>ya: Add tags from selection.

Autocommands

The plugin sets up an autocommand to sanitize YAML tags before saving:

vim.api.nvim_create_autocmd("BufWritePre", {
  pattern = "*.md",
  callback = function()
    require("yaml-tags").sanitize_current_buffer()
  end,
})

Example

Here's an example of how you can use the plugin in your init.lua or init.vim:

require("yaml-tags").setup({
  sanitizer = true, -- Set to false to disable the sanitizer
})

-- Ensure the plugin initializes correctly
require("yaml-tags").initialize()

Tag repository `.my_tags.json`

In the director with the markdown files you can find the .my_tags.json file which contains a list of tags and information about date of last modification.

{
  "last_mod": "2024-06-25 11:33:28",
  "tags": [
    "cm",
    "dataview",
    "ideas",
    "links",
    "#meal",
    "#obsidian",
    "#procreate",
    "admin",
    "art",
    "ascii",
    "backup",
    "base13",
    "bash",
    "blender",
    "blog"
  ]
}

TODO

Configuration option for allowing / disallowing specific files to be excluded from the tag search
Tag under the cursor - should check if the cursor is in the YAML front-matter in tags: section
Some more tests
Few features:
- add tag based on the word under the cursor
- add tag from selected text [#1]

Praczet/yaml-tags.nvim