Markdoc.nvim

Tree-sitter based markdown -> vimdoc converter plugin for Neovim

Generate Convert Improve

Install / Use

/learn @OXY2DEV/Markdoc.nvim

About this skill

Quality Score

0/100

README

🎇 markdoc.nvim

Tree-sitter based markdown to vimdoc converter for Neovim.

<div align="center"> <img src="https://github.com/OXY2DEV/markdoc.nvim/blob/images/images/markdoc.nvim-3.png"> <img src="https://github.com/OXY2DEV/markdoc.nvim/blob/images/images/markdoc.nvim-2.png"> <img src="https://github.com/OXY2DEV/markdoc.nvim/blob/images/images/markdoc.nvim-tables.png"> </div>

🪄 Features

Common markdown syntax support.
Common inline HTML support.
Aligned paragraph(via <p align=""></p> or <div align=""></div>)
Preserves whitespace.
Extended syntax support(e.g. Callouts).
Table converter with column alignment & text wrap support.
Custom Table of contents generator.
Custom file header support(with support for version, author, date modified).
Fully customizable.
Ability to configure per file(using JSON).
Ability to remove parts of the file when converting to Vimdoc(e.g. Top heading in README.md).

And much more!

🧭 Requirements

tree-sitter-markdown.
tree-sitter-markdown_inline.
tree-sitter-html(for inline HTML & comments in markdown).

[!IMPORTANT] By default, callouts use nerd font characters. You can change this in the config to use normal text instead.

📦 Installation

🧩 Vim-plug

Plug "OXY2DEV/markdoc.nvim"

💤 lazy.nvim

{
    "OXY2DEV/markdoc.nvim"
},

return {
    "OXY2DEV/markdoc.nvim"
};

🦠 mini.deps

local MiniDeps = require("mini.deps");

MiniDeps.add({
    source = "OXY2DEV/markdoc.nvim",
})

🌒 rocks.nvim

[!WARNING] luarocks package may sometimes be a bit behind main.

:Rocks install markdoc.nvim

📥 GitHub release

Tagged releases can be found in the release page.

[!NOTE] Github releases may sometimes be slightly behind main.

🎇 Usage

There is a single command,

:Doc

When called without arguments, it runs on the current buffer.

When called with an argument,

:Doc README.md

It converts given file.

:Doc 0

Or buffer.

It can be called with multiple files/buffers.

:Doc README.md test.md

📬 API functions

There are 2 available API functions.

🧩 File conversion API

--[[ Converts **file** with `path` into `vimdoc`. ]]
---@param path string Path to file.
---@param user_config? markdoc.config Custom configuration. Overrides the file specific configuration.
---@param use? integer Buffer to dump the preview into. Has no effect if `generic.filename` is set.
markdoc.convert_file = function (path, user_config, use)
    -- ...
end

This function can be used to convert a file in path into vimdoc.

You can use it like so,

require("markdoc").convert_file("README.md", {
    generic = { filename = "doc/markdoc.nvim.txt" }
});

🧩 Buffer conversion API

--[[ Converts `buffer` into `vimdoc`. ]]
---@param buffer? integer Buffer ID. Defaults to *current* buffer.
---@param user_config? markdoc.config Custom configuration. Overrides the file specific configuration.
---@param use? integer Buffer to dump the preview into. Has no effect if `generic.filename` is set.
markdoc.convert_buffer = function (buffer, user_config, use)
    -- ...
end

This function can be used to convert a buffer into vimdoc.

You can use it like so,

require("markdoc").convert_buffer(0, {
    generic = { filename = "doc/markdoc.nvim.txt" }
});

This will convert current buffer.

✨ Special syntax

markdoc.nvim uses special comments to modify the file. These can be,

✨ File-specific configuration

Use  syntax for adding file specific configuration.

<!--markdoc
    {
        "generic": {
            "filename": "doc/markdoc.nvim.txt",
            "force_write": true,
            "header": {
                "desc": "Tree-sitter based `Markdown -> Vimdoc` converter for Neovim",
                "tag": "markdoc.nvim"
            }
        },
        "markdown": {
            "tags": {
                "Features$": [ "markdoc.nvim-features" ],

                "^generic$": [ "markdoc.nvim-generic" ],
                "^filename$": [ "markdoc.nvim-filename", "markdoc.nvim-generic.filename" ],
                "^force_write$": [ "markdoc.nvim-force_write", "markdoc.nvim-generic.force_write" ],
                "^winopts$": [ "markdoc.nvim-winopts", "markdoc.nvim-generic.winopts" ]
            }
        }
    }
-->

✨ Ignoring parts of the document

Use  &  syntax for specifying parts of the document that will be removed in the converted document.

<!--markdoc_ignore_start-->

# Invisible text

<!--markdoc_ignore_end-->

Tree-sitter based `markdown` to `vimdoc` converter for Neovim.

Some visible text

This will result in


Some visible text

✨ Table of contents

Table of contents can be generated by adding <TOC/> to a line.

<TOC/>

🔧 Configuration

The plugin can be set-up by using the setup() function.

require("markdoc").setup({
    markdown = {
        code_blocks = {
            fallback_language = "vim",
            indentation = "\t"
        },
    }
});

The following options are supported,

generic

Type: markdoc.config.generic

-- Generic options for controlling help file generation.
---@class markdoc.config.generic
---
---@field preserve_whitespace? boolean Should whitespace be preserved?
---
---@field filename? string Name of help file.
---@field relative_path? boolean Is the file oath relative to the `source` file? Gets set to `false`, if `filename` starts with `~`.
---@field force_write? boolean Should `:write!` be used instead of `:write`?
---@field winopts? table Window options for the previewer.
---
---@field textwidth? integer Text width of the help file.
---@field indent? integer Number of spaces to use for indentation.
---
---@field header markdoc.config.generic.header
---@field links markdoc.config.generic.links
---@field images markdoc.config.generic.links
---@field toc markdoc.config.generic.toc

Generic configuration options. These are,

preserve_whitespace

Type: boolean

When false, Repeating empty lines will be collapsed into a single empty line.

The default value is false.

filename

Type: string

Name of the file to save to.

[!NOTE] This is relative to the current file being concerted!

[!IMPORTANT] markdoc doesn't create non-existing directories! You have to make sure the directories exist before using it!

relative_path

Type: string

When true(default value), generic.filename will be relative to the source file's location. When false, the filename will be relative to the current

Related Skills

node-connect

344.4k

Diagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps

frontend-design

99.2k

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

openai-whisper-api

344.4k

Transcribe audio via OpenAI Audio Transcriptions API (Whisper).

qqbot-media

344.4k

QQBot 富媒体收发能力。使用 <qqmedia> 标签，系统根据文件扩展名自动识别类型（图片/语音/视频/文件）。