present.nvim

A Neovim plugin for presenting markdown files as slideshows.

Usage

Start a presentation from the current buffer by calling start_presentation with no arguments, or optionally pass a table with a filepath field to present a specific file;

require("present").start_presentation({
    filepath = "/path/to/file.md" -- optional argument
})

or just run the :PresentStart <filepath?> command, optionally passing a file path to present

Configuration

Calling the setup function is optional if you want to pass any configuration options, the following table shows all valid configuration options with their default values;

require("present").setup({
    -- whether the chosen separator character(s) should be removed from the slide header
    hide_separator_in_title = true,
    -- a list of lua matching patterns to use as slide boundaries
    -- lines matching one of these separators will become slide titles in the header
    separators = { "^# " },
    -- options to control the text displayed in the footer
    footer = {
      -- the text displayed on the left side of the footer, defaults to the format shown
      -- set this equal to an empty string for no text
      left_text = "<current_slide_number> / <total_slide_count> | <filename>",
      -- the text displayed on the right side of the footer, defaults to the current date in the format shown
      -- set this equal to an empty string for no text
      right_text = "YYYY-MM-DD",
    },
    -- the normal mode keymaps available while in presentation mode, see the `Keymaps` section below
    keymaps = {
      previous_slide = "p",
      next_slide = "n",
      first_slide = "f",
      last_slide = "e",
      end_presentation = "q",
      execute_code_blocks = "X",
      close_execution_output = "x",
    },
    -- vim options that will be modified when in presentation mode
    -- you can pass any valid vim options here to customise how presentation mode behaves
    -- see :help option-list to see all valid fields for this table
    presentation_vim_options = {
      cmdheight = 0,
      conceallevel = 0,
      hlsearch = false,
      linebreak = true,
      wrap = true,
    },
    -- the default code executors available, see the `Live Code Block Execution` section below
    executors = {
      go = execution.execute_go_code,
      javascript = execution.create_system_executor("node"),
      lua = execution.execute_lua_code,
      python = execution.create_system_executor("python"),
      rust = execution.execute_rust_code,
    },
})

Live Code Block Execution

You can execute code inside markdown code blocks on a slide, e.g.

print("Hello world!")

and the result will be displayed in a floating window

• Execution functions are provided for lua, go, rust, python, and javascript by default
• You can add your own to the executors table in the setup config table
• The default executors may not be compatible with your system and you may need to write a custom executor. See lua/present/execution.lua for example implementations
• For interpreted languages, you can use the create_system_executor utility function provided by present.nvim to easily create a new executor;

local present = require("present")

present.setup({
    executors = {
        ruby = present.create_system_executor("ruby")
    }
})

Keymaps

These keymaps are active in normal mode when presenting a file. You can customise them using the keymaps table in the config table passed to setup (see Configuration above)

key	description
p	move to the previous slide
n	move to the next slide
f	move to the first slide
e	move to the last slide
q	quit the presentation
X	execute the code blocks on the slide
x	close the code execution output

Developing locally

• This project requires the following development dependencies to be installed:
  • just (command runner)
  • watchexec (file watcher)
  • plenary.nvim plugin/library for testing
    • the plenary repo must be cloned as a sibling directory to this repo by default, i.e. available at ../plenary.nvim/
    • alternatively the PLENARY_NVIM_DIR env var can be set to provide a different location on your system
• Run the entire test suite with just test
• Run the entire test suite in watch mode with just test-watch
• Run just --list for optional arguments and more info

Acknowledgements

Inspired by and adapted from @tjdevries "Neovim Plugin from Scratch" YouTube series

See also tjdevries/present.nvim