Commit 626477b9 authored by Sukil Etxenike's avatar Sukil Etxenike

Initial commit

image: python:3.5
- pip install "nikola[extras]"
- nikola build
- public
This diff is collapsed.
.. title: Nikola Tesla
Some public domain pictures of Nikola Tesla
(copied from `here <>`_)
import sys
def hello(name='world'):
greeting = "hello " + name
if __name__ == "__main__":
.. title: Welcome to Nikola
.. slug: welcome-to-nikola
.. date: 2012-03-30 23:00:00 UTC-03:00
.. tags: nikola, python, demo, blog
.. author: Roberto Alsina
.. link:
.. description:
.. category: nikola
.. figure::
:class: thumbnail
:alt: Nikola Tesla Corner by nicwest, on Flickr
If you can see this in a web browser, it means you managed to install Nikola,
and build a site using it. Congratulations!
Next steps:
* :doc:`Read the manual <handbook>`
* `Visit the Nikola website to learn more <>`__
* `See a demo photo gallery <link://gallery/demo>`__
* :doc:`See a demo listing <listings-demo>`
* :doc:`See a demo slideshow <slides-demo>`
* :doc:`See a demo of a longer text <dr-nikolas-vendetta>`
Send feedback to!
![Build Status](
Example [nikola] website using GitLab Pages.
Learn more about GitLab Pages at and the official
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
**Table of Contents** *generated with [DocToc](*
- [GitLab CI](#gitlab-ci)
- [Building locally](#building-locally)
- [GitLab User or Group Pages](#gitlab-user-or-group-pages)
- [Did you fork this project?](#did-you-fork-this-project)
- [Troubleshooting](#troubleshooting)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## GitLab CI
This project's static Pages are built by [GitLab CI][ci], following the steps
defined in [`.gitlab-ci.yml`](.gitlab-ci.yml):
- pip install "nikola[extras]"
- nikola build
- public
## Building locally
To work locally with this project, you'll have to follow the steps below:
1. Fork, clone or download this project
1. [Install][] Nikola
1. Generate the website: `nikola build`
1. Preview your project: `nikola serve`
1. Add content
Read more at Nikola's [documentation][].
## GitLab User or Group Pages
To use this project as your user/group website, you will need one additional
step: just rename your project to ``, where `namespace` is
your `username` or `groupname`. This can be done by navigating to your
project's **Settings**.
Read more about [user/group Pages][userpages] and [project Pages][projpages].
## Did you fork this project?
If you forked this project for your own use, please go to your project's
**Settings** and remove the forking relationship, which won't be necessary
unless you want to contribute back to the upstream project.
## Troubleshooting
1. CSS is missing! That means two things:
Either that you have wrongly set up the CSS URL in your templates, or
your static generator has a configuration option that needs to be explicitly
set in order to serve static assets under a relative URL.
\ No newline at end of file
.. title: Nikola: it generates static
.. slug: about-nikola
.. date: 2012-03-30 23:00:00 UTC-03:00
.. tags:
.. link:
.. description:
Hope you enjoy this software!
* Home page at
* Author's blog (and reason why Nikola exists):
This diff is collapsed.
.. link:
.. description:
.. tags:
.. date: 2013-08-27 18:20:55 UTC-03:00
.. title: Charts
.. slug: charts
If you are using reStructuredText and install pygal, Nikola has support for rather nice charts
with little effort, and i's even semi-interactive (hover your pointer over the legend!):
.. code:: rest
.. chart:: StackedLine
:title: 'Browser usage evolution (in %)'
:fill: True
:x_labels: ['2002','2003','2004','2005','2006','2007','2008','2009','2010','2011','2012']
:width: 600
:height: 400
:explicit_size: True
:style: BlueStyle
('Others', [14.2, 15.4, 15.3, 8.9, 9, 10.4, 8.9, 5.8, 6.7, 6.8, 7.5])
('IE', [85.8, 84.6, 84.7, 74.5, 66, 58.6, 54.7, 44.8, 36.2, 26.6, 20.1])
('Firefox', [None, None, None, 16.6, 25, 31, 36.4, 45.5, 46.3, 42.8, 37.1])
('Chrome', [None, None, None, None, None, None, 0, 3.9, 10.8, 23.8, 35.3])
.. raw:: html
<div style="text-align: center;">
.. chart:: StackedLine
:title: 'Browser usage evolution (in %)'
:fill: True
:x_labels: ['2002','2003','2004','2005','2006','2007','2008','2009','2010','2011','2012']
:width: 600
:height: 400
:explicit_size: True
:style: BlueStyle
('Others', [14.2, 15.4, 15.3, 8.9, 9, 10.4, 8.9, 5.8, 6.7, 6.8, 7.5])
('IE', [85.8, 84.6, 84.7, 74.5, 66, 58.6, 54.7, 44.8, 36.2, 26.6, 20.1])
('Firefox', [None, None, None, 16.6, 25, 31, 36.4, 45.5, 46.3, 42.8, 37.1])
('Chrome', [None, None, None, None, None, None, 0, 3.9, 10.8, 23.8, 35.3])
.. raw:: html
Here's how it works:
* Next to the directive, use the `chart type you want <>`_
* Any option you can set in a chart? Use it like ``:title:`` in this example. Syntax on
the value is just like in the pygal examples.
* For each data series do it like the line that says ``Firefox`` in this example. The first element
is the label, then comes the data.
Easy, right? Please explore `the pygal site <>`_ for more information, and just
take this example and tweak stuff.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
.. title: Nikola Internals
.. slug: internals
.. date: 2012-03-30 23:00:00 UTC-03:00
.. tags:
.. link:
.. description:
.. author: The Nikola Team
Nikola Internals
.. class:: lead
When trying to guide someone into adding a feature in Nikola, it hit me that
while the way it's structured makes sense **to me** it is far from obvious.
So, this is a short document explaining what each piece of Nikola does and
how it all fits together.
Nikola is a Pile of Plugins
Most of Nikola is implemented as plugins using `Yapsy <>`_.
You can ignore that they are plugins and just think of them as regular python
modules and packages with a funny little ``.plugin`` file next to them.
So, 90% of the time, what you want to do is either write a new plugin or extend
an existing one.
There are several kinds of plugins, all implementing interfaces defined in
``nikola/`` and documented in
`Extending Nikola <>`_
If your plugin has a dependency, please make sure it doesn't make Nikola
throw an exception when the dependency is missing. Try to fail gracefully
with an informative message.
Commands are plugins
When you use ``nikola foo`` you are using the plugin ``command/foo``. Those are
used to extend Nikola's command line. Their interface is defined in the ``Command``
class. They take options and arguments and do whatever you want, so go wild.
The ``build`` command is special
The ``build`` command triggers a whole lot of things, and is the core of Nikola
because it's the one that you use to build sites. So it deserves its own section.
The Build Command
Nikola's goal is similar, deep at heart, to a Makefile. Take sources, compile them
into something, in this case a website. Instead of a Makefile, Nikola uses
`doit <>`_
Doit has the concept of "tasks". The 1 minute summary of tasks is that they have:
What the task **does**. For example, convert a markdown document into HTML.
If this file changes, then we need to redo the actions. If this configuration
option changes, redo it, etc.
Files that the action generates. No two actions can have the same targets.
Each task is identified by either a name or a basename:name pair.
.. sidebar:: More about tasks
If you ever want to do your own tasks, you really should read the doit
`documentation on tasks <>`_
So, what Nikola does, when you use the build command, is to read the
configuration ```` from the current folder, instantiate
the ``Nikola`` class, and have it generate a whole list of tasks for doit
to process. Then doit will decide which tasks need doing, and do them, in
the right order.
The place where the tasks are generated is in ``Nikola.gen_tasks``, which collects tasks
from all the plugins inheriting ``BaseTask``, massages them a bit, then passes them
to doit.
So, if you want things to happen on ``build`` you want to create a Task plugin, or extend
one of the existing ones.
.. sidebar:: Tests
While Nikola is not a hardcore TDD project, we like tests. So, please add them if you can.
You can do doctests, you can do unit tests, you can do integration tests. There is support
for all of them.
Posts and Stories
Nikola has a concept of posts and stories. Both are more or less the same thing, except
posts are added into RSS feeds and stories are not. All of them are in a list called
"the timeline" formed by objects of class ``Post``.
When you are creating a task that needs the list of posts and/or stories (for example,
the RSS creation plugin) on task execution time, your plugin should call ````
in ``gen_tasks`` to ensure the timeline is created and available in
````. You should not modify the timeline, because it will cause consistency issues.
.. sidebar:: scan_posts
The ``Nikola.scan_posts`` function can be used in plugins to force the
timeline creation, for example, while creating the tasks.
Your plugin can use the timeline to generate "stuff" (technical term). For example,
Nikola comes with plugins that use the timeline to create a website (surprised?).
The workflow included with nikola is as follows (incomplete!):
#. The post is assigned a compiler based on its extension and the ``COMPILERS`` option.
#. The compiler is applied to the post data and a "HTML fragment" is produced. That
fragment is stored in a cache (the ``posts`` plugin).
#. The configured theme has templates (and a template engine), which are applied to the post's
HTML fragment and metadata (the ``pages`` plugin).
#. The original sources for the post are copied to some accessible place (the ``sources`` plugin).
#. If the post is tagged, some pages and RSS feeds for each tag are updated (the ``tags`` plugin).
#. If the post is new, it's included in the blog's RSS feed (the ``rss`` plugin).
#. The post is added in the right place in the index pages for the blog (the ``indexes`` plugin).
#. CSS/JS/Images for the theme are put in the right places (the ``copy_assets`` and ``bundles`` plugins).
#. A File describing the whole site is created (the ``sitemap`` plugin).
You can add whatever you want to that list: just create a plugin for it.
You can also expand Nikola's capabilities at several points:
Nikola supports a variety of markups. If you want to add another one, you need to create
a ``Compiler`` plugin.
Nikola's themes can use Jinja2 or Mako templates. If you prefer another template system,
you have to create a ``TemplateSystem`` plugin.
To change how the generated site looks, you can create custom themes.
And of course, you can also replace or extend each of the existing plugins.
Nikola Architecture
.. thumbnail::
.. title: Listings Demo
.. slug: listings-demo
.. date: 2012-12-15 10:16:20 UTC-03:00
.. tags:
.. link:
.. description:
Nikola intends to let you show code easily via listings:
.. listing:: python
This diff is collapsed.
.. title: Path Handlers for Nikola
.. slug: path-handlers
.. author: The Nikola Team
Nikola supports special links with the syntax ``link://kind/name``. In the templates you can also
use ``_link(kind, name)`` Here is the description for all the supported kinds.
.. class:: dl-horizontal
Link to archive path, name is the year.
link://archive/2013 => /archives/2013/index.html
Link to atom archive path, name is the year.
link://archive_atom/2013 => /archives/2013/index.atom
Link to an author's page.
link://author/joe => /authors/joe.html
Link to an author's Atom feed.
link://author_atom/joe => /authors/joe.atom
Link to the author's index.
link://authors/ => /authors/index.html
Link to an author's RSS feed.
link://author_rss/joe => /authors/joe.rss
A link to a category.
link://category/dogs => /categories/dogs.html
A link to a category's Atom feed.
link://category_atom/dogs => /categories/dogs.atom
A link to the category index.
link://category_index => /categories/index.html
A link to a category's RSS feed.
link://category_rss/dogs => /categories/dogs.xml
Link to post or story by source filename.
link://filename/manual.txt => /docs/handbook.html
Link to an image gallery's path.
It will try to find a gallery with that name if it's not ambiguous
or with that path. For example:
link://gallery/london => /galleries/trips/london/index.html
link://gallery/trips/london => /galleries/trips/london/index.html
Link to the global gallery path, which contains all the images in galleries.
There is only one copy of an image on multilingual blogs, in the site root.
link://gallery_global/london => /galleries/trips/london/index.html
link://gallery_global/trips/london => /galleries/trips/london/index.html
(a ``gallery`` link could lead to eg. /en/galleries/trips/london/index.html)
Link to an image gallery's RSS feed.
It will try to find a gallery with that name if it's not ambiguous
or with that path. For example:
link://gallery_rss/london => /galleries/trips/london/rss.xml
link://gallery_rss/trips/london => /galleries/trips/london/rss.xml
Link to a numbered index.
link://index/3 => /index-3.html
Link to a numbered Atom index.
link://index_atom/3 => /index-3.atom
A link to a listing.
It will try to use the file name if it's not ambiguous, or the file path.
link://listing/ => /listings/tutorial/
link://listing/tutorial/ => /listings/tutorial/
Link to the destination of an element in the POSTS/PAGES settings.
link://post_path/posts => /blog
Link to the current language's root.
link://root_path => /
link://root_path => /translations/spanish/
A link to the RSS feed path.
link://rss => /blog/rss.xml
Link to the index for a section.
link://section_index/cars => /cars/index.html
Link to the Atom index for a section.
link://section_index_atom/cars => /cars/index.atom
A link to a post with given slug, if not ambiguous.
link://slug/yellow-camaro => /posts/cars/awful/yellow-camaro/index.html
A link to a tag's page.
link://tag/cats => /tags/cats.html
A link to a tag's Atom feed.
link://tag_atom/cats => /tags/cats.atom
A link to the tag index.
link://tag_index => /tags/index.html
A link to a tag's RSS feed.
link://tag_rss/cats => /tags/cats.xml
This diff is collapsed.
This diff is collapsed.
.. title: Slides Demo
.. slug: slides-demo
.. date: 2012-12-27 10:16:20 UTC-03:00
.. tags:
.. link:
.. description:
Nikola intends to let you do slideshows easily:
.. slides::
.. title: Alternative Social Buttons
.. slug: social_buttons
.. date: 2013-08-19 23:00:00 UTC-03:00
.. tags:
.. link:
.. description:
.. author: The Nikola Team
Using Alternative Social Buttons with Nikola
:Version: 7.7.8
.. class:: alert alert-info pull-right
.. contents::
The Default
By Default, the themes provided with Nikola will add to your pages a "slide in" widget at
the bottom right of the page, provided by Addthis. This is the HTML code for that:
.. code-block:: html
<!-- Social buttons -->
<div id="addthisbox" class="addthis_toolbox addthis_peekaboo_style
addthis_default_style addthis_label_style addthis_32x32_style">
<a class="addthis_button_more">Share</a>
<ul><li><a class="addthis_button_facebook"></a>
<li><a class="addthis_button_google_plusone_share"></a>
<li><a class="addthis_button_linkedin"></a>
<li><a class="addthis_button_twitter"></a>
<script src="//"></script>
<!-- End of social buttons -->
You can change that using the ``SOCIAL_BUTTONS_CODE`` option in your In some cases, just
doing that will be enough but in others, it won't. This document tries to describe all the bits
involved in making this work correctly.
Social sharing services like addthis and others will provide you a HTML snippet.
If it is self-contained, then just setting ``SOCIAL_BUTTONS_CODE`` may be enough.
Try :-)
Part 2: The theme
The ``SOCIAL_BUTTONS_CODE`` HTML fragment will be embedded *somewhere* by the theme. Whether that
is the correct place or not is not something the theme author can truly know, so it is possible that
you may have to tweak the ``base.html`` template to make it look good.
Part 3: ``BODY_END`` and ``EXTRA_HEAD_DATA``
Some social sharing code requires JS execution that depends on JQuery being available
(example: `SocialSharePrivacy <>`__). It's good
practice (and often, the only way that will work) to put those at the end of ``<BODY>``,
and one easy way to do that is to put them in ``BODY_END``
On the other hand, it's possible that it requires you to load some CSS files.
The right place for that is in the document's ``<HEAD>`` so they should be added
Part 4: assets
For sharing code that doesn't rely on a social sharing service, you may need to add CSS, Image, or JS
files to your site
`Sharenice <>`__ is "written in order to provide social sharing features to
web developers and website administrators who wish to maintain and protect their users' privacy"
which sounds cool to me.
Let's go step by step into integrating the hosted version of ShareNice into a Nikola site.
For testing purposes, let's do it on a demo site::
$ nikola init --demo sharenice_test
A new site with example data has been created at sharenice_test.
See README.txt in that folder for more information.
$ cd sharenice_test/
To see what's going on, let's start Nikola in "auto mode". This should build the
site and open a web browser showing the default configuration, with the AddThis widget::
$ nikola auto -b
First, let's add the HTML snippet that will show the sharing options. In your, set this, which
is the HTML code suggested by ShareNice:
.. code-block:: python