Giter Club home page Giter Club logo

markdown.nvim's Introduction

markdown.nvim

Plugin to improve viewing Markdown files in Neovim

Demo

Features

  • Functions entirely inside of Neovim with no external windows
  • Changes between rendered view in normal mode and raw view in all other modes
  • Changes conceallevel between rendered and raw view based on configuration
  • Supports rendering markdown injected into other file types
  • Highlights headings with different groups depending on level and replaces #
  • Highlights code blocks and inline code to better stand out
  • Replaces bullet points with provided character based on level
  • Replaces checkboxes with provided characters based on state
  • Updates horizontal rules with a full-width line
  • Replaces block quote leading > with provided character
  • Updates table borders with better border characters, does NOT automatically align
  • Basic support for LaTeX if pylatexenc is installed on system

Dependencies

Install

Lazy.nvim

{
    'MeanderingProgrammer/markdown.nvim',
    name = 'render-markdown', -- Only needed if you have another plugin named markdown.nvim
    dependencies = { 'nvim-treesitter/nvim-treesitter' },
    config = function()
        require('render-markdown').setup({})
    end,
}

Setup

Below is the configuration that gets used by default, any part of it can be modified by the user.

require('render-markdown').setup({
    -- Capture groups that get pulled from markdown
    markdown_query = [[
        (atx_heading [
            (atx_h1_marker)
            (atx_h2_marker)
            (atx_h3_marker)
            (atx_h4_marker)
            (atx_h5_marker)
            (atx_h6_marker)
        ] @heading)

        (thematic_break) @dash

        (fenced_code_block) @code

        (
          [
            (list_marker_plus)
            (list_marker_minus)
            (list_marker_star)
          ]
          (paragraph)
        ) @list_marker

        (
          [
            (list_marker_plus)
            (list_marker_minus)
            (list_marker_star)
          ]
          (task_list_marker_unchecked)
        ) @checkbox_unchecked

        (
          [
            (list_marker_plus)
            (list_marker_minus)
            (list_marker_star)
          ]
          (task_list_marker_checked)
        ) @checkbox_checked

        (block_quote_marker) @quote_marker
        (block_continuation) @quote_marker

        (pipe_table) @table
        (pipe_table_header) @table_head
        (pipe_table_delimiter_row) @table_delim
        (pipe_table_row) @table_row
    ]],
    -- Capture groups that get pulled from inline markdown
    inline_query = [[
        (code_span) @code
    ]],
    -- Filetypes this plugin will run on
    file_types = { 'markdown' },
    -- Vim modes that will show a rendered view of the markdown file
    -- All other modes will be uneffected by this plugin
    render_modes = { 'n', 'c' },
    -- Characters that will replace the # at the start of headings
    headings = { '󰲡 ', '󰲣 ', '󰲥 ', '󰲧 ', '󰲩 ', '󰲫 ' },
    -- Character to use for the bullet points in lists
    bullets = { '', '', '', '' },
    -- Characters to the unchecked/checked checkboxes
    checkboxes = {
        unchecked = '',
        checked = ''
    },
    -- Character that will replace the > at the start of block quotes
    quote = '',
    -- Character to use for the horizontal rule
    dash = '',
    -- See :h 'conceallevel' for more information about meaning of values
    conceal = {
        -- conceallevel used for buffer when not being rendered, get user setting
        default = vim.opt.conceallevel:get(),
        -- conceallevel used for buffer when being rendered
        rendered = 3,
    },
    -- Add a line above and below tables to complete look, ends up like a window
    fat_tables = true,
    -- Define the highlight groups to use when rendering various components
    highlights = {
        heading = {
            -- Background of heading line
            backgrounds = { 'DiffAdd', 'DiffChange', 'DiffDelete' },
            -- Foreground of heading character only
            foregrounds = {
                'markdownH1',
                'markdownH2',
                'markdownH3',
                'markdownH4',
                'markdownH5',
                'markdownH6',
            },
        },
        -- Code blocks
        code = 'ColorColumn',
        -- Bullet points in list
        bullet = 'Normal',
        -- Checkboxes
        checkboxes = {
            unchecked = 'Normal',
            checked = 'Normal'
        },
        table = {
            -- Header of a markdown table
            head = '@markup.heading',
            -- Non header rows in a markdown table
            row = 'Normal',
        },
        -- LaTeX blocks
        latex = '@markup.math',
        -- Quote character in a block quote
        quote = '@markup.quote',
        -- Horizontal rule
        dash = 'LineNr',
    },
})

Commands

:RenderMarkdownToggle - Switch between enabling & disabling this plugin

  • Function can also be accessed directly through require('render-markdown').toggle()

Purpose

There are many existing markdown rendering plugins in the Neovim ecosystem. However, most of these rely on syncing a separate browser window with the buffer. This is the correct way to do things to get full feature support, however I wanted something that worked completely inside of Neovim and made things look slightly "nicer".

The closest one I found to this was headlines.nvim, which is an awesome plugin that I took several ideas from. However it just didn't have quite what I was looking for. In particular I wanted something that would disappear completely when editing a file and quickly render some style when viewing the file. Hence this plugin.

Markdown Ecosystem

There are many markdown plugins that specialize in different aspects of interacting with markdown files. This plugin specializes in rendering the buffer inside of Neovim, for instance. As a result some plugins will clash with this one, whereas other plugins handle orthogonal concerns and can be used in addition to this one. Below is a categorized (incomplete) list of available plugins.

Render in Neovim

Using any of these plugins with this one will likely lead to undesired behavior as different functionality will clash.

  • headlines.nvim - Same high level idea and starting point of this plugin, but with different feature sets

Render in Browser

These can be used as a second pass to get a real preview of the markdown file. Since they do not interact with the buffer directly there should be no issues.

Orthogonal

These plugins handle functions completely separate from rendering and should also have no issues running alongside this plugin.

  • Any LSP which provides standard LSP capabilities, such as:
    • marksman - General completion, definition, and reference functionality
    • markdown-oxide - Adds Obsidian PKM features to LSP
  • markdown.nvim - Adds markdown specific keybindings for interacting with markdown files

markdown.nvim's People

Contributors

meanderingprogrammer avatar shabaev avatar redimp avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.