A Go program to preview GitHub Flavored Markdown (GFM) 📓.

The gh-gfm-preview command start a local web server to serve the markdown document. gh gfm-preview renders the HTML using yuin/goldmark and some extensions and frontend tricks to have similar features and look to how GitHub renders a markdown.

It may also be used as a GitHub CLI extension.

This is a hard fork of yusukebe/gh-markdown-preview, that uses the GitHub Markdown API, but this means it doesn't work offline. The code of this repository tries to emulate the look of GitHub Markdown rendering as close as possible, but the original project will be even closer to the actual result if you don't need offline rendering.

• Works offline - You don't need an internet connection.
• Fast - Since it doesn't rely on external services it is really fast.
• No-dependencies - You can just run the standalone binary (or optionally via gh as an extension).
• Zero-configuration - You don't have to set the GitHub access token.
• Live reloading - You don't need reload the browser.
• Auto open browser - Your browser will be opened automatically.
• Auto find port - You don't need find an available port if default is used.
• Graceful degradation - Basic functionality works even without JavaScript.

You need to have Go installed.

go run github.com/thiagokokada/gh-gfm-preview

Assuming that you have Flakes enabled:

nix run github:thiagokokada/gh-gfm-preview

gh extension install thiagokokada/gh-gfm-preview

Upgrade:

gh extension upgrade markdown-preview

The usage:

Or this command will detect README file in the directory automatically.

Then access the local web server such as http://localhost:3333 with Chrome, Firefox, or Safari.

Available options:

    --dark-mode           force dark mode
    --disable-auto-open   disable auto opening your browser
    --disable-reload      disable live reloading
-h, --help                help for gh-gfm-preview
    --host string         hostname this server will bind (default "localhost")
    --light-mode          force light mode
    --markdown-mode       force "markdown" mode (rather than default "gfm")
-p, --port int            TCP port number of this server (default 3333)
    --verbose             show verbose output

Since the binary is static and it works offline, this is a good program to use to preview how a Markdown is looking in e.g.: neovim. For example, you can add this in your $HOME/.config/nvim/init.lua:

local function preview_markdown()
  local file = vim.fn.expand("%")
  local on_exit_cb = function(out)
    print("Markdown preview process exited with code:", out.code)
  end
  local process = vim.system(
    -- assuming that the extension were installed using gh
    -- the reason we are not using `gh gfm-preview` instead is because this
    -- can cause an issue where the gh process is killed but not the
    -- gh-gfm-preview, since the kill signal will not reach the child process
    {vim.fn.expand("$HOME/.local/share/gh/extensions/gh-gfm-preview/gh-gfm-preview"), file},
    on_exit_cb
  )

  vim.api.nvim_create_autocmd({ "BufUnload", "BufDelete" }, {
    buffer = vim.api.nvim_get_current_buf(),
    callback = function()
      process:kill("sigterm")
      -- timeout (in ms), will call SIGKILL upon timeout
      process:wait(500)
    end,
  })
end

-- create a shortcut only in Markdown files, mapped to `<Leader>P`
vim.api.nvim_create_autocmd({ "FileType" }, {
  pattern = { "markdown" },
  callback = function()
    vim.keymap.set("n", "<Leader>P", preview_markdown, {
      desc = "Markdown preview", buffer = true
    })
  end,
})

You can run the following command to (re-)generate assets:

And you can run the following command to build: