diff options
Diffstat (limited to 'docs/manual.txt')
| -rw-r--r-- | docs/manual.txt | 151 |
1 files changed, 132 insertions, 19 deletions
diff --git a/docs/manual.txt b/docs/manual.txt index c186260..d78b4f6 100644 --- a/docs/manual.txt +++ b/docs/manual.txt @@ -8,7 +8,7 @@ The Nikola Handbook =================== -:Version: 6.2.1 +:Version: 6.3.0 .. class:: alert alert-info pull-right @@ -89,11 +89,16 @@ out there. Getting Help ------------ -* Feel free to contact me at ralsina@netmanagers.com.ar for questions about Nikola. +.. class:: lead + +`Get help here! <http://getnikola.com/contact.html>`_ + +TL;DR: + * 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://getnikola.com/blog>`_ -* You can follow `Nikola on Twitter <https://twitter.com/nikolagenerator>`_ +* You can follow `Nikola on Twitter <https://twitter.com/GetNikola>`_ Why Static? ----------- @@ -198,6 +203,16 @@ of how to "get" something for your specific operating system are left to you. The short version is: ``pip install nikola`` +If you are running Arch Linux, there are AUR packages, available in Python 2/3 +and stable/git master flavors: `python-nikola`__ / `python2-nikola`__ for the +latest stable release or `python-nikola-git`__ / `python2-nikola-git`__ for the +GitHub master. (only one package may be installed at the same time.) + +__ https://aur.archlinux.org/packages/python-nikola/ +__ https://aur.archlinux.org/packages/python2-nikola/ +__ https://aur.archlinux.org/packages/python-nikola-git/ +__ https://aur.archlinux.org/packages/python2-nikola-git/ + 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 @@ -205,7 +220,10 @@ install something else. For example, if it tells you you need ``requests``:: pip install requests -And so on. +And so on. Alternatively, you can install the ``requirements-full.txt`` file +shipped with the full source tree to get everything. (or `see the file +online +<https://github.com/getnikola/nikola/blob/master/requirements-full.txt>`_) Longer version: @@ -229,6 +247,9 @@ Longer version: #. Get `yapsy <http://yapsy.sourceforge.net>`_ #. Get `PyRSS2Gen <http://www.dalkescientific.com/Python/PyRSS2Gen.html>`_ #. Get `pytz <http://pytz.sourceforge.net/>`_ + #. Get `Logbook <http://pythonhosted.org/Logbook/>`_ + #. Get `blinker <http://pythonhosted.org/blinker/>`_ + #. Get `Setuptools <http://pythonhosted.org/setuptools/>`_ #. If using Python 2, get `configparser <http://pypi.python.org/pypi/configparser/3.2.0r3>`_ #. run ``python setup.py install`` @@ -238,7 +259,10 @@ After that, run ``nikola init --demo sitename`` and that will create a folder ca 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/libxslt errors +~~~~~~~~~~~~~~~~~~~~~ + +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:: @@ -246,9 +270,27 @@ Debian systems:: sudo apt-get install libxml2-dev sudo apt-get install libxslt1-dev -Red Hat/RPM based systems:: +Red Hat/RPM-based systems:: + + sudo yum install libxslt-devel libxml2-devel + +Python.h not found +~~~~~~~~~~~~~~~~~~ - yum install libxslt-devel libxml2-devel +If you get an error to the effect of ``Python.h not found``, you need to +install development packages for Python. + +Debian systems:: + + sudo apt-get install python-dev + +Red Hat/RPM-based systems:: + + sudo yum install python-devel + +Note that many other distros/operating systems (including Arch Linux, +\*BSD and OS X) do not require such packages, as C headers are included +with the base distribution of Python. Installation on Linux, Mac OS X, \*BSD, and any other POSIX-compatible OS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -274,7 +316,8 @@ their `PyPI <https://pypi.python.org/>`_ pages to find official packages, `the u 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 + * the concept of HDD partitions and letters (instead of + seamless mounting under one root) * 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``) @@ -442,6 +485,7 @@ The content of that file is as follows:: .. tags: .. link: .. description: + .. type: text Write your post here. @@ -451,6 +495,9 @@ The third line is the post's date, and is set to "now". The other lines are optional. Tags are comma-separated. The ``link`` is an original source for the content, and ``description`` is mostly useful for SEO. +``type`` is the post type, whatever you set here (prepended with ``post-``) +will become a class of the `<article>` element for this post. Defaults to +``text`` (resulting in a ``post-text`` class) You can add your own metadata fields in the same manner, if you use a theme that supports them (for example: ``.. author: John Doe``) @@ -458,7 +505,7 @@ 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 :: +to your configuration:: ADDITIONAL_METADATA = { 'author': 'John Doe' @@ -500,11 +547,11 @@ to your configuration :: 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 Nikola originally used a separate ``.meta`` file. That will still work! - The format of the meta files is the same as shown above, but without the + The format of the meta files is the same as shown above (i.e. only + the 7 base fields, in the order listed above), but without the explanations:: How to make money @@ -512,27 +559,64 @@ to your configuration :: 2012/09/15 19:52:05 If you are writing a multilingual site, you can also create a per-language -post file (for example: ``how-to-make-money.txt.es``). This one can replace -metadata of the default language, for example: +post file (for example: ``how-to-make-money.txt.es`` with the default TRANSLATIONS_PATTERN, see below). +This one can replace metadata of the default language, for example: * The translated title for the post or page * A translated version of the page name +The pattern used for finding translations is controlled by the +TRANSLATIONS_PATTERN variable in your configuration file. + +The default as in the example above is to append the language code to the +filename path to identify a translation of a file, so the German translation +of ``some_file.rst`` should be named ``some_file.rst.de``. This is because +the TRANSLATIONS_PATTERN variable is by default set to:: + + TRANSLATIONS_PATTERN = "{path}.{ext}.{lang}" + +However, if you don't want your Polish input files to be considered +Perl code (e.g. ``some_file.rst.pl``), you could use this pattern:: + + TRANSLATIONS_PATTERN = "{path}.{lang}.{ext}" + +Note that this pattern will become the default in v7.0.0. + +.. note:: Considered languages + + nikola will only look for translation of input files for languages + specified in the TRANSLATIONS variable. + 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`_ Currently supported languages are +* Basque +* Bulgarian * Catalan +* Chinese (Simplified) +* Croatian +* Czech +* Dutch * English +* Esperanto +* Estonian +* Finnish * French * German * Greek * Italian +* Japanese +* Norwegian Bokmål +* Persian * Polish +* Portuguese * Russian -* Simplified Chinese. +* Slovenian * Spanish +* Turkish +* Urdu If you wish to add support for more languages, check out the instructions at the `theming guide <http://getnikola.com/theming.html>`_. @@ -549,9 +633,11 @@ and ``PAGES`` configuration options:: # (whatever/thing.txt). # # That fragment could have an associated metadata file (whatever/thing.meta), - # and optionally translated files (example for spanish, with code "es"): + # and optionally translated files (example for Spanish, with code "es"): # whatever/thing.txt.es and whatever/thing.meta.es # + # This assumes you use the default TRANSLATIONS_PATTERN. + # # From those files, a set of HTML fragment files will be generated: # cache/whatever/thing.html (and maybe cache/whatever/thing.html.es) # @@ -707,6 +793,21 @@ 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. +Post Types +~~~~~~~~~~ + +Nikola supports specifying post types, just like Tumblr does. Post +types affect the look of your posts, by adding a ``post-YOURINPUTHERE`` +class to the post. Each post can have one and exactly one type. Nikola +styles the following types in the default themes: + ++-----------------+----------------------------+------------------+ +| Name(s) | Description | Styling | ++=================+============================+==================+ +| text | plain text — default value | standard | ++-----------------+----------------------------+------------------+ +| micro | “small” (short) posts | big serif font | ++-----------------+----------------------------+------------------+ Creating a Page --------------- @@ -901,7 +1002,7 @@ One caveat is that if any command has a % in it, you should double them. 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', + 'rsync -rav --delete output/ ralsina@lateral.netmanagers.com.ar:/srv/www/lateral', 'rdiff-backup output ~/blog-backup', "links -dump 'http://www.twingly.com/ping2?url=lateral.netmanagers.com.ar'", ] @@ -924,7 +1025,8 @@ Nikola supports several third party comment systems: * `LiveFyre <http://www.livefyre.com/>`_ * `Moot <http://moot.it>`_ * `Google+ <http://plus.google.com>`_ -* `Facebook <http://facebook.com>`_ +* `Facebook <http://facebook.com/>`_ +* `isso <http://posativ.org/isso/>`_ By default it will use DISQUS, but you can change by setting ``COMMENT_SYSTEM`` to one of "disqus", "intensedebate", "livefyre", "moot", "googleplus" or @@ -944,6 +1046,8 @@ to one of "disqus", "intensedebate", "livefyre", "moot", "googleplus" or * For Facebook, you need to `create an app <https://developers.facebook.com/apps>` (turn off sandbox mode!) and get an **App ID** + * For isso, it is the URL of isso (must be world-accessible and **have a trailing slash**, + default ``http://localhost:8080/``) To use comments in a visible site, you should register with the service and then set the ``COMMENT_SYSTEM_ID`` option. @@ -1191,6 +1295,10 @@ The ID is 78131362 and you can embed the audio with this:: .. soundcloud:: 78131362 +You can also embed playlists, via the `soundcloud_playlist` directive which works the same way. + + .. soundcloud_playlist:: 9411706 + Code ~~~~ @@ -1486,7 +1594,8 @@ 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. +site by putting them in a ``plugins/`` folder. You can also put them in +directories listed in the ``EXTRA_PLUGINS_DIRS`` configuration variable. Getting Extra Plugins @@ -1495,7 +1604,7 @@ 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``: +``install_plugin``:: $ nikola install_plugin -l Plugins: @@ -1524,6 +1633,10 @@ Similarly to themes, there is a nice, built-in command to install them — You can also share plugins you created with the community! Visit the `GitHub repository <https://github.com/getnikola/plugins>`__ to find out more. +You can use the plugins in this repository without installing them into your +site, by cloning the repository and adding the path of the plugins directory to +the ``EXTRA_PLUGINS_DIRS`` list in your configuration. + License ------- |