troubleshooting.md

Troubleshooting

The following guide goes from easy to complex operations that can help when this plugin is not functioning how you expect. As such it is recommended to go in order.

Run checkhealth

:checkhealth render-markdown

If there are any errors these should be looked at closely, warnings can largely be ignored. They are generated to help debug issues for less critical components, i.e. LaTeX support.

Validate filetype

This plugin only operates on markdown files by default, but can be expanded to run on any filetype with markdown injected by providing it in the config:

require('render-markdown').setup({
    file_types = { 'markdown', <other_filetype> },
})

Once you confirm the list of filetypes you expect this plugin to work on get the filetype of the current buffer and make sure it is in that list:

:lua vim.print(vim.bo.filetype)

Validate Parse Tree

Create a new markdown file locally with the following content:

# Heading

- Item

> [!NOTE]
> A note

- [x] Checked

Run :InspectTree which should output the following:

(document ; [0, 0] - [8, 0]
  (section ; [0, 0] - [8, 0]
    (atx_heading ; [0, 0] - [1, 0]
      (atx_h1_marker) ; [0, 0] - [0, 1]
      heading_content: (inline ; [0, 2] - [0, 9]
        (inline))) ; [0, 2] - [0, 9]
    (list ; [2, 0] - [4, 0]
      (list_item ; [2, 0] - [4, 0]
        (list_marker_minus) ; [2, 0] - [2, 2]
        (paragraph ; [2, 2] - [3, 0]
          (inline ; [2, 2] - [2, 6]
            (inline)) ; [2, 2] - [2, 6]
          (block_continuation)))) ; [3, 0] - [3, 0]
    (block_quote ; [4, 0] - [6, 0]
      (block_quote_marker) ; [4, 0] - [4, 2]
      (paragraph ; [4, 2] - [6, 0]
        (inline ; [4, 2] - [5, 8]
          (inline ; [4, 2] - [5, 8]
            (shortcut_link ; [4, 2] - [4, 9]
              (link_text))) ; [4, 3] - [4, 8]
          (block_continuation)))) ; [5, 0] - [5, 2]
    (list ; [7, 0] - [8, 0]
      (list_item ; [7, 0] - [8, 0]
        (list_marker_minus) ; [7, 0] - [7, 2]
        (task_list_marker_checked) ; [7, 2] - [7, 5]
        (paragraph ; [7, 6] - [8, 0]
          (inline ; [7, 6] - [7, 13]
            (inline))))))) ; [7, 6] - [7, 13]

If this is not what you see you likely need to update nvim-treesitter and your treesitter parsers.

Generate Debug Logs

If all else fails hopefully the logs can provide some insight. This plugin ships with logging, however it only includes errors by default.

To help debug your issue you'll need to go through the following steps:

1) Create a Test File

Use the same file from Validate Parse Tree.

2) Update Log Level

Change plugin configuration to output debug logs:

require('render-markdown').setup({
    log_level = 'debug',
})

3) Generate Logs

To do this restart Neovim and open the markdown file from the first step.

This should trigger the rendering logic, then close Neovim.

4) Provide Logs in Issue

Logs are written to a file typically located at: ~/.local/state/nvim/render-markdown.log.

Copy the contents of that file and paste it into the issue.