Skip to main content

Ralsina.Me — Roberto Alsina's website

Posts about nikola

New Plugins for Nikola

Since ev­ery­one is in lock­down and I am no ex­cep­tion, I have spent some of my time do­ing things in open source project­s. Let me in­tro­duce you two new plug­ins for Niko­la my favourite stat­ic site gen­er­a­tor.

  1. marko

    Yet an­oth­er im­­ple­­men­­ta­­tion of Mark­­down! And since adding sup­­port for new im­­ple­­men­­ta­­tions of mark­­down is easy, I added it.

    Marko has some in­­ter­est­ing ideas. If a ecosys­tem of ex­ten­­sions de­vel­op­s, it will be easy to sup­­port them on the Niko­la side.

  2. myst

    Yes, an­oth­er mark­­down but, again, one with orig­i­­nal ideas. In this case, myst has a lot of re­Struc­­tured Text flavour, with sup­­port for di­rec­­tives and roles.

Of course when us­ing marko or myst in Niko­la you al­so get sup­port for short­codes so they are ex­tra-ex­ten­si­ble here.

If you are look­ing for a stat­ic site gen­er­a­tor, I am fair­ly sure "it does­n't sup­port my favourite markup lan­guage" is not a rea­son not to choose Niko­la :-)

Making my site FAST

My site is cre­at­ed us­ing a tool I start­ed and on which I have put a ton of ef­fort over the last 10 years or so, called Niko­la, which is a stat­ic site gen­er­a­tor (SS­G).

One of the sell­ing points of SS­Gs is that the pro­duced sites are fast and I have al­ways tak­en care to check, ev­ery once in a while, that my site was fast ... but not late­ly. And when I checked on Google Page­Speed In­sights I was hor­ri­fied to see it scor­ing 20 points out of 100.

So, I start­ed to see what the heck had hap­pened.

Google PageSpeed HATES Youtube

Each em­bed­ded video is seen as 4MB of block­ing things load­ing and mak­ing your page suck.

So­lu­tion: de­fer load­ing them us­ing http­s://github.­com/­group­board­/yt­de­fer

Bundling things still works

It has been years since it was promised that bundling mul­ti­ple CSS files in­to a large one or merg­ing mul­ti­ple JS files in­to a sin­gle script would not be worth it.

Well, ac­cord­ing to Page­Speed, it's still worth it. Luck­i­ly Niko­la has good sup­port for it, so I made sure EV­ERY­THING was bun­dled. That al­so in­volved get­ting some things off CDNs and in­to my as­sets fold­er:

  • pris­mjs
  • jquery

Google fonts are SLOW

Like, 400ms for two fonts. So, you can self­-host them us­ing http­s://­google-web­fonts-helper.herokuap­p.­com/­fonts

Al­so:

  • use font-display: swap
  • preload the fonts using something like <link rel="preload" href="/assets/fonts/pt-serif-v11-latin-regular.woff2" as="font">

Check CSS for @import

Even after bundling them, if a CSS file uses @import that will still be a separate request.

Check compression and caching

Make sure your web serv­er is do­ing the right things there.

Remove useless stuff

I was load­ing font-awe­some for ONE ICON. There, gone.

Did it work?

Now the score hov­ers around 96 to 98 so, yes it did. And in­deed the page feels very, very snap­py.

New Nikola Plugin: rst code blocks using prism.js

I have been writ­ing some of my posts us­ing Mark­down late­ly. And not even plain old Python Mark­down, but mis­a­ka which is an al­ter­na­tive im­ple­men­ta­tion based on Hoe­down

So, I no­ticed that those mark­down files had no syn­tax high­light­ing! I looked and Mis­a­ka does of­fer some­thing to "high­light things". Here is what it does:

<pre>
<code class="language-python">
def f():
    pass
</code>
</pre>

No class­es in the el­e­ments, no noth­ing, just a class in the code el­e­men­t! It turns out that is the rec­om­mend­ed way to in­di­cate you are show­ing code:

There is no for­mal way to in­di­cate the lan­guage of com­put­er code be­ing marked up. Au­thors who wish to mark code el­e­ments with the lan­guage used, e.g. so that syn­tax high­light­ing scripts can use the right rules, can use the class at­tribute, e.g. by adding a class pre­fixed with "lan­guage-" to the el­e­men­t.

So, I looked for how to ac­tu­al­ly dis­play those things nice­ly, and found pris­mjs.­com which looked very nice!

So nice, in­deed, that now I hat­ed how my re­Struc­tured Text Pages looked!

There­fore, I wrote a new Niko­la plug­in that re­places do­cu­til­s' code di­rec­tive and re­places it with a much sim­pler one that just tags things as code of a giv­en lan­guage and lets prism do the rest.

AFAICS it's functionally equivalent, it supports the :linenos: option, including shifted line numbers.

I doubt any­one ev­er will want to use it but hey, there it is.

Quick Nikola Feature: document APIs using pdoc

A us­er asked in the niko­la-dis­cuss if there was a way to use Niko­la to doc­u­ment APIs. Well, there was­n't and now there is. I took pdoc and wrote a wrap­per as a plug­in for Niko­la.

And now you can just doc­u­ment python mod­ules us­ing it in a cou­ple of min­utes.

Here is the doc­u­men­ta­tion for the re mod­ule from stdlib as an ex­am­ple.

Yes, the out­put is not great, and it needs CSS, and many oth­er fix­es, but it's easy to im­prove now that it's there, as long as there is in­ter­est.

Changes in this blog

I have made a few changes in how this blog is gen­er­at­ed and what fea­tures are en­abled.

Similarity Plugin

I have en­abled the sim­i­lar­i­ty plug­in and dis­abled the equiv­a­lent fea­ture pro­vid­ed by Dis­qus. In gen­er­al, it seems this plug­in pro­duces more whim­si­cal con­nec­tions which is a big plus. It may lead you to dis­cov­er very ran­dom things I wrote. I know it re­mind­ed me of things I did not re­mem­ber writ­ing!

Continuous Import

I have en­abled the con­tin­u­ous im­port plug­in which will au­to­mat­i­cal­ly merge some oth­er as­pects of my on­line pres­ence with this blog. Cur­rent­ly it has sup­port for goodreads (which I al­ready men­tioned be­fore) and youtube (which I have not), so you will see short book re­views and ran­dom videos I make.

Ex­am­ples: goodreads and youtube

This plug­in can the­o­ret­i­cal­ly sup­port any­thing that pro­vides a RSS/Atom feed and lets you ap­ply cus­tom tem­plates to the con­tent so you end up with pret­ty posts in all cas­es. If you are in­ter­est­ed in us­ing it for some oth­er ser­vice, feel free to ask me about it.

Front Page

For the first time ev­er, the front page of this site is no longer the blog, but a land­ing page.

Theme

At some point in the fu­ture I may switch to a more cus­tom­ized the­me, but that's not in any spe­cif­ic roadmap, it will hap­pen when it hap­pen­s. In the mean­time, this is now us­ing the Lu­men bootswatch and am ex­per­i­ment­ing with us­ing Flow­Type for a more read­able au­to­mat­ic font size.