Skip to content
Browse files
update docs
Signed-off-by: Chris Warrick <>
  • Loading branch information
Kwpolska committed Jan 13, 2015
1 parent 21bfb8f commit de3727eacb50b67f28c0a4f767f9f27e742139a6
Showing 11 changed files with 419 additions and 153 deletions.

Large diffs are not rendered by default.

@@ -1,3 +1,90 @@
New in v7.3.0


* Added ``-a``, ``--author`` option to set post author field
* Added option INDEXES_PRETTY_PAGE_URL to make URLs for indexes
pages more pretty. (Issue #1548)
* Added ``-i``, ``--import`` argument to ``new_post`` for importing
existing post contents (Issue #1385)
* Added warning about ``password`` in posts being insecure
(Issue #1547)
* INDEXES_TITLE and INDEXES_PAGES are translatable (Issue #1544)
* Added new option ARCHIVES_ARE_INDEXES which allows archive pages
which list posts to be rendered with the post contents.
(Issue #1537)
* Added new option INDEXES_STATIC which allows to define the
page ordering for indexes (Issue #1537). Also, if tag pages are
created as indexes, they will behave more close to the
default indexes.
* Use ``table`` line-numbering style with reST code, making
copy-pasting code possible (Issue #1285)
* Tag and category pages are now more separated. The prefix for
category pages can be changed and the folder can be modified
independently of the tags' folder. (Issue #1535)
* Writing the tag cloud data file can now be disabled. Will be
disabled by default in the future. (Issue #1535)
* The ``utils.config_changed`` function now takes an optional extra
argument, ``identifier``, used to identify the source of a specific
dependency save. As such, ALL your files will be rebuilt after
upgrading. (Issue #1526 via #1521)
* New option GALLERY_FOLDERS replacing GALLERY_PATH (Issue #1511)
* New PANDOC_OPTIONS option (Issue #1492)
* New tab-width option in code-block directive (Issue #1514)
* New option TAG_PAGES_DESCRIPTIONS for optionally making individual
tag pages more unique and interesting (Issue #1486)
* New option LISTINGS_FOLDERS (which replaces LISTINGS_FOLDER) which
allows to separate input and output folder names for listings, and
allows to have more than one listings folder (Issue #1499)
* ReST listing directive now honors alternative listings folder names
(Issue #1499)
* New command line option --conf= to specify the configuration file
(default is (Issue #1501)
* Added Arabic translation (by darkwise)
* Added Danish translation (by mikkelkristiansen)
* Added Indonesian translation (by Willy Sudiarto Raharjo)
* Added Korean translation (by Dong Geun)
* Added Serbian translation (by Ivan Radeljic)
* Added Swedish translation (by Johan Sommerfeld)
* New advanced option RSS_LINKS_APPEND_QUERY for tracking traffic
from RSS subscribers
* Add ``robots`` meta tag with value ``noindex`` for drafts
(Issue #1489)
* New option TAGLIST_MINIMUM_POSTS allows hiding unpopular tags from
the tag index page (Issue #1484)
allow to create non-hierarchical archives and archives for days,
respectively (Issue #1494)
* New plugin for creating image thumbnails, and a corresponding reST
plugin (Issue #1527)


* Handle over-and-under-lined titles in rst for guessing title (Issue #1539)
* Don't apply colorbox to figures if they are of islink class. (Issue #1536)
* Turned minify_lines into a no-op (Issue #1497)
* Don’t classify unpublished posts as pages (Issue #1577)
* Fixed a ``TranslatableSetting.langformat`` race condition
* Fixed ``TranslatableSetting`` instantiation in
``TranslatableSetting.langformat`` (Issue #1571)
* Fixed ``rss.xsl`` path for blogs not deployed to server root
(Issue #1563)
* Respect SHOW_UNTRANSLATED_POSTS = False in archives
and for untranslated source files (Issue #1360)
* Make sure drafts don’t appear in sitemaps with multiple languages
(Issue #1489)
* Make site.posts_per_file cover all languages (Issues #1270, #1489)
* Fix ANNOTATIONS not working at all (Issue #1477)
* Fix asking questions with Unicode chars in Python 2 (Issue #1476)
* Use ADDITIONAL_METADATA with the two-file format (Issue #1471)
* Make previewimage compatible with sites deployed to subdirectories
(Issue #1473)
* Make sitemaps work on sites deployed to subdirectories
(Issue #1472)

New in v7.2.0

@@ -655,7 +742,7 @@ Bugfixes
* Added .rst to the default reStructuredText extensions (via Issue #542)
* Moved the sample site to the new one-file format (Issue #542)
* Escape HTML in titles (Issue #537)
* Fixed issues with index pages indices (Issue #532)
* Fixed issues with index pages indexes (Issue #532)
* Fixed IPython plugin to work with the latest IPython.nbconvert machinery
* Fixed failing build because of hidden folders and files inside post folder

@@ -1,9 +1,9 @@
.. title: Nikola v7.2.0 configuration file
.. title: Nikola v7.3.0 configuration file
.. slug: conf
.. date: 2014-11-08 18:51:30 UTC
.. description: The Nikola configuration file.
.. type: text

The default config file for Nikola v7.2.0 is reproduced below.
The default config file for Nikola v7.3.0 is reproduced below.

.. listing:: python
@@ -1,5 +1,5 @@
.. slug: creating-a-site-not-a-blog-with-nikola
.. date: 2013/03/01 12:49:41
.. date: 2015-01-10 10:00:00 UTC
.. tags: nikola, python
.. link:
.. description:
@@ -10,19 +10,22 @@ Creating a Site (Not a Blog) with Nikola

.. class:: lead

One of the most frequent questions I get about Nikola is "but how do
I create a site that's not a blog?". And of course, that's because the
documentation is heavily blog-oriented. This document will change that ;-)
One of the most frequent questions I get about Nikola is but how do
I create a site thats not a blog?. And of course, thats because the
documentation is heavily blogoriented. This document will change that ;-)

Since it started, Nikola has had the capabilities to create generic sites. For example,
Nikola's `own site <>`_ is a fairly generic one. Let's go
Nikolas `own site <>`_ is a fairly generic one. Lets go
step by step on how you can do something like that.

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

$ nikola init mysite
Created empty site at mysite.
Creating Nikola Site
[1970-01-01T00:00:00Z] INFO: init: Created empty site at mysite.

Then we go into the new ``mysite`` folder, and make the needed changes in the ````
configuration file:
@@ -40,8 +43,8 @@ configuration file:
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."

@@ -58,12 +61,13 @@ configuration file:

And now we are ready to create our first page::

$ nikola new_post -p
Creating New Post
$ nikola new_page
Creating New Page

Enter title: index
Your post's text is at: pages/index.txt
Title: index
Scanning posts....done!
[1970-01-01T00:00:00Z] INFO: new_page: Your page's text is at: stories/index.rst

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

@@ -74,32 +78,30 @@ We can now build and preview our site::
. 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 ...
[1970-01-01T00:00:00Z] INFO: serve: Serving HTTP on port 8000...

And you can see your (very empty) site in http://localhost:8000
And you can see your (very empty) site in http://localhost:8000/

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

.. code-block:: rest

.. title: index
.. slug: index
.. date: 2013/03/01 10:26:17
.. date: 1970-01-01 00:00:00 UTC
.. 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
``title`` is the page title, ``slug`` is the name of the generated HTML file
(in this case it would be ``index.html``). ``date``, ``tags`` and ``link``
doesn’t matter at all in stories. ``description`` is useful for SEO purposes
if you care for that.

And below, the content. By default you are expected to use
@@ -108,32 +110,31 @@ Nikola supports a ton of formats, including Markdown, plain HTML, BBCode,
Wiki, and Textile.

So, let's give the page a nicer title, and some fake content. Since the default
Nikola theme (called "bootstrap") is based on `bootstrap 2 <>`_
Nikola theme (called ``bootstrap3``) is based on `Bootstrap <>`_
you can use anything you like from it:

.. code-block:: rest

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

.. class:: hero-unit span6
.. class:: jumbotron col-md-6

.. 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
.. raw:: html

Click Me!
<a href="" class="btn btn-primary btn-lg">Click Me!</a>

.. class:: span5
.. class:: col-md-5

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris non nunc turpis.
Phasellus a ullamcorper leo. Sed fringilla dapibus orci eu ornare. Quisque
@@ -146,15 +147,13 @@ you can use anything you like from it:
aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos

[And more in the same vein]

.. admonition:: TIP: Nice URLs

If you like your URLs without the ".html" then you want to create folders and
If you like your URLs without the ``.html`` then you want to create folders and
put the pages in ``index.html`` inside them using the ``PRETTY_URLS`` option.

And that's it. You will want to change the NAVIGATION_LINKS option to create a reasonable
"menu" for your site, you will want to hack the theme (check ``nikola help bootswatch_theme``
menu for your site, you will want to modify 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.

@@ -167,9 +166,10 @@ or whatever.
POSTS = [("posts/*.txt", "blog", "post.tmpl", True)]

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 NAVIGATION_LINKS of course).
in the ``/blog/`` subdirectory of your site — you may want to link to

You can see the finished site in and its full configuration in
If you want to see a site implementing all of the above, check out `the Nikola
website <>`_.

I hope this was helpful!
@@ -17,6 +17,10 @@ so we get good support for slides and galleries.

I will try to create a theme that looks like `Vinicius Massuchetto's Monospace Theme <>`_.

.. danger::

This document is outdated! Recommendations in this post may not work!


Starting The Theme
@@ -8,7 +8,7 @@
Extending Nikola

:Version: 7.2.0
:Version: 7.3.0
:Author: Roberto Alsina <>

.. class:: alert alert-info pull-right
@@ -3,7 +3,7 @@
.. date: 1970-01-01 15:00:00
.. description: Get help using Nikola, or contact us.

:Version: 7.2.0
:Version: 7.3.0

.. class:: alert alert-info pull-right

0 comments on commit de3727e

Please sign in to comment.