Markdown 预览¶

简介¶

Markdown 语言之所以在撰写技术文档时被广泛使用，其原因之一在于其可转换性。代码可以被转换为多种格式（HTML、PDF、纯文本等）进行显示，从而使内容能在多种场景下使用。

具体来说，为 Rocky Linux 撰写的文档会使用一个 python 应用程序转换为 HTML。该应用程序将使用 markdown 编写的文档转换为静态 HTML 页面。

当为 Rocky Linux 撰写文档时，问题就出现了，需要验证其转换为 HTML 代码后的正确显示。

为了将此功能集成到你的编辑器中，本文将介绍两种可用的插件：toppair/peek.nvim 和 markdown-preview.nvim。这两者都支持 github 风格、选择要使用的浏览器进行预览，以及与编辑器同步滚动。

Peek.nvim¶

Peek 在其运行过程中使用了 Deno，一个默认设置安全且拥有 JavaScript、TypeScript 和 WebAssembly 运行时的环境。默认情况下，Deno 不允许任何文件、网络或环境访问，除非显式启用。

要在编辑器配置中安装语言服务器，会使用 mason.nvim 插件，它提供了 :MasonInstall 命令，该命令可以实现 Deno 的自动包含和配置。

:MasonInstall deno

警告

在继续安装插件之前，必须先安装语言服务器。否则安装将失败，并且需要删除 plugins/init.lua 中的代码，打开 Lazy 输入 X 删除插件以执行配置清理，然后重复安装过程。

要安装插件，你需要编辑 plugins/init.lua 文件，并添加以下代码块

{
    "toppair/peek.nvim",
    build = "deno task --quiet build:fast",
    keys = {
        {
        "<leader>op",
            function()
            local peek = require("peek")
                if peek.is_open() then
            peek.close()
            else
            peek.open()
            end
        end,
        desc = "Peek (Markdown Preview)",
        },
},
    opts = { theme = "dark", app = "browser" },
},

保存文件后，可以通过输入 :Lazy 命令打开插件管理器界面来执行安装。插件管理器已自动识别它，并允许你通过输入 I 来安装它。

要获得全部功能，你必须关闭 NvChad (nvim) 并重新打开它。这是为了让编辑器能够加载 Peek 的配置。

其配置已包含激活命令 <leader>op，在键盘上表示为 Space + o，然后是 p。

Peek

你也有这个字符串

opts = { theme = "dark", app = "browser" },

这允许你传递预览的浅色或深色主题选项以及要使用的显示方法。

在此配置中，选择了“browser”方法，该方法会在系统的默认浏览器中打开要查看的文件，但该插件还允许通过“webview”方法仅使用 Deno 通过 webview_deno 组件进行预览。

Peek Webview

Markdown-preview.nvim¶

Markdown-preview.nvim 是一个用 node.js (JavaScript) 编写的插件。在 NvChad 上安装它不需要任何依赖项，因为开发者提供了预编译的版本，可以在编辑器中完美运行。

要安装此版本，你需要将此代码块添加到你的 plugins/init.lua 文件中

{
    "iamcco/markdown-preview.nvim",
    cmd = {"MarkdownPreview", "MarkdownPreviewStop"},
    lazy = false,
    build = function() vim.fn["mkdp#util#install"]() end,
    init = function()
        vim.g.mkdp_theme = 'dark'
    end
},

与前一个插件一样，你需要关闭编辑器并重新打开它，以便 NvChad 能够加载新的配置。同样，你可以向插件传递一些自定义选项，这些选项在项目存储库的专门部分中进行了描述。

然而，必须修改选项以适应 lazy.nvim 的配置，特别是本示例中配置的选项

vim.g.mkdp_theme = "dark"

这对应于项目网站上描述的选项

let g:mkdp_theme = 'dark'

如你所见，要设置选项，你必须修改它们的前半部分，使其可解释。再举一个例子，让我们来看一个允许你选择预览所用浏览器的选项，该选项指定如下

let g:mkdp_browser = '/usr/bin/chromium-browser'

为了在 NvChad 中正确解释这一点，需要将其修改为将 let g: 替换为 vim.g.。

vim.g.mkdp_browser = "/usr/bin/chromium-browser"

这样，下次打开 NvChad 时，将使用 chromium-browser，而不管系统的默认浏览器是什么。

配置还提供了 :MarkdownPreview 和 :MarkdownPreviewStop 命令，分别用于打开和关闭预览。为了更快速地访问命令，你可以将它们映射到 mapping.lua 文件中，如下所示

-- mapping for Markdown Preview
map("n", "<leader>mp", "<CMD> MarkdownPreview<CR>", { desc = "Open Preview" })
map("n", "<leader>mc", "<CMD> MarkdownPreviewStop<CR>", { desc = "Close Preview" })

这将允许你通过输入 Enter + m 后跟 p 来打开 markdown 预览，并通过组合 Enter + m 后跟 c 来关闭它。

注意

该插件还提供了 :MarkdownPreviewToggle 命令，但在撰写本文档时，该命令似乎无法正常工作。如果你尝试调用它，它不会更改预览主题，而是会打开一个新的浏览器标签页，显示相同的预览。

Markdown Preview

结论和最终想法¶

对你正在撰写的内容进行预览可能很有用，无论是对于新手还是对于更深入了解 Markdown 语言的用户。预览可以让你评估代码在转换后的影响以及其中包含的任何错误。

选择使用哪个插件是完全主观的，我们鼓励你尝试这两种插件，以评估哪种可能最适合你。

使用这些插件之一，可以让你为 Rocky Linux 的文档贡献符合所用代码的文档，从而减轻文档审阅者的工作量。

作者：Franco Colussi

贡献者：Steven Spencer, Ganna Zhyrnova