Skip to main content

Ralsina.Me — Roberto Alsina's website

Twitter Card Support in Nikola

This fea­ture for Niko­la was im­ple­ment­ed by @amok­leben, and now, if you ask twit­ter your site can have it too.

What are Twit­ter Card­s? Did you no­tice that for some sites, when you click on tweets that have links, you get a small pre­view of the con­tent? Well, that's a twit­ter card.

This still needs a lit­tle im­prove­ment to sup­port the rich­er "me­di­a" card­s, but it does work:


Yes, that's a pic­ture of the twit­ter card for this post. How meta, right?

You don't have to do any­thing in your site, but set­ting the "de­scrip­tion" meta­da­ta to your posts helps make this more ac­cu­rate (and it al­so works for google+)

Nikola 5.4 is out!

I am thrilled to an­nounce the re­lease of ver­sion 5.4 of Niko­la, a stat­ic site/blog gen­er­a­tor

Here's the (in­com­plete!) changel­og for this re­lease 1:


  • Twit­ter Card / Open Graph sup­­port.

  • Smart math sup­­port

  • New sound­­could di­rec­­tive

  • Cus­­tom "read more" links

  • Bet­ter time dis­­­play, time­­zone sup­­port

  • Bet­ter doit in­­te­­gra­­tion (Is­­sue #151)

  • Make the whole list­ings fold­er brows­able (Is­­sue #128)

  • New GZIP_­­FILES/GZIP_EX­TEN­­SIONS op­­tions to cre­ate gzipped copies of some files (Is­­sue #348)

  • New op­­tion­al path pa­ram­e­ter to new_­­post com­­mand.

  • Word­­press im­­porter: op­­tion to not down­load files

  • Word­­press im­­porter: op­­tion to squash new­­lines

  • Sep­a­rat­ed BLOG_URL in­­­to SITE_URL and BASE_URL

  • Added DIS­­ABLED_­­PLU­G­INS op­­tion (Is­­sue #354)


  • Added mis­s­ing </­di­v> in de­­fault theme tem­­plates.

  • Word­­press im­­port: De­scrip­­tion is left em­p­­ty if no de­scrip­­tion is found.

  • When run­n­ing the build com­­mand it is now pos­si­ble to get help.

  • Load jQuery be­­fore boot­s­trap in JS bun­­dle (Is­­sue #327)

  • Gen­er­ate valid HT­M­L5 for redi­rects (Is­­sue #276)

  • Fixed "niko­la check"

  • Fixed in­­ter­­na­­tion­al­ized RSS links

  • Make com­­mands that need to be run in a site fail grace­­ful­­ly (Is­­sue #342)

  • Use lo­­cal­ized links on lxml fix­er

  • Redi­rec­­tions cre­at­ed dur­ing the im­­port from word­­press are now writ­ten to con­

  • Stop pars­ing meta­­da­­ta in post file on first blank line

  • Meta­­da­­ta han­dling cleanups by Tordek

  • Fixed block­­quote font size in­­­con­­sis­ten­­cy

  • Word­­press Im­­port: Do not break in­­­den­­ta­­tion (is­­sue #189)

  • Make things work even if SITE_URL has a path (Fix #307)


There are al­so some ex­tra bits of doc­u­men­ta­tion, and a awe­some be­ta theme called "site-re­veal" based on boot­strap and re­veal.js!

Creating a Site (Not a Blog) with Nikola

One of the most fre­quent ques­tions I get about Niko­la is "but how do I cre­ate a site that's not a blog?". And of course, that's be­cause the doc­u­men­ta­tion is heav­i­ly blog-ori­ent­ed. This doc­u­ment will change that ;-)

Since it start­ed, Niko­la has had the ca­pa­bil­i­ties to cre­ate gener­ic sites. For ex­am­ple, Niko­la's own site is a fair­ly gener­ic one. Let's go step by step on how you can do some­thing like that.

As usual when starting a nikola site, you start with nikola init which creates a empty semi-configured site:

$ nikola init mysite
Created empty site at mysite.

Then we go into the new mysite folder, and make the needed changes in the configuration file:

# Configuration, please edit

# Data about this site
BLOG_AUTHOR = "Roberto Alsina"
BLOG_TITLE = "Not a Blog"
# This is the main URL for your site. It will be used
# in a prominent link
BLOG_DESCRIPTION = "This is a demo site (not a blog) for Nikola."

# Some things in the middle you don't really need to change...

post_pages = (
    ("pages/*.txt", "", "story.tmpl", False),

And now we are ready to cre­ate our first page:

$ nikola new_post -p
Creating New Post

Enter title: index
Your post's text is at:  pages/index.txt


The -p option in the nikola new_post command means we are creating a page and not a blog post.

We can now build and pre­view our site:

$ nikola build
Scanning posts.done!
.  render_site:output/categories/index.html
.  render_sources:output/index.txt
.  render_rss:output/rss.xml
: [Much more of the same]

$ nikola serve
Serving HTTP on port 8000 ...

And you can see your (very emp­ty) site in http://lo­cal­host:8000

So, what's in that pages/index.txt file?

.. title: index
.. slug: index
.. date: 2013/03/01 10:26:17
.. tags:
.. link:
.. description:

Write your post here.

Title is the page title, slug is the name of the generated HTML file (in this case it would be index.html) the date doesn't matter much in not-blogs, same for tags and link. Description is useful for SEO purposes if you care for that.

And be­low, the con­tent. By de­fault you are ex­pect­ed to use re­Struc­tured text but Niko­la sup­ports a ton of for­mat­s, in­clud­ing Mark­down, plain HTM­L, BB­Code, Wik­i, and Tex­tile.

So, let's give the page a nicer ti­tle, and some fake con­tent. Since the de­fault Niko­la theme (called "site") is based on boot­strap you can use any­thing you like from it:

.. title: Welcome To The Fake Site
.. slug: index
.. date: 2013/03/01 10:26:17
.. tags:
.. link:
.. description: Fake Site version 1, welcome page!

.. class:: hero-unit span6

.. admonition:: This is a Fake Site

    It pretends to be about things, but is really just an example.
    So, don't click this button, it leads nowhere.

    .. class:: btn

    Click Me!

.. class:: span5

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris non nunc turpis.
Phasellus a ullamcorper leo. Sed fringilla dapibus orci eu ornare. Quisque
gravida quam a mi dignissim consequat. Morbi sed iaculis mi. Vivamus ultrices
mattis euismod. Mauris aliquet magna eget mauris volutpat a egestas leo rhoncus.
In hac habitasse platea dictumst. Ut sed mi arcu. Nullam id massa eu orci
convallis accumsan. Nunc faucibus sodales justo ac ornare. In eu congue eros.
Pellentesque iaculis risus urna. Proin est lorem, scelerisque non elementum at,
semper vel velit. Phasellus consectetur orci vel tortor tempus imperdiet. Class
aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos

[And more in the same vein]

TIP: Nice URLs

If you like your URLs without the ".html" then you want to create folders and put the pages in index.html inside them. Example:

nikola new_post -p pages/foo/index.txt

which will cre­ate a page you could ac­cess as "http://y­our­site.­com/­foo"

And that's it. You will want to change the SIDEBAR_LINKS option to create a reasonable "menu" for your site, you will want to hack the theme (check nikola help bootswatch_theme for a quick & dirty solution), and you may want to add a blog later on, for company news or whatever.

TIP: So, how do I add a blog now?

First, change the post_pages option like this:

post_pages = (
    ("pages/*.txt", "", "story.tmpl", False),
    ("posts/*.txt", "blog", "post.tmpl", True),

And to avoid a conflict (because blogs try to generate /index.html:

INDEX_PATH = "blog"

Create a post with nikola new_post and that's it, you now have a blog in (you may want to add links to it in SIDEBAR_LINKS of course).

You can see the fin­ished site in http://no­tablog.ralsi­ and its full con­fig­u­ra­tion in //ralsi­­ings/no­tablog/­con­

I hope this was help­ful!

Contents © 2000-2020 Roberto Alsina