diff options
Diffstat (limited to 'docs/manual.txt')
| -rw-r--r-- | docs/manual.txt | 709 |
1 files changed, 554 insertions, 155 deletions
diff --git a/docs/manual.txt b/docs/manual.txt index 3917dbc..d287099 100644 --- a/docs/manual.txt +++ b/docs/manual.txt @@ -1,14 +1,13 @@ .. title: The Nikola Handbook .. slug: handbook .. date: 2012-03-30 23:00:00 UTC-03:00 -.. tags: mathjax .. link: .. description: The Nikola Handbook =================== -:Version: 7.1.0 +:Version: 7.6.0 .. class:: alert alert-info pull-right @@ -20,7 +19,7 @@ All You Need to Know After you have Nikola `installed <#installing-nikola>`_: -Create a empty site (with a setup wizard): +Create an empty site (with a setup wizard): ``nikola init mysite`` You can create a site with demo files in it with ``nikola init --demo mysite`` @@ -32,15 +31,14 @@ Create a post: Edit the post: The filename should be in the output of the previous command. + You can also use ``nikola new_post -e`` to open an editor automatically. Build the site: ``nikola build`` -Start the test server: - ``nikola serve`` +Start the test server and open a browser (http://127.0.0.1:8000/): + ``nikola serve -b`` -See the site: - http://127.0.0.1:8000 That should get you going. If you want to know more, this manual will always be here for you. @@ -58,7 +56,7 @@ that it takes some texts you wrote, and uses them to create a folder full of HTML files. If you upload that folder to a server, you will have a rather full-featured website, done with little effort. -It's original goal is to create blogs, but it supports most kind of sites, and +Its original goal is to create blogs, but it supports most kind of sites, and can be used as a CMS, as long as what you present to the user is your own content instead of something the user generates. @@ -67,7 +65,7 @@ Nikola can do: * A blog (`example <http://ralsina.me>`__) * Your company's site * Your personal site -* A software project's site (`example <http://getnikola.com>`__) +* A software project's site (`example <https://getnikola.com>`__) * A book's site Since Nikola-based sites don't run any code on the server, there is no way to process @@ -91,13 +89,13 @@ Getting Help .. class:: lead -`Get help here! <http://getnikola.com/contact.html>`_ +`Get help here! <https://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 subscribe to `the Nikola Blog <https://getnikola.com/blog>`_ * You can follow `Nikola on Twitter <https://twitter.com/GetNikola>`_ Why Static? @@ -136,7 +134,7 @@ Obsolescense You may say those are long term issues, or that they won't matter for years. Well, I believe things should work forever, or as close to it as we can make them. Nikola's static output and its input files will work as long as you can install - a Python > 2.6 in a Linux, Windows, or Mac and can find a server + a Python 2.7/3.3 or newer under Linux, Windows, or OS X and can find a server that sends files over HTTP. That's probably 10 or 15 years at least. Also, static sites are easily handled by the Internet Archive. @@ -180,7 +178,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 <http://getnikola.com/quickstart.html>`__ or +* The input format is light markup (`reStructuredText <https://getnikola.com/quickstart.html>`__ or `Markdown <http://daringfireball.net/projects/markdown/>`_) * Easy-to-create image galleries * Support for displaying source code @@ -205,7 +203,7 @@ The short version is:: pip install nikola -Note that you need Python v2.6 or newer OR v3.3 or newer. +Note that you need Python v2.7 or newer OR v3.3 or newer. Some features require **extra dependencies**. You can install them all in bulk by doing:: @@ -219,31 +217,41 @@ After that, run ``nikola init --demo sitename`` and that will run the setup wizard, which will create a folder called ``sitename`` containing a functional demo site. -Nikola is packaged for some Linux distributions, you may get that instead. e.g. -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.) +Linux packages +~~~~~~~~~~~~~~ + +Nikola is packaged for some Linux distributions, you may get that instead of +installing via ``pip``. Keep in mind that those packages might be +**outdated** and that we don’t support versions that are too old. Proceed with +care! + +* Arch Linux (AUR): `python-nikola`__ / `python2-nikola`__ for the + latest stable release or `python-nikola-git`__ / `python2-nikola-git`__ for the + GitHub master. (official Nikola-supported packages) +* Fedora: `python-nikola`__ (incl. python3-nikola) +* Debian and derivatives: `nikola`__ +* Gentoo: `www-apps/nikola`__ __ 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/ +__ https://admin.fedoraproject.org/pkgdb/package/python-nikola/ +__ https://packages.debian.org/sid/nikola +__ https://packages.gentoo.org/package/www-apps/nikola -libxml/libxslt errors -~~~~~~~~~~~~~~~~~~~~~ +libxml/libxslt (files missing) 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: +If you get errors about various files missing while compiling ``lxml``, you must install headers for the ``libxml``, ``libxslt`` and ``zlib`` libraries, like so: Debian systems:: - sudo apt-get install libxml2-dev - sudo apt-get install libxslt1-dev + sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev Red Hat/RPM-based systems:: - sudo yum install libxslt-devel libxml2-devel + sudo yum install libxslt-devel libxml2-devel zlib-devel Python.h not found ~~~~~~~~~~~~~~~~~~ @@ -263,18 +271,6 @@ 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -(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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -289,7 +285,7 @@ caveats: pre-built packages is possible through ``virtualenv --system-site-packages``. #. 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: + hesitate to report them. Some of the differences include: * ``\`` as path separator (instead of ``/``) * the concept of HDD partitions and letters (instead of @@ -307,9 +303,10 @@ 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 reStructuredText and Markdown, but there is also support -for textile and WikiCreole and even for just writing HTML. +for Textile and WikiCreole and even for just writing HTML. For more details, +read `Configuring other input formats`_. -.. note:: There is a great `quick tutorial to learn reStructuredText. <http://getnikola.com/quickstart.html>`__ +.. note:: There is a great `quick tutorial to learn reStructuredText. <https://getnikola.com/quickstart.html>`__ First, let's see how you "build" your site. Nikola comes with a minimal site to get you started. @@ -373,7 +370,7 @@ and even individual files like ``nikola build output/index.html`` Nikola also has other commands besides ``build``:: $ nikola help - Nikola is a tool to create static websites and blogs. For full documentation and more information, please visit http://getnikola.com/ + Nikola is a tool to create static websites and blogs. For full documentation and more information, please visit https://getnikola.com/ Available commands: @@ -400,7 +397,7 @@ Nikola also has other commands besides ``build``:: nikola plugin manage plugins nikola serve start the test webserver nikola strace use strace to list file_deps and targets - nikola tabcompletion generate script for tab-complention + nikola tabcompletion generate script for tab-completion nikola version print the Nikola version number nikola help show help / reference @@ -440,7 +437,8 @@ but you can use a lot of different markups using the ``-f`` option. Currently Nikola supports reStructuredText, Markdown, IPython Notebooks, HTML as input, can also use Pandoc for conversion, and has support for BBCode, CreoleWiki, txt2tags, Textile -and more via `plugins <http://plugins.getnikola.com>`__. +and more via `plugins <https://plugins.getnikola.com>`__. +For more details, read `Configuring other input formats`_. 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 @@ -493,11 +491,47 @@ to your configuration:: Nikola will also use other metadata fields: + author + Author of the post, will be used in the RSS feed and possibly in the post + display (theme-dependent) + + annotations / noannotations + Override the value of the ``ANNOTATIONS`` option for this specific post or page. + + category + Like tags, except each post can have only one, and they usually have + more descriptive names. + + filters + See the `Post Processing Filters`_ section. + + hidetitle + Set "True" if you do not want to see the **page** title as a + heading of the output html file (does not work for posts). + nocomments Set to "True" to disable comments. Example:: .. nocomments: True + password + The post will be encrypted and invisible until the reader enters the password. + Also, the post's sourcecode will not be available. + + WARNING: **DO NOT** use for real confidential data. The algorithm used (RC4) is insecure. The implementation may also be easily brute-forced. Please consider using something else if you need *real* encryption! + + More information: `Issue #1547 <https://github.com/getnikola/nikola/issues/1547>`_ + + previewimage + Designate a preview or other representative image path relative to BASE_URL + for use with Open Graph for posts. Adds the image when sharing on social + media and many other uses. + + .. previewimage: images/looks_great_on_facebook.png + + The image can be of any size and dimension (services will crop and adapt) + but should less than 1 MB and be larger than 300x300 (ideally 600x600). + template Will change the template used to render this page/post specific page. Example:: @@ -506,24 +540,8 @@ to your configuration:: 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). + enclosure + Add an enclosure to this post when it's used in RSS. See `more information about enclosures <http://en.wikipedia.org/wiki/RSS_enclosure>`__ .. note:: The Two-File Format @@ -603,7 +621,7 @@ Currently supported languages are: * Urdu If you wish to add support for more languages, check out the instructions -at the `theming guide <http://getnikola.com/theming.html>`_. +at the `theming guide <https://getnikola.com/theming.html>`_. The post page is generated using the ``post.tmpl`` template, which you can use to customize the output. @@ -625,7 +643,7 @@ and ``PAGES`` configuration options:: # From those files, a set of HTML fragment files will be generated: # cache/whatever/thing.html (and maybe cache/whatever/thing.html.es) # - # These files are combinated with the template to produce rendered + # These files are combined with the template to produce rendered # pages, which will be placed at # output / TRANSLATIONS[lang] / destination / pagename.html # @@ -647,7 +665,7 @@ and ``PAGES`` configuration options:: ``new_post`` will use the *first* path in ``POSTS`` (or ``PAGES`` if ``-p`` is supplied) that ends with the extension of your desired markup format (as -defined in ``COMPILERS`` in conf.py) as the directory that the new post will be +defined in ``COMPILERS`` in ``conf.py``) as the directory that the new post will be written into. If no such entry can be found, the post won’t be created. The ``new_post`` command supports some options:: @@ -680,7 +698,7 @@ In reStructuredText:: .. TEASER_END -In Markdown:: +In Markdown (or basically, the resulting HTML of any format):: <!-- TEASER_END --> @@ -712,10 +730,11 @@ 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. If you wish your drafts to be not available in your deployed site, you -can set ``DEPLOY_DRAFTS = False`` in your configuration. +can set ``DEPLOY_DRAFTS = False`` in your configuration. This will not work if +lazily include ``nikola build`` in your ``DEPLOY_COMMANDS``. 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 +you rebuild after that date. This behavior 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 @@ -786,6 +805,120 @@ styles the following types in the default themes: | micro | “small” (short) posts | big serif font | +-----------------+----------------------------+------------------+ +Configuring other input formats +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to use input formats other than reStructuredText, you need some extra +setup. + +1. Make sure you have the compiler for the input format you want. Some + input formats are supported out-of-the-box, but others must be installed from + the Plugins repository. You may also need some extra dependencies. You + will get helpful errors if you try to build when missing something. +2. You must ensure the compiler and your desired input file extension is included + in the ``COMPILERS`` dict and does not conflict with any other format. This + is extremely important for the pandoc compiler. +3. Finally, you must configure the ``POSTS`` and ``PAGES`` tuples. Follow the + instructions and the format set by pre-existing entries. Make sure to use + the same extension as is set in ``COMPILERS`` and configure the outputs + properly. + +Markdown +```````` + +To use Markdown in your posts/pages, make sure ``markdown`` is in your +``COMPILERS`` and that at least one of your desired extensions is defined in +``POSTS`` and ``PAGES``. + +You can use Python-Markdown extensions by setting the ``MARKDOWN_EXTENSIONS`` +config option: + +.. code:: python + + MARKDOWN_EXTENSIONS = ['fenced_code', 'codehilite', 'extra'] + +IPython Notebook/Jupyter +```````````````````````` + +To use Jupyter notebooks (previously known as IPython Notebooks) as posts/pages, +make sure ``ipynb`` is in your ``COMPILERS`` and that the ``.ipynb`` extension +is defined in ``POSTS`` and ``PAGES``. + +The ``-f`` argument to ``new_post`` should be used in the ``ipynb@KERNEL`` format. +It defaults to Python in the version used by Nikola if not specified. + +HTML +```` + +To use plain HTML in your posts/pages, make sure ``html`` is in your +``COMPILERS`` +and that the ``.html`` extension is defined in ``POSTS`` and ``PAGES``. + +PHP +``` + +There are two ways of using PHP within Nikola: + +1. To use PHP in your posts/pages (inside your site, with the theme and + everything), make sure ``php`` is in your ``COMPILERS`` and that the ``.php`` + extension is defined in ``POSTS`` and ``PAGES``. +2. To use PHP as standalone files (without any modifications), put them in + ``files/`` (or whatever ``FILES_FOLDERS`` is configured to). + +Pandoc +`````` + +To use Pandoc, you must uncomment the entry in ``COMPILERS`` and set the +extensions list to your desired extensions while also removing them from their +original compilers. The input format is inferred from the extension by Pandoc. + +Using Pandoc for reStructuredText, Markdown and other input formats that have a +standalone Nikola plugin is **not recommended** as it disables plugins and +extensions that are usually provided by Nikola. + +Indexes +~~~~~~~ + +All your posts that are not drafts, private or dated in the future, will be +shown in indexes. + +Settings +```````` + +Indexes are put in the ``INDEX_PATH`` directory, which defaults to an empty +string (site root). The “main” index is ``index.html``, and all the further +indexes are ``index-*.html``, respectively. + +By default, 10 posts are displayed on an index page. This can be changed with +``INDEX_DISPLAY_POST_COUNT``. Indexes can show full posts or just the teasers, +as controlled by the ``INDEX_TEASERS`` setting (defaults to ``False``). + +Titles of the pages can be controlled by using ``INDEXES_TITLES``, +``INDEXES_PAGES`` and ``INDEXES_PAGES_MAIN`` settings. + +Categories and tags use simple lists by default that show only titles and +dates; however, you can switch them to full indexes by using +``CATEGORY_PAGES_ARE_INDEXES`` and ``TAG_PAGES_ARE_INDEXES``, respectively. + +Static indexes +`````````````` + +Nikola uses *static indexes* by default. This means that ``index-1.html`` has +the oldest posts, and the newest posts past the first 10 are in +``index-N.html``, where ``N`` is the highest number. Only the page with the +highest number and the main page (``index-N.html`` and ``index.html``) are +rebuilt (the others remain unchanged). The page that appears when you click +*Older posts* on the index page, ``index-N.html``, might contain **less than 10 +posts** if there are not enough posts to fill up all pages. + +This can be disabled by setting ``INDEXES_STATIC`` to ``False``. In that mode, +``index-1.html`` contains all the newest posts past the first 10 and will +always contain 10 posts (unless you have less than 20). The last page, +``index-N.html``, contains the oldest posts, and might contain less than 10 +posts. This is how many blog engines and CMSes behave. Note that this will +lead to rebuilding all index pages, which might be a problem for larger blogs +(with a lot of index pages). + Creating a Page --------------- @@ -836,7 +969,7 @@ You surely want to edit these options:: # Data about this site BLOG_AUTHOR = "Your Name" # (translatable) BLOG_TITLE = "Demo Site" # (translatable) - SITE_URL = "http://getnikola.com/" + SITE_URL = "https://getnikola.com/" BLOG_EMAIL = "joe@demo.site" BLOG_DESCRIPTION = "This is a demo site for Nikola." # (translatable) @@ -846,6 +979,11 @@ them. For those options, two types of values can be provided: * a string, which will be used for all languages * a dict of language-value pairs, to have different values in each language +.. note:: It is possible to load the configuration from another file by specifying + ``--conf=path/to/other.file`` on Nikola's command line. For example, to + build your blog using the configuration file ``configurations/test.config``, + you have to execute ``nikola build --conf=configurations/test.config``. + Customizing Your Site --------------------- @@ -854,17 +992,17 @@ the easy ones! CSS tweaking Using the default configuration, you can create a ``assets/css/custom.css`` - file and then it will be loaded from the ``<head>`` blocks of your site - pages. Create it and put your CSS code there, for minimal disruption of the - provided CSS files. + file under ``files/`` or in your theme and then it will be loaded from the + ``<head>`` blocks of your site pages. Create it and put your CSS code 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>`__. If you want to use LESS_ or Sass_ for your custom CSS, or the theme you use contains LESS or Sass code that you want to override, you will need to install - the `LESS plugin <http://plugins.getnikola.com/#less>`__ or - `SASS plugin <http://plugins.getnikola.com/#sass>`__ create a ``less`` or + the `LESS plugin <https://plugins.getnikola.com/#less>`__ or + `SASS plugin <https://plugins.getnikola.com/#sass>`__ create a ``less`` or ``sass`` directory in your site root, put your ``.less`` or ``.scss`` files there and a targets file containing the list of files you want compiled. @@ -904,10 +1042,17 @@ Navigation Links submenus is supported. .. note:: + Some themes, including the default Bootstrap 3 theme, may present issues if the menu is too large. (in ``bootstrap3``, the navbar can grow too large and cover contents.) + .. note:: + + If you link to directories, make sure to follow ``STRIP_INDEXES``. If + it’s set to ``True``, end your links with a ``/``, otherwise end them + with ``/index.html`` — or else they won’t be hilighted when active. + 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 something else. @@ -929,6 +1074,60 @@ SOCIAL_BUTTONS_CODE 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. +Fancy Dates +----------- + +Nikola can use various styles for presenting dates. + +DATE_FORMAT + The date format to use if there is no JS or fancy dates are off. Compatible with Python’s ``strftime()`` syntax. + +JS_DATE_FORMAT + The date format to use if fancy dates are on. Compatible with ``moment.js`` syntax. + +DATE_FANCINESS = 0 + Fancy dates are off, and DATE_FORMAT is used. + +DATE_FANCINESS = 1 + Dates are recalculated in user’s timezone. Requires JavaScript. + +DATE_FANCINESS = 2 + Dates are recalculated as relative time (eg. 2 days ago). Requires JavaScript. + +In order to use fancy dates, your theme must support them. The built-in Bootstrap family supports it, but other themes might not by default. + +For Mako: + +.. code:: html + + <!-- required scripts -- best handled with bundles --> + <script src="/assets/js/moment-with-locales.min.js"></script> + <script src="/assets/js/fancydates.js"></script> + + <!-- fancy dates code --> + <script> + moment.locale("${momentjs_locales[lang]}"); + fancydates(${date_fanciness}, ${js_date_format}); + </script> + <!-- end fancy dates code --> + + +For Jinja2: + +.. code:: html + + <!-- required scripts -- best handled with bundles --> + <script src="/assets/js/moment-with-locales.min.js"></script> + <script src="/assets/js/fancydates.js"></script> + + <!-- fancy dates code --> + <script> + moment.locale("{{ momentjs_locales[lang] }}"); + fancydates({{ date_fanciness }}, {{ js_date_format }}); + </script> + <!-- end fancy dates code --> + + Adding Files ------------ @@ -955,7 +1154,7 @@ Getting More Themes ------------------- There are a few themes for Nikola. They are available at -the `Themes Index <http://themes.getnikola.com/>`_. +the `Themes Index <https://themes.getnikola.com/>`_. Nikola has a built-in theme download/install mechanism to install those themes — the ``install_theme`` command:: $ nikola install_theme -l @@ -968,7 +1167,7 @@ Nikola has a built-in theme download/install mechanism to install those themes $ nikola install_theme blogtxt [2013-10-12T16:46:13Z] NOTICE: install_theme: Downloading: - http://themes.getnikola.com/v6/blogtxt.zip + https://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 @@ -1003,27 +1202,32 @@ Nikola doesn't really have a concept of deployment. However, if you can specify deployment procedure as a series of commands, you can put them in the ``DEPLOY_COMMANDS`` option, and run them with ``nikola deploy``. +You can have multiple deployment presets. If you run ``nikola deploy``, the +``default`` preset is executed. You can also specify the names of presets +you want to run (eg. ``nikola deploy default``, multiple presets are allowed). + 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 = [ + DEPLOY_COMMANDS = {'default': [ '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'", - ] + ]} 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 -Ubuntu One. Any way you can think of to copy files from one place to another is good enough. +for that matter), using `lftp mirror <http://lftp.yar.ru/>`_ or unison, or Dropbox. +Any way you can think of to copy files from one place to another is good enough. Deploying to GitHub ~~~~~~~~~~~~~~~~~~~ -Nikola provides a separate command ``github_deploy`` to deploy your -site to GitHub pages. The command builds the site, commits the -output to a gh-pages branch and pushes the output to GitHub. +Nikola provides a separate command ``github_deploy`` to deploy your site to +GitHub pages. The command builds the site, commits the output to a gh-pages +branch and pushes the output to GitHub. Nikola uses the `ghp-import command +<https://github.com/davisp/ghp-import>`_ for this. The branch to use for committing the sources can be changed using the ``GITHUB_DEPLOY_BRANCH`` option in your config. For a @@ -1037,14 +1241,9 @@ push to the repository specified as the remote. This command performs the following actions, when it is run: -1. Ensure that your site is a git repository, and git is on the PATH. -2. Check for changes, and prompt the user to continue, if required. -3. Build the site -4. Clean any files that are "unknown" to Nikola. -5. Create a deploy branch, if one doesn't exist. -6. Commit the output to this branch. (NOTE: Any untracked source - files, may get committed at this stage, on the wrong branch!) -7. Push and deploy! +1. Builds the site +2. Commit the output folder to the ``GITHUB_DEPLOY_BRANCH`` to this branch. +3. Push the branch to the remote specified in ``GITHUB_REMOTE_NAME``! Comments and Annotations ------------------------ @@ -1063,8 +1262,8 @@ Nikola supports several third party comment systems: * `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 -"facebook" +to one of "disqus", "intensedebate", "livefyre", "moot", "googleplus", +"facebook" or "isso" .. sidebar:: ``COMMENT_SYSTEM_ID`` @@ -1080,7 +1279,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**, + * For isso, it is the URL of isso (must be world-accessible, encoded with + Punycode (if using Internationalized Domain Names) and **have a trailing slash**, default ``http://localhost:8080/``) To use comments in a visible site, you should register with the service and @@ -1126,7 +1326,7 @@ You can disable comments for a post by adding a "nocomments" metadata field to i #639). An alternative or complement to comments are annotations. Nikola integrates -the annotation service provided by `AnnotateIt. <annotateit.org>`_ +the annotation service provided by `AnnotateIt. <http://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. @@ -1137,30 +1337,53 @@ 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 ---------------- +Images and Galleries +-------------------- To create an image gallery, all you have to do is add a folder inside ``galleries``, and put images there. Nikola will take care of creating thumbnails, index page, etc. -If you click on images on a gallery, you should see a bigger image, thanks to -the excellent `colorbox <http://www.jacklmoore.com/colorbox>`_ +If you click on images on a gallery, or on images with links in post, you will +see a bigger image, thanks to the excellent `colorbox +<http://www.jacklmoore.com/colorbox>`_. If don’t want this behavior, add an +``.islink`` class to your image or link. The gallery pages are generated using the ``gallery.tmpl`` template, and you can customize it there (you could switch to another lightbox instead of colorbox, change its settings, change the layout, etc.). -The ``conf.py`` options affecting gallery pages are these:: +Images to be used in normal posts can be placed in the ``images`` folder. These +images will be processed and have thumbnails created just as for galleries, but will +then be copied directly to the corresponding path in the ``output`` directory, so you +can reference it from whatever page you like, most easily using the ``thumbnail`` +reST extension. If you don't want thumbnails, just use the ``files`` folder instead. + +The ``conf.py`` options affecting images and gallery pages are these:: - # Galleries are folders in galleries/ - # Final location of galleries will be output / GALLERY_PATH / gallery_name - GALLERY_PATH = "galleries" + # One or more folders containing galleries. The format is a dictionary of + # {"source": "relative_destination"}, where galleries are looked for in + # "source/" and the results will be located in + # "OUTPUT_PATH/relative_destination/gallery_name" + # Default is: + GALLERY_FOLDERS = {"galleries": "galleries"} + # More gallery options: THUMBNAIL_SIZE = 180 MAX_IMAGE_SIZE = 1280 USE_FILENAME_AS_TITLE = True - GALLERY_SORT_BY_DATE = False EXTRA_IMAGE_EXTENSIONS = [] + # If set to False, it will sort by filename instead. Defaults to True + GALLERY_SORT_BY_DATE = True + + # Folders containing images to be used in normal posts or pages. Images will be + # scaled down according to IMAGE_THUMBNAIL_SIZE and MAX_IMAGE_SIZE options, but + # will have to be referenced manually to be visible on the site + # (the thumbnail has ``.thumbnail`` added before the file extension). + # The format is a dictionary of {source: relative destination}. + + IMAGE_FOLDERS = {'images': 'images'} + IMAGE_THUMBNAIL_SIZE = 400 + 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. The format is the same as for posts. @@ -1212,20 +1435,50 @@ The currently available filters are: 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``. + You can turn any function into a filter using ``apply_to_text_file`` (for + text files to be read in UTF-8) and ``apply_to_binary_file`` (for files to + be read in binary mode). + 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 + from nikola.filters import apply_to_text_file FILTERS = { - ".html": [apply_to_file(string.upper)] + ".html": [apply_to_text_file(string.upper)] } +html_tidy_nowrap + Prettify HTML 5 documents with `tidy5 <http://www.html-tidy.org/>`_ + +html_tidy_wrap + Prettify HTML 5 documents wrapped at 80 characters with `tidy5 <http://www.html-tidy.org/>`_ + +html_tidy_wrap_attr + Prettify HTML 5 documents and wrap lines and attributes with `tidy5 <http://www.html-tidy.org/>`_ + +html_tidy_mini + Minify HTML 5 into smaller documents with `tidy5 <http://www.html-tidy.org/>`_ + +html_tidy_withconfig + Run `tidy5 <http://www.html-tidy.org/>`_ with ``tidy5.conf`` as the config file (supplied by user) + +html5lib_minify + Minify HTML5 using html5lib_minify + +html5lib_xmllike + Format using html5lib + +typogrify + Improve typography using `typogrify <http://static.mintchaos.com/projects/typogrify/>`__ + +typogrify_sans_widont + Same as typogrify without the widont filter + minify_lines - Strips leading whitespace and blank lines. Useful for compacting HTML but pre-formatted text must be escaped manually. + **THIS FILTER HAS BEEN TURNED INTO A NOOP** and currently does nothing. yui_compressor Compress CSS/JavaScript using `YUI compressor <http://yui.github.io/yuicompressor/>`_ @@ -1239,8 +1492,11 @@ optipng jpegoptim Compress JPEG files using `jpegoptim <http://www.kokkonen.net/tjko/projects.html>`_ -typogrify - Improve typography using `typogrify <https://github.com/mintchaos/typogrify>`_ + +You can apply filters to specific posts or pages by using the ``filters`` metadata field:: + + .. filters:: filters.html_tidy_nowrap, "sed s/foo/bar" + Optimizing Your Website @@ -1261,7 +1517,7 @@ different ones, or about other web servers, please share! AddType text/css .css -#. Optionally you can greate static compressed copies and save some CPU on your server +#. Optionally you can create static compressed copies and save some CPU on your server with the GZIP_FILES option in Nikola. #. The webassets Nikola plugin can drastically decrease the number of CSS and JS files your site fetches. @@ -1272,42 +1528,84 @@ different ones, or about other web servers, please share! #. The USE_CDN option offloads standard JavaScript and CSS files to a CDN so they are not downloaded from your server. -reStructuredText Extensions ---------------------------- - -Nikola includes support for a few directives and roles that are not part of docutils, but which -we think are handy for website development. +Math +---- + +Nikola supports math input via MathJax. It is activated via the math roles and +directives of reStructuredText and the usual LaTeX delimiters (``\(inline\)`` +and ``\[display\]``) for other input formats. + +We **DO NOT** support the old, deprecated and error-prone ``$inline$`` +delimiters by default. If you want to use them, please add them manually, +like this: + +.. code:: python + + """ + MATHJAX_CONFIG = """ + <script type="text/x-mathjax-config"> + MathJax.Hub.Config({ + tex2jax: { + inlineMath: [ ['$','$'], ["\\\(","\\\)"] ], + displayMath: [ ['$$','$$'], ["\\\[","\\\]"] ], + processEscapes: true + }, + displayAlign: 'left', // Change this to 'center' to center equations. + "HTML-CSS": { + styles: {'.MathJax_Display': {"margin": 0}} + } + }); + </script> + """ -MathJax -~~~~~~~ +Inline mathematics are produced using the reST `math` **role** or the ``\(…\)`` delimiters: -Nikola supports math input via MathJax. It uses the usual math roles and -directives of reStructuredText. +Euler’s formula: :math:`e^{ix} = \cos x + i\sin x` -In order to use them in your posts, you **must** add the special ``mathjax`` tag. +In reST: -Inline mathematics (equivalent to single dollar signs or backslash-parentheses -in LaTeX) are produced using the `math` **role**: +.. code:: restructuredtext -Euler’s formula: :math:`e^{ix} = \cos x + i\sin x` + Euler’s formula: :math:`e^{ix} = \cos x + i\sin x` -:: +In other input formats:: - Euler’s formula: :math:`e^{ix} = \cos x + i\sin x` + Euler’s formula: \(e^{ix} = \cos x + i\sin x\) -Display mathematics (equivalent to double dollar signs or backslash-brackets in -LaTeX) are produced using the `math` **directive**: +Display mathematics are produced using the reST `math` **directive** or the ``\[…\]`` delimiters: .. math:: \int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C + +In reST: + :: .. math:: \int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C +In other input formats: + +:: + + \[\int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C\] + +reStructuredText Extensions +--------------------------- + +Nikola includes support for a few directives and roles that are not part of docutils, but which +we think are handy for website development. + +Includes +~~~~~~~~ + +Nikola supports the standard reStructuredText ``include`` directive, but with a +catch: filenames are relative to **Nikola site root** (directory with ``conf.py``) +instead of the post location (eg. ``posts/`` directory)! + Media ~~~~~ @@ -1316,7 +1614,7 @@ URL of the page. For example here are two random videos:: .. media:: http://vimeo.com/72425090 - .. youtube:: http://www.youtube.com/watch?v=wyRpAat5oz0 + .. media:: 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>`_ @@ -1381,18 +1679,28 @@ for ``code`` directive are provided: ``code-block`` and ``sourcecode``:: Listing ~~~~~~~ -To use this, you have to put your source code files inside ``listings`` or whatever your -``LISTINGS_FOLDER`` variable is set to. Assuming you have a ``foo.py`` inside that folder:: +To use this, you have to put your source code files inside ``listings`` or whatever folders +your ``LISTINGS_FOLDERS`` variable is set to fetch files from. Assuming you have a ``foo.py`` +inside one of these folders:: .. listing:: foo.py python Will include the source code from ``foo.py``, highlight its syntax in python mode, -and also create a ``listings/foo.py.html`` page and the listing will have a title linking to it. +and also create a ``listings/foo.py.html`` page (or in another directory, depending on +``LISTINGS_FOLDER``) and the listing will have a title linking to it. Listings support the same options `reST includes`__ support (including various options for controlling which parts of the file are included), and also a ``linenos`` option for Sphinx compatibility. +The ``LISTINGS_FOLDER`` configuration variable allows to specify a list of folders where +to fetch listings from together with subfolder of the ``output`` folder where the +processed listings should be put in. The default is, ``LISTINGS_FOLDERS = {'listings': 'listings'}``, +which means that all source code files in ``listings`` will be taken and stored in ``output/listings``. +Extending ``LISTINGS_FOLDERS`` to ``{'listings': 'listings', 'code': 'formatted-code'}`` +will additionally process all source code files in ``code`` and put the results into +``output/formatted-code``. + __ http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment .. note:: @@ -1415,6 +1723,29 @@ Producing this: This degrades gracefully if the browser doesn't support JavaScript. +Thumbnails +~~~~~~~~~~ + +To include an image placed in the ``images`` folder (or other folders defined in ``IMAGE_FOLDERS``), use the +``thumbnail`` directive, like this:: + + .. thumbnail:: ../tesla.jpg + +(make sure to check the file paths!) + +The small thumbnail will be placed in the page, and it will be linked to the bigger +version of the image when clicked, using +`colorbox <http://www.jacklmoore.com/colorbox>`_ by default. All options supported by +the reST `image <http://docutils.sourceforge.net/docs/ref/rst/directives.html#image>`_ +directive are supported (except ``target``). If a body element is provided, the +thumbnail will mimic the behavior of the +`figure <http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure>`_ +directive instead:: + + .. thumbnail:: ../tesla.jpg + + Nikola Tesla, the man that invented the 20th century. + Slideshows ~~~~~~~~~~ @@ -1479,6 +1810,16 @@ and it will produce: Post List ~~~~~~~~~ +.. WARNING:: + + Any post or page that uses this directive will be considered out of date, + every time a post is added or deleted, causing maybe unnecessary rebuilds. + + On the other hand, it will sometimes **not** be considered out of date if + a post content changes, so it can sometimes be shown outdated, in those + cases, use ``nikola build -a`` to force a total rebuild. + + This directive can be used to generate a list of posts. You could use it, for example, to make a list of the latest 5 blog posts, or a list of all blog posts with the tag ``nikola``:: @@ -1486,26 +1827,70 @@ with the tag ``nikola``:: Here are my 5 latest and greatest blog posts: .. post-list:: - :start: -5 + :stop: 5 These are all my posts about Nikola: .. post-list:: :tags: nikola -Note that you can give the ``tags`` option a comma-separated list of tags, in -which case the list will show all posts that have at least one of those tags. -Other interesting options include ``stop`` (set it to ``-1``, for example, to -show all but the last post); ``reverse`` (set to ``True`` to sort the list in -chronological order, instead of the default latest-post-first); ``lang`` -(language to use for post titles and links); and ``slugs`` (allows you to filter -by post slugs, instead of tags). +The following options are recognized: + +* ``start`` : integer + The index of the first post to show. + A negative value like ``-3`` will show the *last* three posts in the + post-list. + Defaults to None. + +* ``stop`` : integer + The index of the last post to show. + A value negative value like ``-1`` will show every post, but not the + *last* in the post-list. + Defaults to None. + +* ``reverse`` : flag + Reverse the order of the post-list. + Defaults is to not reverse the order of posts. + +* ``sort``: string + Sort post list by one of each post's attributes, usually ``title`` or a + custom ``priority``. Defaults to None (chronological sorting). + +* ``tags`` : string [, string...] + Filter posts to show only posts having at least one of the ``tags``. + + Defaults to None. + +* ``slugs`` : string [, string...] + Filter posts to show only posts having at least one of the ``slugs``. + Defaults to None. + +* ``all`` : flag + Shows all posts and pages in the post list. + Defaults to show only posts with set *use_in_feeds*. + +* ``lang`` : string + The language of post *titles* and *links*. + Defaults to default language. + +* ``template`` : string + The name of an alternative template to render the post-list. + Defaults to ``post_list_directive.tmpl`` + +* ``id`` : string + A manual id for the post list. + Defaults to a random name composed by ``'post_list_' + uuid.uuid4().hex``. The post list directive uses the ``post_list_directive.tmpl`` template file (or another one, if you use the ``template`` option) to generate the list's HTML. By default, this is an unordered list with dates and clickable post titles. See the template file in Nikola's base theme for an example of how this works. +The list may fail to update in some cases, please run ``nikola build -a`` with +the appropriate path if this happens. + +We recommend using stories with dates in the past (1970-01-01) to avoid +dependency issues. Importing Your WordPress Site Into Nikola ----------------------------------------- @@ -1562,6 +1947,8 @@ Instead a new file with a timestamp at the end of the filename will be created. Using Twitter Cards ------------------- +Nikola supports Twitter Card summaries, but they are disabled by default. + Twitter Cards enable you to show additional information in Tweets that link to you content. Nikola supports `Twitter Cards <https://dev.twitter.com/docs/cards>`_. @@ -1570,24 +1957,25 @@ They are implemented to use *Open Graph* tags whenever possible. .. admonition:: Important To use Twitter Cards you need to opt-in on Twitter. - To do so please use the form that can be found at https://dev.twitter.com/form/participate-twitter-cards + To do so, please visit https://cards-dev.twitter.com/validator + +Images displayed come from the `previewimage` meta tag. -To enable and configure your use of Twitter Cards please modify the -corresponding lines in your ``conf.py``. -An example configuration that uses the Twitter nickname of the website -and the authors Twitter user ID is found below. +You can specify the card type by using the `card` parameter in TWITTER_CARD. + +To enable and configure your use of Twitter Cards, please modify the +corresponding lines in your ``conf.py``: .. code-block:: python TWITTER_CARD = { - 'use_twitter_cards': True, # enable Twitter Cards / Open Graph - 'site': '@website', # twitter nick for the website - # 'site:id': 123456, # Same as site, but the website's Twitter user ID instead. - # 'creator': '@username', # Username for the content creator / author. - 'creator:id': 654321, # Same as creator, but the Twitter user's ID. + 'use_twitter_cards': True, # enable Twitter Cards + 'card': 'summary', # Card type, you can also use 'summary_large_image', + # see https://dev.twitter.com/cards/types + 'site': '@website', # twitter nick for the website + 'creator': '@username', # Username for the content creator / author. } - Custom Plugins -------------- @@ -1599,7 +1987,7 @@ directories listed in the ``EXTRA_PLUGINS_DIRS`` configuration variable. Getting Extra Plugins --------------------- -If you want extra plugins, there is also the `Plugins Index <http://plugins.getnikola.com/>`_. +If you want extra plugins, there is also the `Plugins Index <https://plugins.getnikola.com/>`_. Similarly to themes, there is a nice, built-in command to manage them — ``plugin``:: @@ -1613,7 +2001,7 @@ Similarly to themes, there is a nice, built-in command to manage them — ⋮ $ nikola plugin --install helloworld - [2013-10-12T16:51:56Z] NOTICE: install_plugin: Downloading: http://plugins.getnikola.com/v6/helloworld.zip + [2013-10-12T16:51:56Z] NOTICE: install_plugin: Downloading: https://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. @@ -1641,7 +2029,7 @@ And upgrade them:: [2014-04-15T09:00:18Z] WARNING: plugin: This is not very smart, it just reinstalls some plugins and hopes for the best Will upgrade 1 plugins: graphviz Upgrading graphviz - [2014-04-15T09:00:20Z] INFO: plugin: Downloading: http://plugins.getnikola.com/v7/graphviz.zip + [2014-04-15T09:00:20Z] INFO: plugin: Downloading: https://plugins.getnikola.com/v7/graphviz.zip [2014-04-15T09:00:20Z] INFO: plugin: Extracting: graphviz into /home/ralsina/.nikola/plugins/ [2014-04-15T09:00:20Z] NOTICE: plugin: This plugin has third-party dependencies you need to install manually. Contents of the requirements-nonpy.txt file: @@ -1658,8 +2046,19 @@ 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. +Advanced Features +----------------- + +Debugging +~~~~~~~~~ + +For pdb debugging in Nikola, you should use ``doit.tools.set_trace()`` instead +of the usual pdb call. By default, doit (and thus Nikola) redirects stdout and +stderr. Thus, you must use the different call. (Alternatively, you could run +with ``nikola build -v 2``, which disables the redirections.) + Shell Tab Completion --------------------- +~~~~~~~~~~~~~~~~~~~~ Since Nikola is a command line tool, and this is the 21st century, it's handy to have smart tab-completion so that you don't have to type the full commands. |