Oasis and 'render-markdown'

[pkazmier]

Here is my first pass at tuning 'render-markdown' for Oasis. Below are two markdown files as an example.

I'm still debating about the order of colors for the headings. I also used terminal-based colors in Oasis palette as I wanted explicit control over which colors would be adjacent to each other. At first I tried syntax-based colors, but when switching between Oasis themes, I didn't like some of the adjacent colors.

Also, please keep in mind, this is not out of the box behavior for 'render-markdown'.

CONFIG: 'render-markdown'

I dynamically create several hl-groups based that 'render-markdown' requires to achieve the header effect you see in the screenshot. Rather than hardcode these into my current theme, I generate them based on the `@markup.heading.N` colors. There are a couple helper functions in here prefixed by `Config` which can be found in my neovim config repo on GitHub.

-- ---------------------------------------------------------------------------
-- render-markdown
-- ---------------------------------------------------------------------------

-- Setup custom reverse video render-markdown heading hl groups based on
-- the fg color of existing markdown hl groups. This provides the fancy
-- headings when in preview mode.
local setup_heading_hl_groups = function()
  local fallback_hl_info = Config.get_hl("@markup.heading") or Config.get_hl("Title")

  for lvl = 1, 6 do
    local hl_name = "@markup.heading." .. lvl
    local hl_info = Config.get_hl(hl_name .. ".markdown") or Config.get_hl(hl_name) or fallback_hl_info
    assert(hl_info, "Must set one of 'Title', '@markup.heading', '@markup.heading.N', or '@markup.heading.N.markdown'")

    local hl_spec = {}
    if hl_info.fg then hl_spec.fg = hl_info.fg end
    if hl_info.bg then hl_spec.bg = hl_info.bg end
    if hl_info.bold then hl_spec.bold = true end
    if hl_info.italic then hl_spec.italic = true end

    vim.api.nvim_set_hl(0, "RenderMarkdownH" .. lvl, hl_spec)
    hl_spec.reverse = true
    vim.api.nvim_set_hl(0, "RenderMarkdownH" .. lvl .. "Bg", hl_spec)
  end
end

Config.now_if_args(function()
  vim.pack.add({ "https://github.com/MeanderingProgrammer/render-markdown.nvim" }, { load = true })
  require("render-markdown").setup({
    file_types = { "markdown", "md", "codecompanion" },
    render_modes = { "n", "no", "c", "t", "i", "ic" },
    code = {
      sign = false,
      border = "thin",
      position = "right",
      width = "block",
      above = "▁",
      below = "▔",
      language_left = "█",
      language_right = "█",
      language_border = "▁",
      left_pad = 1,
      right_pad = 1,
    },
    heading = {
      sign = false,
      width = "block",
      left_pad = 1,
      right_pad = 0,
      position = "right",
      icons = function(ctx) return (""):rep(ctx.level) .. "" end,
    },
  })

  -- Set the heading hl groups AND an autocmd for colorscheme changes.
  setup_heading_hl_groups()
  Config.new_autocmd("Colorscheme", {
    desc = "Setup up heading hl groups for render markdown.",
    callback = setup_heading_hl_groups,
  })
end)

CONFIG: 'oasis'

Config.now(function()
  vim.pack.add({ { src = "https://github.com/uhs-robert/oasis.nvim" } }, { load = true })
  require("oasis").setup({
    highlight_overrides = function(c, colors)
      -- stylua: ignore
      return {
        RenderMarkdownBullet           = "Special",
        RenderMarkdownChecked          = "String",
        RenderMarkdownTodo             = "Special",
        RenderMarkdownUnchecked        = "Special",
        RenderMarkdownCode             = { bg = c.bg.mantle },
        RenderMarkdownCodeInline       = { bg = c.bg.mantle },
        RenderMarkdownCodeBorder       = { bg = c.bg.surface },
        RenderMarkdownLink             = { fg = c.theme.strong_primary },
        RenderMarkdownWikiLink         = {},
        RenderMarkdownTableHead        = { fg = c.fg.muted },
        RenderMarkdownTableRow         = { fg = c.fg.muted },

        ["@markup.heading.1"]          = { fg = c.terminal.yellow,         bold = true },
        ["@markup.heading.2"]          = { fg = c.terminal.bright_yellow,  bold = true },
        ["@markup.heading.3"]          = { fg = c.terminal.red,            bold = true },
        ["@markup.heading.4"]          = { fg = c.terminal.green,          bold = true },
        ["@markup.heading.5"]          = { fg = c.terminal.bright_magenta, bold = true },
        ["@markup.heading.6"]          = { fg = c.terminal.blue,           bold = true },
        ["@markup.italic"]             = { fg = c.theme.accent,            italic = true },
        ["@markup.link.label"]         = { fg = c.theme.primary },
        ["@string.special.url"]        = { fg = c.theme.secondary },
        ["@markup.strong"]             = { fg = c.theme.accent,            bold = true },
      }
    end,
  })
  vim.cmd.colorscheme("oasis")
end)

p.s. This is the first time that I noticed Oasis dims non-active windows via NormalNC. I just noticed it when switching back and forth between windows in the above screenshot. I guess I hadn't noticed while working on buffers with code as very little text in those defaults to Normal.

[uhs-robert]

This looks beautiful! I love what you've done here.

The "fancy heading" design is really slick, too. I especially like how the slant count matches the heading levels; it makes the hierarchy obvious at a glance (while quietly teaching users the color key too). I also agree with using terminal colors here for tighter control and consistency.

Thanks for sharing the setup code. I do want to recreate this locally so I can see it in context. I’ll take a look at your config helpers later.

Headings

For the order of colors in headings, that's a good question. Headings represent hierarchy, so I think the colors should reflect/reinforce that too by "descending".

Since Oasis as a pack spans the full rainbow, it may be easiest to just lean into that and follow ROYGBIV from top to bottom.

Option A (my preference): ROYGBIV in order

• H1 = Red
• H2 = Orange
• H3 = Yellow
• H4 = Green
• H5 = Blue
• H6 = Indigo/Violent (Bright Magenta)

Option B: 3 hues × 2 strengths

Pick 3 anchor hues, then use base/bright as the pair. For example, using primary colors (RYB), we descend from the warmest colors to the coolest:

• H1/H2 = Red / Bright Red
• H3/H4 = Yellow / Bright Yellow
• H5/H6 = Blue / Bright Blue

Either way keeps a clear “most important to least important” hierarchical progression.

NormalNC

NormalNC dimming is intentional, but I’m still not happy with it and could use a second opinion.

The goal is simple: make inactive windows recede so the active buffer stays the focus. In my local config, I tried NormalNC.bg = bg.shadow, but I haven’t shipped it because the effect is very subtle. And, as you noticed, the fg change is mostly invisible since Normal isn’t used much. Some themes (like Abyss) also can’t dim their background further because bg.core is already at #000000.

Alternatives I’m considering: slightly brighten inactive windows (e.g., bg.mantle) or add an even darker “shadow” level and just treat Abyss/Starlight as special edge cases. Not sure what the best approach is.

[pkazmier]

Glad you like the markdown setup. I agree, it makes taking notes in meetings so much more enjoyable for me. I have over 2,000 meeting notes in my system, so I hyper optimize on my note taking environment. I never really use checkmarks, but I like your changes and will incorporate as well.

[pkazmier]

On a side note, I noticed your screenshot had a reference to WezTerm. Is that your terminal of choice? If so, you may be interested in this wezterm/wezterm#5435.

[uhs-robert]

I am currently on the fence with WezTerm (because I just love using Lua as a config file language, which allows for all sorts of dynamic decision making). But I am currently using Kitty as it uses less memory, the fonts look a bit different, and I am a huge fan of cursor trails. I am still on the fence though, and have been toying with the idea of switching for the past 4 months 😂.

Your guide, which shows dynamic configuration branching, is... awesome. This is exactly the kind of stuff that makes me want to make the switch to WezTerm!

[kovidgoyal]

Just FYI, you can write kitty config in any language from bash to C and everything in between using the geninclude directive in kitty.conf which allows you to dynamically generate kitty config directives by running an arbitrary program of your choice.

[uhs-robert]

@kovidgoyal you’ve got to be kitten me, I had no idea geninclude existed! I am going to have to explore that option sometime this week. Thank you for the tip! This should open a few doors to dynamic behavior that I've been missing.