Markdown Enhancements

Transforming Neovim into a powerful writing environment

Markdown serves as the default format for documentation, README files, and structured content creation, valued for its clarity, accessibility, and adaptability. Neovim, with its extensible framework and robust plugin support, functions as an optimal Markdown editing environment.

Neovim's minimalist, configurable design allows for workflow refinement in Markdown editing. With the addition of relevant plugins, it provides advanced features such as syntax differentiation and intelligent formatting.

This adaptability positions Neovim as a capable replacement for dedicated Markdown editors, merging text editor efficiency with modern writing tool functionality.

Why Neovim for Markdown authoring

Neovim provides a terminal-based, keyboard-driven environment optimized for Markdown authoring. Its architecture supports high performance, extensibility, and integration with modern development workflows.

For technical writers and developers, Neovim combines the efficiency of a terminal editor with the flexibility to adapt to complex documentation requirements.

Markdown in Rocksmarker

In Rocksmarker, markdown-plus.nvim and render-markdown.nvim integrate to create a seamless Markdown editing environment. markdown-plus.nvim provides advanced editing capabilities, including intelligent list management, quick formatting, and efficient header navigation for structured content creation. render-markdown.nvim dynamically renders Markdown elements like headings, code blocks, and lists directly in the editor, eliminating the need for external preview tools.

Together, these plugins transform Neovim into a real-time, interactive Markdown platform, merging the flexibility of a text editor with the features of dedicated Markdown tools. This integration optimizes the workflow for authoring, editing, and visualizing Markdown documents.

Plugin details

markdown-plus.nvim

markdown-plus.nvim enhances Markdown editing in Neovim by providing intelligent, context-aware tools for structured content creation. It improves workflow efficiency with features such as automated list handling, dynamic header manipulation, and real-time table of contents generation, all while maintaining a lightweight and responsive editing experience. The plugin integrates with Neovim's native environment, offering intuitive keymaps and commands that simplify common editing tasks.

The plugin supports a comprehensive range of Markdown elements, including inline formatting, code blocks, tables, footnotes, and callouts. By automating repetitive tasks like list renumbering, link conversion, and TOC updates, it allows to focus on content creation. Its configurable and extensible design makes it suitable for various use cases, from simple note-taking to complex technical documentation.

Core Features

markdown-plus.nvim serves users who demand efficiency, precision, and adaptability in their Markdown workflow. It combines the simplicity of a text editor with the functionality of specialized documentation tools.

Keymaps

List management

Key Features

• Auto-Continuation
  Pressing Enter in INSERT mode automatically continues lists with proper markers and indentation.
• Smart Indentation
  Tab and Shift+Tab adjust list item indentation contextually.
• Checkbox Support
  Toggle task completion with ,+m+x or Ctrl+t (INSERT mode).
• Renumbering: Ordered lists are automatically renumbered as you edit. Use ,+m+r to manually trigger renumbering.
• Parent-Aware Outdenting: Outdenting nested items with Shift+Tab adopts the parent’s ordered marker.
• Blank Line Handling: Lists separated by blank lines restart numbering from 1.
• Code Block Awareness: Indented fenced code blocks within lists are treated as part of the list item.

Text Formatting Keymaps

Key Features

• Context-Aware Formatting: Applies formatting to the word under the cursor or the visually selected text.
• Treesitter Integration: Uses Treesitter for accurate detection of formatted regions and nested formatting.
• Dot-Repeat Support: Repeat the last formatting command with the . key in normal mode.
• Multi-Style Support: Supports nested formatting (e.g., bold inside italic).
• Code Block Conversion: Quickly convert selected text to a fenced code block in visual mode.

Headers & TOC

Key Features

• Header Navigation: Quickly jump between headers using ]] and [[.
• Header Level Adjustment: Promote or demote headers with ++comma+h+and ++comma+h-.
• Direct Header Conversion: Set headers to specific levels (H1-H6) with dedicated keymaps.
• TOC Generation: Automatically generate and update a Table of Contents with GitHub-style anchors.
• TOC Window: Open an interactive, navigable TOC window for easy document traversal.
• Header Style Toggle: Switch between ATX and setext header styles.
• Duplicate Prevention: TOC generation avoids duplicates using HTML comment markers.

Links & references

Key Features of Links & References

• Link Insertion: Quickly insert new links with ,+m+l.
• Link Conversion: Convert selected text or URLs to Markdown links in visual mode.
• Link Editing: Modify existing links with ,+m+e.
• Style Conversion: Toggle between reference-style and inline-style links.
• Browser Integration: Open links directly in the browser using g+x.
• Smart Link Handling: Automatically converts bare URLs to Markdown links.

Image Links

Normal & Visual Mode

Quotes Management

Normal & Visual Mode

Callouts/Admonitions

Normal & Visual Mode

Tables

Normal Mode

Insert Mode

Note: Insert mode navigation falls back to arrow keys when not in a table.

Footnotes

Normal Mode

!!! note ""

In normal mode, these commands operate on the word under the cursor. In visual mode, they operate on the selected text.

render-markdown.nvim

render-markdown.nvim brings real-time rendering of Markdown elements directly into the Neovim buffer. It visually enhances your content by displaying headings, code blocks, checkboxes, and lists with styling, allowing you to preview your work without leaving the editor. This plugin bridges the gap between writing and visualizing, making it easier to create polished and professional Markdown documents.

Key Features

• Live Preview: Renders Markdown elements in real-time, providing immediate visual feedback.
• Customizable Themes: Adjust the appearance of headings, code blocks, and other elements to match your preferences.
• Lightweight: Designed for performance, ensuring a smooth editing experience even with large files.
• Seamless Integration: Works alongside other Markdown plugins to create a cohesive and productive writing environment.

The combination of markdown-plus.nvim and render-markdown.nvim transforms Rocksmarker into a powerful and intuitive environment for Markdown authoring. Together, these plugins offer the modern features and visual clarity needed to create high-quality documentation, notes, and blog posts efficiently.

LSP tools

Neovim's Language Server Protocol (LSP) integration extends robust code editing features to Markdown files. By leveraging LSP clients such as nvim-lspconfig, users enable real-time diagnostics, autocompletion, hover documentation, and symbol navigation within Markdown documents. These tools enhance productivity by providing context-aware suggestions, error detection, and formatting support, all while maintaining compatibility with Neovim's modular architecture.

Key functionalities include:

• Diagnostics: Identify syntax errors, broken links, and style inconsistencies.
• Autocompletion: Contextual suggestions for headings, links, and code blocks.
• Hover Information: Preview rendered Markdown or embedded code snippets.
• Symbol Navigation: Jump between headings, links, and references efficiently.

Markdown Linting

Linting verifies Markdown files for structural and stylistic compliance. It detects syntax errors, formatting inconsistencies, unreachable links, and improper heading nesting. Tools such as markdownlint, vale, or LSP-based linters (e.g., marksman) apply user-defined rules to keep uniformity and correctness.

Key Features:

• Rule Application: Enforces standards for headings, lists, line lengths, and link integrity.
• Actionable Output: Reports violations and can offer automated corrections.

Linting streamlines documentation workflows, reduces manual reviews, and ensures consistency with project or industry standards. Configure rules to match specific guidelines or specifications.

Prose linting

Prose linting systems analyze written content for clarity, consistency, and correctness. These tools detect grammatical errors, stylistic inconsistencies, redundant phrasing, and non-inclusive language in natural language text. Solutions such as vale, proselint, or write-good integrate with editing workflows to enforce style guides and improve readability.

Core Capabilities:

• Style Enforcement: Applies rules for grammar, terminology, and voice (active/passive).
• Automation: Operates in editors (e.g., Neovim via LSP), CI pipelines, or standalone scripts.
• Customizable Rules: Supports organization-specific or industry-standard guidelines.

Prose linters enhance technical documentation, marketing content, and general writing by reducing ambiguity and ensuring adherence to defined standards. Configuration files allow tailoring checks to project requirements.

Vale

Vale is a syntax-aware linter for prose that enforces stylistic and grammatical consistency in documentation and content. It applies customizable rules to detect errors, inconsistencies, and noncompliant phrasing in natural language text. Designed for technical writers, developers, and content teams, Vale integrates with editing workflows to ensure adherence to style guides and best practices.

Key Features:

• Rule-Based Checking: Validates terminology, grammar, readability, and inclusive language.
• Extensible Rules: Supports community and custom rule sets.

-- Configure vale_ls for prose linting in Neovim.
setup_lsp_server("vale_ls", {
  -- Use extended client capabilities for full LSP feature support.
  capabilities = get_lsp_capabilities(),

  -- Specify the filetypes for which vale_ls should be activated.
  filetypes = { "markdown", "text", "tex", "rst" },

  -- Optional: Set the root directory pattern to look for '.vale.ini'
  -- root_dir = require('lspconfig.util').root_pattern('.vale.ini'),

  -- Enable single file support.
  single_file_support = true,

  -- Optional: Add any additional settings for vale_ls.
  settings = {
    -- If you have specific Vale settings, they can be added here.
  },
})

Vale improves clarity, reduces ambiguity, and standardizes writing across projects. Configuration files allow tailoring checks to specific guidelines, making it adaptable to technical, marketing, or general content.

nvim-lint with vale

nvim-lint integrates with Vale to give real-time feedback on grammar, style, and clarity in Markdown and text files. This combination brings automated prose linting directly into Neovim, enforcing consistency with customizable style guides and reducing manual reviews.

Key Features:

• Inline Diagnostics: Flags grammatical errors, terminology inconsistencies, and non-inclusive language during editing.
• Rule Customization: Supports Vale's extensible rule sets.
• Asynchronous Operation: Runs checks in the background, preserving editor responsiveness.

-- nvim-lint.nvim settings - Linting capabilities
local lint_ok, lint = pcall(require, "lint")
if not lint_ok then
  return
end

lint.linters_by_ft = {
  markdown = { "markdownlint", "vale" },
  yaml = { "yamllint" },
  bash = { "shellcheck" },
  json = { "jsonlint" },
  vim = { "vint" },
}

nvim-lint with Vale enables technical writers and developers to support high-quality, standardized content without workflow disruptions. Configure linting rules through Vale's .vale.ini and style-specific rule files.

!!! note "validates structure and prose"

`nvim-lint` is configured to run both `markdownlint` and Vale. This setup validates Markdown structure and prose quality in real time, using rules defined in `.markdownlint.json` and `.vale.ini`. Diagnostics are hidden by default; toggle visibility with <leader>dd.

harper

Harper is a prose linter that enforces consistency, clarity, and correctness in written content. It analyzes text for grammatical errors, stylistic inconsistencies, and adherence to defined standards. Targeted at documentation, APIs, and general prose, Harper integrates with development workflows to automate reviews and reduce manual edits.

Core Capabilities:

• Style and Grammar Validation: Detects deviations from configured style guides or best practices.
• Custom Rule Sets: Supports organization-specific or industry-standard rules for terminology, voice, and structure.

-- Configure Harper language server for grammar and style checking in Neovim.
-- Harper is a privacy-first, offline grammar checker for developers and writers.
setup_lsp_server("harper_ls", {
  settings = {
    -- All Harper-specific settings must be nested under the harper-ls key.
    ["harper-ls"] = {
      -- Linters configuration: enable or disable specific grammar and style checks.
      linters = {
        SpellCheck = true,
        SpelledNumbers = false,
        AnA = true,
        SentenceCapitalization = true,
        UnclosedQuotes = true,
        WrongQuotes = false,
        LongSentences = true,
        RepeatedWords = true,
        Spaces = true,
        Matcher = true,
        CorrectNumberSuffix = true,
      },

      -- Code actions configuration: control how code actions are displayed.
      codeActions = {
        ForceStable = false,
      },

      -- Markdown-specific settings: control how Harper handles Markdown files.
      markdown = {
        IgnoreLinkTitle = false,
        IgnoreCodeBlocks = true,
        IgnoreInlineCode = true,
        CheckLists = true,
        CheckHeadings = true,
      },

      -- Set the severity level for diagnostics.
      -- Options: "error", "warning", "information", "hint"
      diagnosticSeverity = "hint",

      -- Isolate English language checks to avoid false positives in mixed-language documents.
      isolateEnglish = true,
    },
  },
})

Harper helps teams maintain high-quality, uniform documentation and content. Its configurable ruleset system allows adaptation to project-specific or domain-specific requirements.

Validation and verification

Syntax validation ensures Markdown files comply with structural rules. It identifies issues such as unclosed code blocks, improper list nesting, or wrong metadata. LSP-based tools parse content to flag syntax errors, enabling corrections before publication.

Link verification confirms the integrity of all hyperlinks in Markdown. It validates

• Link accessibility (HTTP status, endpoint response)
• Anchor existence (internal reference targets)
• URL format (syntax, completeness)

LSP integrations automate these checks during editing or in build workflows. Configuration options support custom rules for domains, timeouts, and exclusions. Together, these processes maintain document accuracy and reduce manual validation efforts.

marksman

Marksman is a language server for Markdown that provides real-time syntax validation, semantic analysis, and linting. It ensures structural correctness, detects formatting inconsistencies, and verifies link integrity within Markdown files. Designed for integration with code editors, Marksman leverages the Language Server Protocol (LSP) to deliver immediate feedback during editing.

Key Features:

• Syntax and Structure Validation: Identifies malformed elements, improper nesting, and metadata errors.
• Link and Reference Checking: Validates internal/external links, anchors, and cross-references.
• Editor Integration: Works seamlessly with Neovim and other LSP-compatible editors for inline diagnostics and autocompletion.

-- Marksman provides advanced Markdown language features such as syntax checking,
-- formatting, and navigation.
setup_lsp_server("marksman", {
  -- The `get_lsp_capabilities()` function returns a table of capabilities that enhance
  -- the interaction between Neovim and the LSP server.
  capabilities = get_lsp_capabilities(),

  -- Specify the filetypes for which Marksman should be activated.
  filetypes = { "markdown", "md" },
})

Marksman enhances documentation workflows by automating error detection and enforcing consistency. Its rule-based approach supports customization for project-specific or organizational standards.

markdownlint

markdownlint is a static analysis tool that enforces consistent style and syntax in Markdown files. It detects common issues such as inconsistent heading levels, improper list indentation, broken links, and non-standard formatting. Designed for developers and technical writers, markdownlint integrates with editors, build systems, and version control workflows to keep clean, readable documentation.

Core Functionality:

• Rule-Based Linting: Applies configurable rules for structure, syntax, and style (e.g., line length, heading increments, link validity).
• Automated Checks: Runs in CI pipelines, pre-commit hooks, or editor plugins (e.g., Neovim via null-ls or efmls).
• Customizable Rules: Supports disabling or adjusting rules via configuration files to match project requirements.

markdownlint reduces manual review efforts and ensures Markdown content adheres to defined standards, improving maintainability and professionalism.

Real-Time markdown linting

nvim-lint is a Neovim plugin that provides asynchronous linting for various file types, including Markdown. When configured with markdownlint rules, it delivers immediate feedback on style and syntax issues directly in the editor. This integration helps keep consistency, catch errors early, and enforce best practices without leaving the development environment.

Key Features:

• Inline Diagnostics: Highlights problems such as inconsistent headings, list formatting, or broken links as you edit.
• Custom Rule Support: Uses markdownlint configurable ruleset to align with project or team-specific conventions.
• Non-Blocking Workflow: Runs linting in the background, ensuring responsive editing even in large documents.

nvim-lint combined with markdownlint automates quality checks, reduces manual reviews, and streamlines Markdown authoring in Neovim. You manage configuration through .markdownlint files to adapt flexibly to different standards.

Automated Formatting and Linting

conform.nvim is a Neovim plugin for lightweight, asynchronous formatting and linting. When paired with markdownlint, it enforces style and structural rules in Markdown files, providing both automated fixes and real-time diagnostics. This integration ensures consistent formatting and error-free documentation directly within the editor.

Key Features:

• On-Save Linting: Validates Markdown against markdownlint rules during file saves or on-demand.
• Auto-Correction: Applies fixable rule violations (e.g., list indentation, heading increments) automatically.
• Seamless Integration: Works alongside LSP and other Neovim plugins for a unified editing experience.

conform.nvim with markdownlint reduces manual intervention, standardizes documentation, and accelerates workflows by merging linting and formatting into one tool. You configure it through conform.nvim setup and .markdownlint rule files.