diff options
Diffstat (limited to 'docs/manual.txt')
| -rw-r--r-- | docs/manual.txt | 719 |
1 files changed, 557 insertions, 162 deletions
diff --git a/docs/manual.txt b/docs/manual.txt index 4833eae..c186260 100644 --- a/docs/manual.txt +++ b/docs/manual.txt @@ -1,7 +1,14 @@ +.. title: The Nikola Handbook +.. slug: handbook +.. date: 2012/03/30 23:00 +.. tags: +.. link: +.. description: + The Nikola Handbook =================== -:Version: 5.4.4 +:Version: 6.2.1 .. class:: alert alert-info pull-right @@ -11,7 +18,7 @@ The Nikola Handbook All You Need to Know -------------------- -After you have Nikola installed: +After you have Nikola `installed <#installing-nikola>`_: Create a empty site: ``nikola init mysite`` @@ -57,10 +64,10 @@ instead of something the user generates. Nikola can do: -* A blog (`example <http://lateral.netmanagers.com.ar>`__) +* A blog (`example <http://ralsina.me>`__) * Your company's site * Your personal site -* A software project's site (`example <http://nikola.ralsina.com.ar>`__) +* A software project's site (`example <http://getnikola.com>`__) * A book's site Since Nikola-based sites don't run any code on the server, there is no way to process @@ -71,7 +78,7 @@ Nikola can't do: * Twitter * Facebook * An Issue tracker -* Anything with forms, really (except for comments_!) +* Anything with forms, really (except for `comments <#comments-and-annotations>`_!) Keep in mind that "static" doesn't mean **boring**. You can have animations, slides or whatever fancy CSS/HTML5 thingie you like. It only means all that HTML is @@ -83,10 +90,10 @@ Getting Help ------------ * Feel free to contact me at ralsina@netmanagers.com.ar for questions about Nikola. -* You can file bugs at `the issue tracker <https://github.com/ralsina/nikola-site/issues>`__ +* You can file bugs at `the issue tracker <https://github.com/getnikola/nikola/issues>`__ * You can discuss Nikola at the `nikola-discuss google group <http://groups.google.com/group/nikola-discuss>`_ -* You can subscribe to `the Nikola Blog <http://nikola.ralsina.com.ar/blog>`_ -* You can follow `Nikola on Twitter <https://twitter.com/#!/nikolagenerator>`_ +* You can subscribe to `the Nikola Blog <http://getnikola.com/blog>`_ +* You can follow `Nikola on Twitter <https://twitter.com/nikolagenerator>`_ Why Static? ----------- @@ -106,13 +113,13 @@ Security Dynamic sites are prone to experience security issues. The solution for that is constant vigilance, keeping the software behind the site updated, and plain old good luck. The stack of software used to provide a static site, - like those Nikola generates, is much smaller (Just a webserver). + like those Nikola generates, is much smaller (Just a web server). A smaller software stack implies less security risk. Obsolescense - If you create a site using (for example) Wordpress, what happens when Wordpress - releases a new version? You have to update your Wordpress. That is not optional, + If you create a site using (for example) WordPress, what happens when WordPress + releases a new version? You have to update your WordPress. That is not optional, because of security and support issues. If I release a new version of Nikola, and you don't update, *nothing* happens. You can continue to use the version you have now forever, no problems. @@ -142,7 +149,7 @@ Cost and Performance Lockin On server-side blog platforms, sometimes you can't export your own data, or it's in strange formats you can't use in other services. I have switched - blogging platforms from Advogato to PyCs to two homebrewed systems, to Nikola, + blogging platforms from Advogato to PyCs to two homebrew systems, to Nikola, and have never lost a file, a URL, or a comment. That's because I have *always* had my own data in a format of my choice. @@ -151,7 +158,7 @@ Lockin Features -------- -Nikola has a very defined featureset: it has every feature I needed for my own sites. +Nikola has a very defined feature set: it has every feature I needed for my own sites. Hopefully, it will be enough for others, and anyway, I am open to suggestions. If you want to create a blog or a site, Nikola provides: @@ -168,7 +175,7 @@ If you want to create a blog or a site, Nikola provides: * Google sitemap generation * Custom deployment (if it's a command, you can use it) * A (very) basic look and feel you can customize, and is even text-mode friendly -* The input format is light markup (`reStructuredText <quickstart.html>`_ or +* The input format is light markup (`reStructuredText <quickstart.html>`__ or `Markdown <http://daringfireball.net/projects/markdown/>`_) * Easy-to-create image galleries * Support for displaying source code @@ -177,7 +184,7 @@ If you want to create a blog or a site, Nikola provides: Also: -* A preview webserver +* A preview web server * "Live" re-rendering while you edit * "Smart" builds: only what changed gets rebuilt (usually in seconds) * Easy to extend with minimal Python knowledge. @@ -189,28 +196,40 @@ This is currently lacking on detail. Considering the niche Nikola is aimed at, I suspect that's not a problem yet. So, when I say "get", the specific details of how to "get" something for your specific operating system are left to you. -The short version is: ``pip install https://github.com/ralsina/nikola/archive/master.zip`` +The short version is: ``pip install nikola`` + +Note that you need Python v2.6 or newer OR v3.3 or newer. + +For some features it may give you an error message telling you that you need to +install something else. For example, if it tells you you need ``requests``:: + + pip install requests + +And so on. Longer version: -#. Get `Nikola <http://nikola.ralsina.com.ar/>`_ +#. Get `Nikola <http://getnikola.com/>`_ #. Install dependencies. To do that, either: - #. ``pip install -r requirements.txt`` and ``pip install .`` or... + #. ``pip install -r requirements.txt`` (or ``requirements-full.txt`` + for extra stuff) and ``pip install .`` or... #. Install your distribution's packages for all the things mentioned below, if they exist, or... #. Get all of these manually (but why?, use pip): - #. Get python, if you don't have it. + #. Get Python, if you don't have it. #. Get `doit <http://pydoit.org>`_ #. Get `docutils <http://docutils.sf.net>`_ #. Get `Mako <http://makotemplates.org>`_ - #. Get `PIL <http://www.pythonware.com/products/pil/>`_ (or Pillow) + #. Get `Pillow <http://python-imaging.github.io/>`_ #. Get `Pygments <http://pygments.org/>`_ #. Get `unidecode <http://pypi.python.org/pypi/Unidecode/>`_ #. Get `lxml <http://lxml.de/>`_ #. Get `yapsy <http://yapsy.sourceforge.net>`_ - #. Get `configparser <http://pypi.python.org/pypi/configparser/3.2.0r3>`_ + #. Get `PyRSS2Gen <http://www.dalkescientific.com/Python/PyRSS2Gen.html>`_ + #. Get `pytz <http://pytz.sourceforge.net/>`_ + #. If using Python 2, get `configparser <http://pypi.python.org/pypi/configparser/3.2.0r3>`_ #. run ``python setup.py install`` @@ -222,33 +241,65 @@ Nikola is packaged for some Linux distributions, you may get that instead. *NOTE*: If you get a ``ERROR: /bin/sh: 1: xslt-config: not found`` or ``fatal error: libxml/xmlversion.h: No such file or directory`` when running ``pip install -r requirements.txt``, install *libxml* and *libxslt* libraries, like so: -Debian systems: +Debian systems:: sudo apt-get install libxml2-dev sudo apt-get install libxslt1-dev -RHEL systems: +Red Hat/RPM based systems:: yum install libxslt-devel libxml2-devel +Installation on Linux, Mac OS X, \*BSD, and any other POSIX-compatible OS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(we obviously support all.) + +Using ``pip`` should suffice. You may also want to use distribution- or +system-specific packages for our dependencies. + +There are **no known issues or caveats** on those OSes. Keep in mind that most +of our developers run Linux on a daily basis and may not have the full +knowledge required to resolve issues relating to your operating system. + +Installation on Windows and Windows support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Nikola supports Windows! Keep in mind, though, that there are some +caveats: + +1. ``lxml`` and ``Pillow`` require compiled extensions. Compiling them on +Windows is hard for most people. Fortunately, compiled packages exist. Check +their `PyPI <https://pypi.python.org/>`_ pages to find official packages, `the unofficial Gohlke binaries <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_ site, or get them somewhere else. If you are using virtualenvs, using those pre-built packages is possible through ``virtualenv --system-site-packages``. +2. Windows has some differences over POSIX, which may cause some features to work incorrectly under Windows. If any problems occur, please do not hesitate to report them. Some of the differeces include: + + * ``\`` as path separator (instead of ``/``) + * the concept of partitions + * some characters in paths are disallowed (although this shouldn’t cause + problems) + * CR+LF (aka ``\r\n``) as the line separator (instead of LF ``\n``) + +3. Windows also dislikes some characters in paths. +4. Most of our developers run Linux on a daily basis and may not have the full knowledge required to resolve issues relating to Windows. + Getting Started --------------- To create posts and pages in Nikola, you write them in one of the supported input formats. Those source files are later converted to HTML -The recommended formats are restructured text and Markdown, but there is also support +The recommended formats are reStructuredText and Markdown, but there is also support for textile and WikiCreole and even for just writing HTML. -.. note:: There is a great `quick tutorial to learn restructured text. <quickstart.html>`_ +.. note:: There is a great `quick tutorial to learn reStructuredText. <quickstart.html>`__ First, let's see how you "build" your site. Nikola comes with a minimal site to get you started. -The tool used to do builds is called `doit <http://pydoit.org>`_, and it rebuilds the +The tool used to do builds is called `doit <http://pydoit.org>`__, and it rebuilds the files that are not up to date, so your site always reflects your latest content. To do our first build, just run "nikola build":: $ nikola build - Scanning posts . . done! + Scanning posts....done! . render_posts:stories/manual.html . render_posts:posts/1.html . render_posts:stories/1.html @@ -260,17 +311,17 @@ first build, just run "nikola build":: . render_pages:output/stories/handbook.html . render_rss:output/rss.xml . render_sources:output/stories/about-nikola.txt - : - : - : + ⋮ + ⋮ + ⋮ Nikola will print a line for every output file it generates. If we do it again, that will be much much shorter:: $ nikola build - Scanning posts . . done! + Scanning posts....done! -That is because `doit <http://pydoit.org>`_ is smart enough not to generate +That is because `doit <http://pydoit.org>`__ is smart enough not to generate all the pages again, unless you changed something that the page requires. So, if you change the text of a post, or its title, that post page, and all index pages where it is mentioned, will be recreated. If you change the post page template, then all the post pages will be rebuilt. @@ -278,7 +329,7 @@ will be recreated. If you change the post page template, then all the post pages Nikola is mostly a series of doit *tasks*, and you can see them by doing ``nikola list``:: $ nikola list - Scanning posts . . done! + Scanning posts....done! build_bundles copy_assets copy_files @@ -296,39 +347,46 @@ Nikola is mostly a series of doit *tasks*, and you can see them by doing ``nikol render_tags sitemap -You can make Nikola redo everything by calling ``nikola build forget``, you can make it do just a specific -part of the site using task names, for example ``nikola build render_pages``, and even individual files like -``nikola build render_indexes:output/index.html`` +You can make Nikola redo everything by calling ``nikola forget`` and then ``nikola build`` (or ``nikola build -a``, +you can make it do just a specific part of the site using task names, for example ``nikola build render_pages``, +and even individual files like ``nikola build output/index.html`` Nikola also has other commands besides ``build``:: $ nikola help - Nikola - Available commands: - nikola auto automatically execute tasks when a dependency changes - nikola bootswatch_theme Given a swatch name and a parent theme, creates a custom theme. - nikola build run tasks - nikola check Check links and files in the generated site. - nikola clean clean action / remove targets - nikola console A short explanation. - nikola deploy Deploy the site. - nikola dumpdb dump dependency DB - nikola forget clear successful run status from internal DB - nikola help show help - nikola ignore ignore task (skip) on subsequent runs - nikola import_blogger Import a blogger dump. - nikola import_wordpress Import a wordpress dump. - nikola init Create a Nikola site in the specified folder. - nikola install_theme Install theme into current site. - nikola list list tasks from dodo file - nikola new_post Create a new blog post or site page. - nikola run run tasks - nikola serve Start the test webserver. - nikola strace use strace to list file_deps and targets - - nikola help show help / reference - nikola help <command> show command usage - nikola help <task-name> show task usage + Nikola is a tool to create static websites and blogs. For full documentation and more information, + please visit http://getnikola.com + + + Available commands: + nikola auto automatically detect site changes, rebuild and optionally refresh a browser + nikola bootswatch_theme given a swatch name from bootswatch.com and a parent theme, creates a custom theme + nikola build run tasks + nikola check check links and files in the generated site + nikola clean clean action / remove targets + nikola console start an interactive python console with access to your site and configuration + nikola deploy deploy the site + nikola dumpdb dump dependency DB + nikola forget clear successful run status from internal DB + nikola help show help + nikola ignore ignore task (skip) on subsequent runs + nikola import_blogger import a blogger dump + nikola import_feed import a RSS/Atom dump + nikola import_wordpress import a WordPress dump + nikola init create a Nikola site in the specified folder + nikola install_theme install theme into current site + nikola list list tasks from dodo file + nikola mincss apply mincss to the generated site + nikola new_post create a new blog post or site page + nikola run run tasks + nikola serve start the test webserver + nikola strace use strace to list file_deps and targets + nikola version print the Nikola version number + + nikola help show help / reference + nikola help <command> show command usage + nikola help <task-name> show task usage + The ``serve`` command starts a web server so you can see the site you are creating:: @@ -340,7 +398,7 @@ After you do this, you can point your web browser to http://localhost:8000 and y the sample site. This is useful as a "preview" of your work. By default, the ``serve`` command runs the web server on port 8000 on the IP address 127.0.0.1. -You can pass in an IP address and port number explicity using ``-a IP_ADDRESS`` +You can pass in an IP address and port number explicitly using ``-a IP_ADDRESS`` (short version of ``--address``) or ``-p PORT_NUMBER`` (short version of ``--port``) Example usage:: @@ -358,14 +416,14 @@ By default, that file will contain also some extra information about your post ( It can be placed in a separate file by using the ``-2`` option, but it's generally easier to keep it in a single location. -The contents of your post have to be written (by default) in `restructured text <http://docutils.sf.net>`_ +The contents of your post have to be written (by default) in `reStructuredText <http://docutils.sf.net>`__ but you can use a lot of different markups using the ``-f`` option. Currently Nikola supports bbcode, wiki, markdown, html, txt2tags and textile in addition -to restructured text. +to reStructuredText. -You can control what markup compiler is used for each file extension with the ``post_compilers`` +You can control what markup compiler is used for each file extension with the ``COMPILERS`` option. The default configuration expects them to be placed in ``posts`` but that can be -changed (see below, the post_pages option) +changed (see below, the ``POSTS`` and ``PAGES`` options) This is how it works:: @@ -387,7 +445,7 @@ The content of that file is as follows:: Write your post here. -The ``slug`` is the pagename. Since often titles will have +The ``slug`` is the page name. Since often titles will have characters that look bad on URLs, it's generated as a "clean" version of the title. The third line is the post's date, and is set to "now". @@ -397,6 +455,15 @@ source for the content, and ``description`` is mostly useful for SEO. You can add your own metadata fields in the same manner, if you use a theme that supports them (for example: ``.. author: John Doe``) +To add these metadata fields to all new posts by default, you can set the +variable ``ADDITIONAL_METADATA`` in your configuration. For example, you can +add the author metadata to all new posts by default, by adding the following +to your configuration :: + + ADDITIONAL_METADATA = { + 'author': 'John Doe' + } + .. sidebar:: Other Metadata Fields Nikola will also use other metadata fields: @@ -411,10 +478,28 @@ supports them (for example: ``.. author: John Doe``) .. template: story.tmpl + That template needs to either be part of the theme, or be placed in a ``templates/`` + folder inside your site. + password The post will be encrypted and invisible until the reader enters the password. Also, the post's sourcecode will not be available. + category + Like tags, except each post can have only one, and they usually have + more descriptive names. + + annotations / noannotations + Override the value of the ``ANNOTATIONS`` option for this specific post or page. + + author + Author of the post, will be used in the RSS feed and possibly in the post + display (theme-dependent) + + hidetitle + Set "True" if you do not want to see the **story** title as a + heading of the page (does not work for posts). + .. note:: The Two-File Format @@ -431,7 +516,7 @@ post file (for example: ``how-to-make-money.txt.es``). This one can replace metadata of the default language, for example: * The translated title for the post or page -* A translated version of the pagename +* A translated version of the page name You can edit these files with your favourite text editor, and once you are happy with the contents, generate the pages as explained in `Getting Started`_ @@ -450,19 +535,21 @@ Currently supported languages are * Spanish If you wish to add support for more languages, check out the instructions -at the `theming guide <http://nikola.ralsina.com.ar/theming.html>`_. +at the `theming guide <http://getnikola.com/theming.html>`_. The post page is generated using the ``post.tmpl`` template, which you can use to customize the output. -The place where the post will be placed by ``new_post`` is based on the ``post_pages`` -configuration option:: +The place where the post will be placed by ``new_post`` is based on the ``POSTS`` +and ``PAGES`` configuration options:: - # post_pages contains (wildcard, destination, template, use_in_feed) tuples. + # POSTS and PAGES contains (wildcard, destination, template) tuples. + # + # The wildcard is used to generate a list of reSt source files + # (whatever/thing.txt). # - # The wildcard is used to generate a list of reSt source files (whatever/thing.txt) - # That fragment must have an associated metadata file (whatever/thing.meta), - # and opcionally translated files (example for spanish, with code "es"): + # That fragment could have an associated metadata file (whatever/thing.meta), + # and optionally translated files (example for spanish, with code "es"): # whatever/thing.txt.es and whatever/thing.meta.es # # From those files, a set of HTML fragment files will be generated: @@ -472,18 +559,24 @@ configuration option:: # pages, which will be placed at # output / TRANSLATIONS[lang] / destination / pagename.html # - # where "pagename" is specified in the metadata file. + # where "pagename" is the "slug" specified in the metadata file. # - # if use_in_feed is True, then those posts will be added to the site's - # rss feeds. + # The difference between POSTS and PAGES is that POSTS are added + # to feeds and are considered part of a blog, while PAGES are + # just independent HTML pages. # - post_pages = ( - ("posts/*.txt", "posts", "post.tmpl", True), - ("stories/*.txt", "stories", "story.tmpl", False), + + POSTS = ( + ("posts/*.txt", "posts", "post.tmpl"), + ("posts/*.rst", "posts", "post.tmpl"), + ) + PAGES = ( + ("stories/*.txt", "stories", "story.tmpl"), + ("stories/*.rst", "stories", "story.tmpl"), ) -It will use the first location that has the last parameter set to True, or the last -one in the list if all of them have it set to False. +It will use the first location that has the last item in ``POSTS``, or the last +one in ``PAGES`` if ``POSTS`` is empty. The ``new_post`` command supports some options:: @@ -511,7 +604,7 @@ index page or in RSS feeds, but to display instead only the beginning of them. If it's the case, you only need to add a "magical comment" in your post. -In restructuredtext:: +In reStructuredText:: .. TEASER_END @@ -530,12 +623,32 @@ change that text, you can use a custom teaser:: .. TEASER_END: click to read the rest of the article +Or you can completely customize the link using the ``READ_MORE_LINK`` option:: + + # A HTML fragment with the Read more... link. + # The following tags exist and are replaced for you: + # {link} A link to the full post page. + # {read_more} The string “Read more” in the current language. + # {{ A literal { (U+007B LEFT CURLY BRACKET) + # }} A literal } (U+007D RIGHT CURLY BRACKET) + # READ_MORE_LINK = '<p class="more"><a href="{link}">{read_more}…</a></p>' + + Drafts ~~~~~~ If you add a "draft" tag to a post, then it will not be shown in indexes and feeds. It *will* be compiled, and if you deploy it it *will* be made available, so use -with care. +with care. If you wish your drafts to be not available in your deployed site, you +can set ``DEPLOY_DRAFTS = False`` in your configuration. + +Also if a post has a date in the future, it will not be shown in indexes until +you rebuild after that date. This behaviour can be disabled by setting +``FUTURE_IS_NOW = True`` in your configuration, which will make future posts be +published immediately. Posts dated in the future are *not* deployed by default +(when ``FUTURE_IS_NOW = False``). To make future posts available in the +deployed site, you can set ``DEPLOY_FUTURE = True`` in your configuration. +Generally, you want FUTURE_IS_NOW and DEPLOY_FUTURE to be the same value. Retired Posts ~~~~~~~~~~~~~ @@ -544,6 +657,57 @@ If you add a "retired" tag to a post, then it will not be shown in indexes and f It *will* be compiled, and if you deploy it it *will* be made available, so it will not generate 404s for people who had linked to it. +Queuing Posts +~~~~~~~~~~~~~ + +Some blogs tend to have new posts based on a schedule (for example, +every Mon, Wed, Fri) but the blog authors don't like to manually +schedule their posts. You can schedule your blog posts based on a +rule, by specifying a rule in the ``SCHEDULE_RULE`` in your +configuration. You can either post specific blog posts according to +this schedule by using the ``--schedule`` flag on the ``new_post`` +command or post all new posts according to this schedule by setting +``SCHEDULE_ALL = True`` in your configuration. (Note: This feature +requires that the ``FUTURE_IS_NOW`` setting is set to ``False``) + +For example, if you would like to schedule your posts to be on every +Monday, Wednesday and Friday at 7am, add the following +``SCHEDULE_RULE`` to your configuration :: + + SCHEDULE_RULE = 'RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR;BYHOUR=7;BYMINUTE=0;BYSECOND=0' + +For more details on how to specify a recurrence rule, look at the +`iCal specification <http://www.kanzaki.com/docs/ical/rrule.html>`_. + +Say, you get a free Sunday, and want to write a flurry of new posts, +or at least posts for the rest of the week, you would run the +``new_post`` command with the ``--schedule`` flag, as many times as +you want:: + + $ nikola new_post --schedule + # Creates a new post to be posted on Monday, 7am. + $ nikola new_post -s + # Creates a new post to be posted on Wednesday, 7am. + $ nikola new_post -s + # Creates a new post to be posted on Friday, 7am. + . + . + . + +All these posts get queued up according to your schedule, but note +that you will anyway need to build and deploy your site for the posts +to appear online. You can have a cron job that does this regularly. + +An additional setting (``SCHEDULE_FORCE_TODAY = True``) lets you tell +Nikola to make the post today, if you run the ``new_post --schedule`` +after the scheduled hour has passed, and there is no other post +at/after the scheduled hour. Concretely, say, you run the ``nikola +new_post -s`` command at 10am on a Monday (with the schedule rule set +to the same as above), with no other post on Monday, at/after 7am, +setting ``SCHEDULE_FORCE_TODAY = True`` will have your post scheduled +to Monday, instead of being scheduled to Wednesday 7am. + + Creating a Page --------------- @@ -554,10 +718,10 @@ Pages are the same as posts, except that: * They use the ``story.tmpl`` template instead of ``post.tmpl`` by default The default configuration expects the page's metadata and text files to be on the -``stories`` folder, but that can be changed (see post_pages option above). +``stories`` folder, but that can be changed (see ``PAGES`` option above). You can create the page's files manually or use the ``new_post`` command -with the ``-p`` option, qhich will place the files in the folder that +with the ``-p`` option, which will place the files in the folder that has ``use_in_feed`` set to False. Redirections @@ -587,15 +751,13 @@ what Nikola does. Its syntax is python, but if you don't know the language, it still should not be terribly hard to grasp. The default ``conf.py`` you get with Nikola should be fairly complete, and is quite -commented, but just in case, here is a full, -`customized example configuration <sampleconfig.html>`_ (the one I use for -`my site <http://lateral.netmanagers.com.ar>`_) +commented. You surely want to edit these options:: # Data about this site BLOG_TITLE = "Demo Site" - SITE_URL = "http://nikola.ralsina.com.ar" + SITE_URL = "http://getnikola.com" BLOG_EMAIL = "joe@demo.site" BLOG_DESCRIPTION = "This is a demo site for Nikola." @@ -611,18 +773,35 @@ CSS tweaking which is empty. Put your CSS there, for minimal disruption of the provided CSS files. If you feel tempted to touch other files in assets, you probably will be better off - with a `custom theme <theming.html>`_. + with a `custom theme <theming.html>`__. Template tweaking If you really want to change the pages radically, you will want to do a - `custom theme <theming.html>`_. + `custom theme <theming.html>`__. -Sidebar - ``LICENSE`` is a HTML snippet for things like a CC badge, or whatever you prefer. +Navigation Links + The 'NAVIGATION_LINKS' option lets you define what links go in a sidebar or menu + (depending on your theme) so you can link to important pages, or to other sites. + + The format is a language-indexed dictionary, where each element is a tuple of + tuples which are one of: + + 1. A (url, text) tuple, describing a link + 2. A ((url, text), (url, text), (url, text), title) tuple, describing a submenu / sublist. + + Example:: + + NAVIGATION_LINKS = { + DEFAULT_LANG: ( + ('/archive.html', 'Archives'), + ('/categories/index.html', 'Tags'), + ('/rss.xml', 'RSS'), + ((('/foo', 'FOO'), + ('/bar', 'BAR')), 'BAZ'), + ), + } - The 'sidebar_links' option lets you define what links go in the right-hand - sidebar, so you can link to important pages, or to other sites. The ``SEARCH_FORM`` option contains the HTML code for a search form based on duckduckgo.com which should always work, but feel free to change it to @@ -630,20 +809,24 @@ Sidebar Footer ``CONTENT_FOOTER`` is displayed, small at the bottom of all pages, I use it for - the copyright notice. + the copyright notice. The default shows a text formed using ``BLOG_AUTHOR``, + ``BLOG_EMAIL``, the date and ``LICENSE``. -Analytics - This is probably a misleading name, but the ``ANALYTICS`` option lets you define - a HTML snippet that will be added at the bottom of body. The main usage is - a Google analytics snippet or something similar, but you can really put anything - there. +BODY_END + This option lets you define a HTML snippet that will be added at the bottom of body. + The main usage is a Google analytics snippet or something similar, but you can really + put anything there. Good place for JavaScript. +SOCIAL_BUTTONS_CODE + The ``SOCIAL_BUTTONS_CODE`` option lets you define a HTML snippet that will be added + at the bottom of body. It defaults to a snippet for AddThis, but you can + really put anything there. See `social_buttons.html` for more details. Adding Files ------------ Any files you want to be in ``output/`` but are not generated by Nikola (for example, -``favicon.ico``, just put it in ``files/``. Everything there is copied into +``favicon.ico``) just put it in ``files/``. Everything there is copied into ``output`` by the ``copy_files`` task. Remember that you can't have files that collide with files Nikola generates (it will give an error). @@ -664,36 +847,41 @@ change the FILES_FOLDERS option:: Getting More Themes ------------------- -There are not so many themes for Nikola. On occasion, I port something I like, and make -it available for download. Nikola has a builtin theme download/install mechanism, its -``install_theme`` command:: +There are a few themes for Nikola. They are available at +the `Themes Index <http://themes.getnikola.com/>`_. +Nikola has a built-in theme download/install mechanism to install those themes — the ``install_theme`` command:: $ nikola install_theme -l Themes: ------- + base-jinja blogtxt - readable + ⋮ + ⋮ - $ nikola install_theme -n blogtxt - Downloading: http://nikola.ralsina.com.ar/themes/blogtxt.zip - Extracting: blogtxt into themes + $ nikola install_theme blogtxt + [2013-10-12T16:46:13Z] NOTICE: install_theme: Downloading: + http://themes.getnikola.com/v6/blogtxt.zip + [2013-10-12T16:46:15Z] NOTICE: install_theme: Extracting: blogtxt into themes -And there you are, you now have themes/blogtxt installed. It's very rudimentary, but it -should work in most cases. +And there you are, you now have themes/blogtxt installed. It's very +rudimentary, but it should work in most cases. -If you create a nice theme, please share it! You can post about it on -`the nikola forum <http://groups.google.com/group/nikola-discuss>`_ and I will -make it available for download. +If you create a nice theme, please share it! You can do it as a pull +request in the `GitHub repository <https://github.com/getnikola/nikola-themes>`__. One other option is to tweak an existing theme using a different color scheme, typography and CSS in general. Nikola provides a ``bootswatch_theme`` option to create a custom theme by downloading free CSS files from http://bootswatch.com:: - $ nikola bootswatch_theme -n custom_theme -s spruce -p site - Creating 'custom_theme' theme from 'spruce' and 'site' - Downloading: http://bootswatch.com/spruce/bootstrap.min.css - Downloading: http://bootswatch.com/spruce/bootstrap.css - Theme created. Change the THEME setting to "custom_theme" to use it. + $ nikola bootswatch_theme -n custom_theme -s spruce -p bootstrap3 + [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Creating 'custom_theme' theme + from 'spruce' and 'bootstrap3' + [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Downloading: + http://bootswatch.com//spruce/bootstrap.min.css + [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Downloading: + http://bootswatch.com//spruce/bootstrap.css + [2013-10-12T16:46:59Z] NOTICE: bootswatch_theme: Theme created. Change the THEME setting to "custom_theme" to use it. You can even try what different swatches do on an existing site using their handy `bootswatchlet <http://news.bootswatch.com/post/29555952123/a-bookmarklet-for-bootswatch>`_ @@ -714,26 +902,53 @@ Here is an example, from my own site's deployment script:: DEPLOY_COMMANDS = [ 'rsync -rav --delete output/* ralsina@lateral.netmanagers.com.ar:/srv/www/lateral', - 'rdiff-backup output ~/bartleblog-backup', + 'rdiff-backup output ~/blog-backup', "links -dump 'http://www.twingly.com/ping2?url=lateral.netmanagers.com.ar'", - 'rsync -rav ~/bartleblog-backup/* ralsina@netmanagers.com.ar:bartleblog-backup', ] Other interesting ideas are using `git as a deployment mechanism <http://toroid.org/ams/git-website-howto>`_ (or any other VCS -for that matter), using `lftp mirror <http://lftp.yar.ru/>`_ or unison, or dropbox, or +for that matter), using `lftp mirror <http://lftp.yar.ru/>`_ or unison, or Dropbox, or Ubuntu One. Any way you can think of to copy files from one place to another is good enough. -Comments --------- +Comments and Annotations +------------------------ While Nikola creates static sites, there is a minimum level of user interaction you are probably expecting: comments. -The default templates contain support for `Disqus <http://disqus.com>`_. All you have -to do is register a forum, put its short name in the ``DISQUS_FORUM`` option. +Nikola supports several third party comment systems: + +* `DISQUS <http://disqus.com>`_ +* `IntenseDebate <http://www.intensedebate.com/>`_ +* `LiveFyre <http://www.livefyre.com/>`_ +* `Moot <http://moot.it>`_ +* `Google+ <http://plus.google.com>`_ +* `Facebook <http://facebook.com>`_ + +By default it will use DISQUS, but you can change by setting ``COMMENT_SYSTEM`` +to one of "disqus", "intensedebate", "livefyre", "moot", "googleplus" or +"facebook" -Disqus is a good option because: +.. sidebar:: ``COMMENT_SYSTEM_ID`` + + The value of ``COMMENT_SYSTEM_ID`` depends on what comment system you + are using and you can see it in the system's admin interface. + + * For DISQUS it's called the **shortname** + * In IntenseDebate it's the **IntenseDebate site acct** + * In LiveFyre it's the **siteId** + * In Moot it's your **username** + * For Google Plus, ``COMMENT_SYSTEM_ID`` need not be set, but you must + `verify your authorship <https://plus.google.com/authorship>`_ + * For Facebook, you need to `create an app + <https://developers.facebook.com/apps>` (turn off sandbox mode!) + and get an **App ID** + +To use comments in a visible site, you should register with the service and +then set the ``COMMENT_SYSTEM_ID`` option. + +I recommend 3rd party comments, and specially DISQUS because: 1) It doesn't require any server-side software on your site 2) They offer you a way to export your comments, so you can take @@ -745,12 +960,44 @@ You can disable comments for a post by adding a "nocomments" metadata field to i .. nocomments: True -.. admonition:: Important +.. admonition:: DISQUS Support In some cases, when you run the test site, you won't see the comments. That can be fixed by adding the disqus_developer flag to the templates but it's probably more trouble than it's worth. +.. admonition:: Moot Support + + Moot doesn't support comment counts on index pages, and it requires adding + this to your ``conf.py``: + + .. code-block:: python + + BODY_END = """ + <script src="//cdn.moot.it/1/moot.min.js"></script> + """ + EXTRA_HEAD_DATA = """ + <link rel="stylesheet" type="text/css" href="//cdn.moot.it/1/moot.css"> + <meta name="viewport" content="width=device-width"> + <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> + """ + +.. admonition:: Facebook Support + + You need jQuery, but not because Facebook wants it (see Issue + #639). + +An alternative or complement to comments are annotations. Nikola integrates +the annotation service provided by `AnnotateIt. <annotateit.org>`_ +To use it, set the ``ANNOTATIONS`` option to True. This is specially useful +if you want feedback on specific parts of your writing. + +You can enable or disable annotations for specific posts or pages using the +``annotations`` and ``noannotations`` metadata. + +Annotations require JQuery and are therefore not supported in the base theme. +You can check bootstrap theme's ``base.html`` for details on how to handle them in +custom themes. Image Galleries --------------- @@ -773,9 +1020,12 @@ The ``conf.py`` options affecting gallery pages are these:: THUMBNAIL_SIZE = 180 MAX_IMAGE_SIZE = 1280 USE_FILENAME_AS_TITLE = True + GALLERY_SORT_BY_DATE = False + EXTRA_IMAGE_EXTENSIONS = [] If you add a file in ``galleries/gallery_name/index.txt`` its contents will be -converted to HTML and inserted above the images in the gallery page. +converted to HTML and inserted above the images in the gallery page. The +format is the same as for posts. If you add some image filenames in ``galleries/gallery_name/exclude.meta``, they will be excluded in the gallery page. @@ -809,12 +1059,55 @@ replace that with strings describing command lines, or arbitrary python function If there's any specific thing you expect to be generally useful as a filter, contact me and I will add it to the filters library so that more people use it. +The currently available filters are: + +.. sidebar:: Creating your own filters + + You can use any program name that works in place as a filter, like ``sed -i`` + and you can use arbitrary python functions as filters, too. + + If your program doesn't run in-place, then you can use Nikola's runinplace function. + For example, this is how the yui_compressor filter is implemented: + + .. code-block:: python + + def yui_compressor(infile): + return runinplace(r'yui-compressor --nomunge %1 -o %2', infile) + + You can turn any function into a filter using ``apply_to_file``. + As a silly example, this would make everything uppercase and totally break + your website: + + .. code-block:: python + + import string + from nikola.filters import apply_to_file + FILTERS = { + ".html": [apply_to_file(string.upper)] + } + +yui_compressor + Compress files using `YUI compressor <http://yui.github.io/yuicompressor/>`_ + +optipng + Compress PNG files using `optipng <http://optipng.sourceforge.net/>`_ + +jpegoptim + Compress JPEG files using `jpegoptim <http://www.kokkonen.net/tjko/projects.html>`_ + +tidy + Apply `tidy <http://tidy.sourceforge.net/>`_ to HTML files + +typogrify + Improve typography using `typogrify <https://github.com/mintchaos/typogrify>`_ + + Optimizing Your Website ----------------------- One of the main goals of Nikola is to make your site fast and light. So here are a few tips we have found when setting up Nikola with Apache. If you have more, or -different ones, or about other webservers, please share! +different ones, or about other web servers, please share! #. Use a speed testing tool. I used Yahoo's YSlow but you can use any of them, and it's probably a good idea to use more than one. @@ -833,21 +1126,33 @@ different ones, or about other webservers, please share! #. The webassets Nikola plugin can drastically decrease the number of CSS and JS files your site fetches. #. Through the filters feature, you can run your files through arbitrary commands, so that images - are recompressed, Javascript is minimized, etc. + are recompressed, JavaScript is minimized, etc. -#. The USE_CDN option offloads standard Javascript and CSS files to a CDN so they are not +#. The USE_CDN option offloads standard JavaScript and CSS files to a CDN so they are not downloaded from your server. -Restructured Text Extensions ----------------------------- +reStructuredText Extensions +--------------------------- -Nikola includes support for a few directives that are not part of docutils, but which +Nikola includes support for a few directives and roles that are not part of docutils, but which we think are handy for website development. -Youtube +Media +~~~~~ + +This directive lets you embed media from a variety of sites automatically by just passing the +URL of the page. For example here are two random videos:: + + .. media:: http://vimeo.com/72425090 + + .. youtube:: http://www.youtube.com/watch?v=wyRpAat5oz0 + +It supports Instagram, Flickr, Github gists, Funny or Die, and dozens more, thanks to `Micawber <https://github.com/coleifer/micawber>`_ + +YouTube ~~~~~~~ -To link to a youtube video, you need the id of the video. For example, if the +To link to a YouTube video, you need the id of the video. For example, if the URL of the video is http://www.youtube.com/watch?v=8N_tupPBtWQ what you need is **8N_tupPBtWQ** @@ -858,15 +1163,14 @@ Once you have that, all you need to do is:: Vimeo ~~~~~ -To link to a vimeo video, you need the id of the video. For example, if the +To link to a Vimeo video, you need the id of the video. For example, if the URL of the video is http://www.vimeo.com/20241459 then the id is **20241459** Once you have that, all you need to do is:: .. vimeo:: 20241459 -If you are running python 2.6 or later, or have the json module installed and -have internet connectivity when generating your site, the height and width of +If you have internet connectivity when generating your site, the height and width of the embedded player will be set to the native height and width of the video. You can override this if you wish:: @@ -879,7 +1183,7 @@ Soundcloud This directive lets you share music from http://soundcloud.com You first need to get the ID for the piece, which you can find in the "share" link. For example, if the -Wordpress code starts like this:: +WordPress code starts like this:: [soundcloud url="http://api.soundcloud.com/tracks/78131362" @@ -894,7 +1198,7 @@ The ``code`` directive has been included in docutils since version 0.9 and now replaces Nikola's ``code-block`` directive. To ease the transition, two aliases for ``code`` directive are provided: ``code-block`` and ``sourcecode``:: - .. code:: python + .. code-block:: python :number-lines: print("Our virtues and our failings are inseparable") @@ -936,7 +1240,7 @@ Producing this: .. gist:: 2395294 -This degrades gracefully if the browser doesn't support javascript. +This degrades gracefully if the browser doesn't support JavaScript. Slideshows ~~~~~~~~~~ @@ -951,17 +1255,65 @@ To create an image slideshow, you can use the ``slides`` directive. For example: /galleries/demo/tesla_lightning1_lg.jpg /galleries/demo/tesla_tower1_lg.jpg +Chart +~~~~~ + +This directive is a thin wrapper around `Pygal <http://pygal.org/>`_ and will produce charts +as SVG files embedded directly in your pages. + +Here's an example of how it works:: + + .. chart:: Bar + :title: 'Browser usage evolution (in %)' + :x_labels: ["2002", "2003", "2004", "2005", "2006", "2007"] + + 'Firefox', [None, None, 0, 16.6, 25, 31] + 'Chrome', [None, None, None, None, None, None] + 'IE', [85.8, 84.6, 84.7, 74.5, 66, 58.6] + 'Others', [14.2, 15.4, 15.3, 8.9, 9, 10.4] + +The argument passed next to the directive (Bar in that example) is the type of chart, and can be one of +Line, StackedLine, Bar, StackedBar, HorizontalBar, XY, DateY, Pie, Radar, Dot, Funnel, Gauge, Pyramid. For +examples of what each kind of graph is, `check here <http://pygal.org/chart_types/>`_ -Importing Your Wordpress Site Into Nikola +It can take *a lot* of options to let you customize the charts (in the example, title and x_labels). +You can use any option described in `the pygal docs <http://pygal.org/basic_customizations/>`_ + +Finally, the content of the directive is the actual data, in the form of a label and +a list of values, one series per line. + +Doc +~~~ + +This role is useful to make links to other post or page inside the same site. + +Here's an example:: + + Take a look at :doc:`my other post <creating-a-theme>` about theme creating. + +In this case we are giving the portion of text we want to link. So, the result will be: + + Take a look at :doc:`my other post <creating-a-theme>` about theme creating. + +If we want to use the post's title as the link's text, just do:: + + Take a look at :doc:`creating-a-theme` to know how to do it. + +and it will produce: + + Take a look at :doc:`creating-a-theme` to know how to do it. + + +Importing Your WordPress Site Into Nikola ----------------------------------------- -If you like Nikola, and want to start using it, but you have a Wordpress blog, Nikola +If you like Nikola, and want to start using it, but you have a WordPress blog, Nikola supports importing it. Here's the steps to do it: 1) Get a XML dump of your site [#]_ -2) nikola import_wordpress -f mysite.wordpress.2012-12-20.xml +2) nikola import_wordpress mysite.wordpress.2012-12-20.xml -After some time, this will crate a ``new_site`` folder with all your data. It currently supports +After some time, this will create a ``new_site`` folder with all your data. It currently supports the following: * All your posts and pages @@ -971,11 +1323,11 @@ the following: * Will try to add redirects that send the old post URLs to the new ones * Will give you a url_map so you know where each old post was - This is also useful for Disqus thread migration! + This is also useful for DISQUS thread migration! * Will try to convert the content of your posts. This is *not* error free, because - wordpress uses some unholy mix of HTML and strange things. Currently we are treating it - as markdown, which does a reasonabe job of it. + WordPress uses some unholy mix of HTML and strange things. Currently we are treating it + as markdown, which does a reasonable job of it. You will find your old posts in ``new_site/posts/post-title.wp`` in case you need to fix any of them. @@ -987,7 +1339,7 @@ about it. .. [#] The dump needs to be in 1.2 format. You can check by reading it, it should say ``xmlns:excerpt="http://wordpress.org/export/1.2/excerpt/"`` near the top of the file. If it says ``1.1`` instead of ``1.2`` you will have to update your - wordpress before dumping. + WordPress before dumping. Other versions may or may not work. @@ -997,7 +1349,7 @@ Importing To A Custom Location Or Into An Existing Site It is possible to either import into a location you desire or into an already existing Nikola site. To do so you can specify a location after the dump.:: - $ nikola import_wordpress -f mysite.wordpress.2012-12-20.xml -o import_location + $ nikola import_wordpress mysite.wordpress.2012-12-20.xml -o import_location With this command Nikola will import into the folder ``import_location``. @@ -1075,14 +1427,13 @@ when they try to open a post. Local Search ~~~~~~~~~~~~ -If you don't want to depend on google or duckduckgo to implement search for you, -or just want it to wok even if you are offline, enable this plugin and the +If you don't want to depend on Google or DuckDuckGo to implement search for you, +or just want it to work even if you are offline, enable this plugin and the search will be performed client side. This plugin implements a Tipue-based local search for your site. -To use it, copy task_localsearch.plugin and task_localsearch -into a plugins/ folder in your nikola site. +To use it, enable local_search in ENABLED_EXTRAS in your sites conf.py After you build your site, you will have several new files in assets/css and assets/js and a tipue_search.html that you can use as a basis for using this in your site. @@ -1092,14 +1443,14 @@ docs at http://www.tipue.com/search/ Tipue is under an MIT license (see MIT-LICENSE.txt) -Here's a set of example settings for conf.py that should work nicely with the "site" theme:: +Here's a set of example settings for conf.py that should work nicely with the "bootstrap" theme:: SEARCH_FORM = """ <span class="navbar-form pull-left"> <input type="text" id="tipue_search_input"> </span>""" - ANALYTICS = """ + BODY_END = """ <script type="text/javascript" src="/assets/js/tipuesearch_set.js"></script> <script type="text/javascript" src="/assets/js/tipuesearch.js"></script> <script type="text/javascript"> @@ -1118,6 +1469,9 @@ Here's a set of example settings for conf.py that should work nicely with the "s <div id="tipue_search_content" style="margin-left: auto; margin-right: auto; padding: 20px;"></div> """ + ENABLED_EXTRAS = [ 'local_search' ] + + The <div> in EXTRA_HEAD_DATA is a hack but it will migrate into the <body> of the documents thanks to magic, and will hold the search results after the user searches. @@ -1128,11 +1482,52 @@ This task gives you a ``mustache.html`` file which lets you access your whole blog without reloading the page, using client-side templates. Makes it much faster and modern ;-) +Custom Plugins +-------------- + +You can create your own plugins (see :doc:`extending`) and use them in your own +site by putting them in a ``plugins/`` folder. + + +Getting Extra Plugins +--------------------- + +If you want extra plugins, there is also the `Plugins Index <http://plugins.getnikola.com/>`_. + +Similarly to themes, there is a nice, built-in command to install them — +``install_plugin``: + + $ nikola install_plugin -l + Plugins: + -------- + helloworld + tags + ⋮ + ⋮ + + $ nikola install_plugin helloworld + [2013-10-12T16:51:56Z] NOTICE: install_plugin: Downloading: http://plugins.getnikola.com/v6/helloworld.zip + [2013-10-12T16:51:58Z] NOTICE: install_plugin: Extracting: helloworld into plugins + plugins/helloworld/requirements.txt + [2013-10-12T16:51:58Z] NOTICE: install_plugin: This plugin has Python dependencies. + [2013-10-12T16:51:58Z] NOTICE: install_plugin: Installing dependencies with pip... + ⋮ + ⋮ + [2013-10-12T16:51:59Z] NOTICE: install_plugin: Dependency installation succeeded. + [2013-10-12T16:51:59Z] NOTICE: install_plugin: This plugin has a sample config file. + Contents of the conf.py.sample file: + + # Should the Hello World plugin say “BYE” instead? + BYE_WORLD = False + + +You can also share plugins you created with the community! Visit the +`GitHub repository <https://github.com/getnikola/plugins>`__ to find out more. License ------- -Nikola is released under a `MIT license <https://github.com/ralsina/nikola/blob/master/LICENSE.txt>`_ which +Nikola is released under a `MIT license <https://github.com/getnikola/nikola/blob/master/LICENSE.txt>`_ which is a free software license. Some components shipped along with Nikola, or required by it are released under other licenses. |