Grav? Nikola? maybe both

by Offray Vladimir Luna Cárdenas — on  ,  ,  ,  , 


I have recently discovered grav, but I have a previous blog site with nikola. How can both technologies be integrated?

Cybernomade... yep after years I'm still one of them.

I have been trying for years to build a self owned web presence ([1] [2]), but is difficult. Not only because there is a lot of appealing and easy to use cyber feudalism offers to cultivate the ciberspace of and for others while making them richer (facebook, google, twitter, etc), but also because in the realm of self hosted, author owned indie web bets, there are emerging interesting and maturing options with less and less overweight for authors/owners: Known, Nikola and grav are three of such options, that I have personaly tested. I will concentrate of the last two, because there is major overlap between its functionality.

Grav and Nikola are both flat file web site generators. This means that you write in a plain file with light markup language and metadata and both convert it in a responsive site, with css, menu navigation, image embedding and so on. Both have a plugin extensible architecture.

On the differences, grav is made on php, Nikola with python. Grav is a dynamic flat file CMS, Nikola is a static web generator, which means that, to produce the final result, flat files are interpreted on the fly in the former and compiled in the last one. Nikola has an extensive support for several markup languages, including IPython/Jupyter notebooks, while grav only supports markdown + yaml (which similar to the combination followed by pandoc, the format I'm using for writing my thesis). Grav has a lot of prebuild web site templates to start with, called Skeletons, and a diverse amount ot themes, while in the case of Nikola, themes are kind of homogeneous, regarding font sizes and white space (margins, header photos, etc), and there are not skeletons, which could save you tons of time.

I really never liked php. I don't like its syntax, its semantics, its ecosytem extremely focused on the web. Python seemed to me like a more interesing, clearer, multidomain language, and for several years it was my scripting and exploratory computing language. That's why, anytime I can choose, I have chosen python based technologies over php ones and that's why IPython/Jupyter support was an important feature of the publishing technologies I used. Despite that, there is a lot of really good infrastructures made on php, dokuwiki, question2answer and grav are examples that I have personaly experienced.

But now that I'm using primary Pharo as my main medium for explorative computing, including data visualization and interactive documentation (see grafoscopio), I'm not so much interested in the scripting languages behind publishing solutions like grav or Nikola, or the support for IPython documents, but more in API, storage formats (data and metadata) and the reading experience, this last one heavily influenced by practical typography, for online reading, and on printing by the master Edward Tufte.

That's why I'm making this experiment with grav. After writing and publishing, I want a clean reading experience, like the one provided by this theme (called notepad), and even if I think that I will be using some "legacy" and external IPython/Jupyter docs that I could be publishing and/or interacting with, I would like them to produce an output more like this (or the ones in practical typography), instead of the ones with small letters and margins provided by default with bootstrap themes.

So, how integration will happen?

  • The first thing I will do will be put all my new post on grav instead of Nikola. This will equal my first hand experience with both systems to start thinking in integration. So, I will be using Nikola for publishing IPython/Jupyter notebooks and grav for everything else.
  • The second thing I'll do is to experiment with grafoscopio and grav integration, mainly by making grafoscopio to know about grav and how to publish on it. Because grafoscopio uses pandoc's markdown it shares with grav the idea of yaml metadata embedded in markdown, so it shoudn't be so difficult. (when I talked about yaml for metadata in Nikola, one developer answered me that this was python, not ruby!, like if python had something against human readable data serialization languages).
  • The third thing will be some playing with scrapping and publishing using something like soup, teapot, rss, grav and Nikola. By using a microframework I have to add an abstraction layer to what before was just static files in flat files site generators, but anyway a cognitive burden will be added when I need to think about how to hack html templates to produce desired output, so why not use the dynamic explorative nature of pharo to see how this integration can be done, and in fact see if I can learn the Smalltalk way to the web, with dynamic objects, that can be stored in plain files and rendered by superb static web site generators when I just need that, and have interative behaviour if I need something else.

Hopefuly it will lead to some ideas cross-pollination between different approaches for example:

  • Nikola Teasers: This blog template only use the first paragraph of the post as a stand out for the content and a one line abstract in the timeline. Sometimes you need more text and or an image and the way of solving these via teasers seems elegant and useful.
  • Enabling comments is trickier for grav and easier for Nikola. There is a comments plugin already for that, but is not working easily. Would be nice to have in both some integration with hypothesis, so you can comment specific selections of the text, and see in the side, how many coments are associated wich that part and their respective conversations (a more subtle indicator for selections in needed when is going to be integrated in a blog, more similar to Medium and less to a underliner marker).
  • Grav themes and skeletons: Porting some themes could not take long for experienced Nikola devs and knowing the proactivity and good vibra of the Nikola people, is not difficult to imagine some ports of Notepad and Mediator themes soon. Also having more complete templates to start with Nikola (store, blog, agency site, etc) would help to new users and spread its adoption, like is happening right now with grav.
  • Site autorefresh for Nikola. This is possible right now with the proper flags on Nikola, but again is about sensible defaults. In this way any change you made on the flat files is reflected automátically in your rendered html without manual intervention, like happens with grav because of its dynamic nature. I think that auto-refresh should be the default and interactivity on computers should turned off by additional work, not the other way (by the way this is not happening by default regarding publishing on my own project: grafoscopio, but that's because publishing is something you do at the very end on academic writing, open, garage and citizen science, everything else is highly interactive thanks to Pharo/Smalltalk).
  • Dates fields in the yaml headers of each post can be used for ordering the entries, which I discover by using the admin plugin. The only thing you need to remember is to put your dates between quotes, something like date: "2015-10-06", as in the source code of this post. Will be nice to have two dates, one for creation date of the post and one for the last modification.
  • I like the idea of a folder per post. They become more modular and self contained, so you can have figures, scripts and other information related to the post in a bigger container, while gravs takes care of making that resources system wide available.

Ok. That is for now: just a recap of the history, some ideas for cross-pollination and a state of intend for the future. Let's see how this experiment goes.