feat: add highlight.js

[clason]

used for syntax highlighting of annotated code examples

neovim.min.css provided by @rockerBOO

Dark theme:

Light theme:

closes #302

[rockerBOO]

Made a demo using tokyo night dark/light. I think this is the most popular colorscheme for Neovim right now.

https://codepen.io/rockerboo/pen/KKeRERd

And a repo for building it out. I have a neovim.min.css you should be able to drop in. We can further tweak the colors as we go.

https://github.com/rockerBOO/neovim-highlight-colorscheme

[rockerBOO]

[rockerBOO]

Also base 16 based colors so theres a bunch of options out there like the ones in https://github.com/RRethy/nvim-base16

[clason]

Thanks! I stuck with these since Justin seems very keen on the general colorscheme, so I wanted to exactly match the background. (And I kinda prefer the light green to your grey...)

Highlight.js has a bunch of base16 styles which I looked through as well.

Anyway, I personally don't have any strong preferences and will happily use whatever style is preferred!

[rockerBOO]

Ok perfect, I can fix the light scheme some.

I also noticed we are already plumbed for highlighting on the site right now. Possibly something in jekyll adding the tags in the code. Maybe we can style that up instead/as well. I think having a non-JS highlighting is better generally, but we can apply highlight.js where this is not available.

From /news/

<div class="highlight"><pre class="highlight"><code><span class="c1">-- Using a Lua function in a key mapping prior to 0.7</span>
<span class="kd">local</span> <span class="k">function</span> <span class="nf">say_hello</span><span class="p">()</span>
    <span class="nb">print</span><span class="p">(</span><span class="s2">"Hello world!"</span><span class="p">)</span>
<span class="k">end</span>

<span class="n">_G</span><span class="p">.</span><span class="n">my_say_hello</span> <span class="o">=</span> <span class="n">say_hello</span>

<span class="n">vim</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">nvim_set_keymap</span><span class="p">(</span><span class="s2">"n"</span><span class="p">,</span> <span class="s2">"&lt;leader&gt;H"</span><span class="p">,</span> <span class="s2">"&lt;Cmd&gt;call v:lua.my_say_hello()&lt;CR&gt;"</span><span class="p">,</span> <span class="p">{</span><span class="n">noremap</span> <span class="o">=</span> <span class="kc">true</span><span class="p">})</span>
</code></pre></div>

We can tweak the colors some to match the some green/blue we use away from tokyo night.

I'll look into the highlighter working on the website.

[clason]

I also noticed we are already plumbed for highlighting on the site right now

That doesn't sound right. I don't see any actual syntax highlighting working. (We also need to support explicit language annotations, since our snippets are usually too short to automatically recognize vimscript.)

But, sure, if there's a lighter alternative to highlight.js, I don't mind!

[rockerBOO]

It seems to support the same way github works, ```lua

Uses https://github.com/rouge-ruby/rouge , see _config.yaml for highlighter

We can use https://github.com/rouge-ruby/rouge#command-line to generate the css and then include that css file.

Color changes

Here are the new colors for light dark using our accent-bg-color from the site. Updated css at rockerBOO/neovim-highlight-colorscheme

[clason]

Here are the new colors for light dark using our accent-bg-color from the site.

Nice!

It seems to support the same way github works, ```lua

so instead of <pre><code> ... </code></pre> blocks, I should just use wrap the markdown fenced block in <pre>...</pre>?

[rockerBOO]

It seems to support the same way github works, ```lua

so instead of <pre><code> ... </code></pre> blocks, I should just use wrap the markdown fenced block in <pre>...<pre>?

Not sure what you mean here. If we use the jekyll/rogue option we are good with just adding the css. If theres a place outside that we can use highlight.js to handle that.

Did a quick pass for the jekyll/rogue option at #304

[clason]

I mean, how should the html sources look like? We want to add language annotations in general, and I need to change the HTML generator to do that. I've done this for highlight.js, but I have no idea what the Jekyll one expects.

[rockerBOO]

jekyll has a plugin that is already doing it. See the HTML for this page https://neovim.io/news/, the code blocks have the spans inside the pre.

[clason]

Yeah, I don't see any syntax highlighting there. Just a bunch of random spans.

Again, I want to manually annotate the code blocks as "vim", "lua", "python", ..., and highlight them accordingly. I don't think we can rely on automatic language detection.

[rockerBOO]

Yeah the span are what I am styling in that PR I linked above, #304.

The spans are from rogue which used the pygment format. You can see colorschemes using that format.

The spans are generated from the type of file it's highlighting, and inside our posts/ markdown we'd use the github syntax and it'll do the rest.

The fenced areas in the latest news items.

[clason]

That was exactly what I was asking. So I should use Markdown fenced codeblocks instead of <code>...</code> blocks in the generated HTML.

[clason]

Unfortunately, the generator script doesn't like backticks...

[rockerBOO]

I have been mentioning mostly about neovim.github.io, but I think you're working with the doc generator for the neovim docs? So I would imagine that would be different, and also not have the rogue/jekyll things.

I would keep the HTML like suggested with highlight.js.

<pre><code class="language-html">...</code></pre>

And now I understand why it will be hard to know what language it is showing with snippets and the vimdoc.

Well, now we should be good on the colors for the moment.

[clason]

I have been mentioning mostly about neovim.github.io, but I think you're working with the doc generator for the neovim docs?

No, that part is working fine. I'm talking here only about neovim.github.io/doc/ (although of course I can only test locally by running jekyll serve --host, where the backticks don't work). The docs already have the annotation (see the linked Neovim PR near the top here); the question is how to make Jekyll use it. I got it working with highlight.js, but I'm happy to use anything else -- if someone tells me how to ;)

[clason]

In any case, I'll happily switch to your css tomorrow :)

[rockerBOO]

Ok neovim.github.io/doc/, this individual page is made by jekyll but other paths under, like https://neovim.io/doc/user/, are generated in that other vimdoc script. jekyll doesn't touch those other pages, so we can't use the rogue syntax highlighter from jekyll for those. At least not easily.

So highlight.js for the reference manual and the rogue highlighting for the main site. My other PR will handle the main site.

[clason]

Ah, ok, thank you for explaining, now I understand!

Then let's proceed like you suggest:

1. merge this PR (with your updated CSS) for /doc/user
2. merge your PR for the main site
3. tweak both themes (or use the same for both) to taste

[justinmk]

Is it time to start a section in the readme mentioning various components like this?