From 8041475aab2b8efad7d2857027331bd626d26312 Mon Sep 17 00:00:00 2001 From: Agustin Henze Date: Wed, 26 Aug 2015 07:57:04 -0300 Subject: Imported Upstream version 7.6.4 --- docs/extending.txt | 38 +- docs/man/nikola.1.gz | Bin 1777 -> 1785 bytes docs/man/nikola.rst | 4 +- docs/manual.txt | 896 ++++++++++++++++++++++-------------------------- docs/social_buttons.txt | 2 +- docs/sphinx/conf.py | 4 +- docs/support.rst | 14 +- docs/theming.txt | 4 +- 8 files changed, 463 insertions(+), 499 deletions(-) (limited to 'docs') diff --git a/docs/extending.txt b/docs/extending.txt index 9db5344..bb94003 100644 --- a/docs/extending.txt +++ b/docs/extending.txt @@ -8,7 +8,7 @@ Extending Nikola ================ -:Version: 7.6.0 +:Version: 7.6.4 :Author: Roberto Alsina .. class:: alert alert-info pull-right @@ -34,7 +34,9 @@ of Nikola. Command Plugins --------------- -When you run ``nikola --help`` you will see something like this:: +When you run ``nikola --help`` you will see something like this: + +.. code-block:: console $ nikola help Nikola is a tool to create static websites and blogs. For full documentation and more @@ -146,7 +148,9 @@ For your own plugin, just change the values in a sensible way. The httpd.serve_forever() As mentioned above, a plugin can have options, which the user can see by doing -``nikola help command`` and can later use, for example:: +``nikola help command`` and can later use, for example: + +.. code-block:: console $ nikola help serve Purpose: start the test webserver @@ -242,6 +246,7 @@ a stub for a hypothetical system called "Templater": template search mechanism.""" pass +You can see a real example in `the Jinja plugin `__ Task Plugins ------------ @@ -257,7 +262,7 @@ T and ``TaskMultiplier`` plugins that take a task and create more tasks out of it. -:: +.. code-block:: console $ nikola list Scanning posts....done! @@ -361,7 +366,7 @@ PageCompiler Plugins -------------------- These plugins implement markup languages, they take sources for posts or pages and -create HTML or other output files. A good example is the ``misaka`` plugin. +create HTML or other output files. A good example is `the misaka plugin. `__ They must provide: @@ -381,12 +386,27 @@ metadata contained in the file. RestExtension Plugins --------------------- -Implement directives for reStructuredText, see ``media.py`` for a simple example. +Implement directives for reStructuredText, see `media.py `__ for a simple example. + +If your output depends on a config value, you need to make your post record a dependency on a pseudo-path, like this: + +.. code-block:: text + + ####MAGIC####CONFIG:OPTIONNAME + +Then, whenever the ``OPTIONNAME`` option is changed in conf.py, the file will be rebuilt. + +If your directive depends or may depend on the whole timeline (like the post-list directive, where adding new posts +to the site could make it stale), you should record a dependency on the +pseudo-path ``####MAGIC####TIMELINE``. MarkdownExtension Plugins ------------------------- -Implement Markdown extensions, see ``mdx_nikola.py`` for a simple example. +Implement Markdown extensions, see `mdx_nikola.py `__ for a simple example. + +Note that python markdown extensions are often also available as separate packages. This is only meant to ship extensions +along with Nikola. SignalHandler Plugins --------------------- @@ -424,13 +444,15 @@ Currently Nikola emits the following signals: 'undeployed': # all files not deployed since they are either future posts/drafts } +One example is the `deploy_hooks plugin. `__ + ConfigPlugin Plugins -------------------- Does nothing specific, can be used to modify the site object (and thus the config). Put all the magic you want in ``set_site()``, and don’t forget to run the one -from ``super()``. +from ``super()``. Example plugin: `navstories `__ PostScanner Plugins ------------------- diff --git a/docs/man/nikola.1.gz b/docs/man/nikola.1.gz index e2425f4..db17fa8 100644 Binary files a/docs/man/nikola.1.gz and b/docs/man/nikola.1.gz differ diff --git a/docs/man/nikola.rst b/docs/man/nikola.rst index 036170d..633cb33 100644 --- a/docs/man/nikola.rst +++ b/docs/man/nikola.rst @@ -6,7 +6,7 @@ Nikola A Static Site and Blog Generator -------------------------------- -:Version: Nikola v7.6.0 +:Version: Nikola v7.6.4 :Manual section: 1 :Manual group: User Commands @@ -94,7 +94,7 @@ The most basic commands needed to get by are: deploy the site using the ``DEPLOY_COMMANDS`` setting ``nikola github_deploy``` deploy the site to GitHub Pages -``nikola serve [-p PORT] [-a ADDRESS] [-b|--browser] [-6|--ipv6]`` +``nikola serve [-p PORT] [-a ADDRESS] [-d|--detach] [-b|--browser] [-6|--ipv6]`` start development web server ``nikola auto [-p PORT] [-a ADDRESS] [-b|--browser] [-6|--ipv6]`` start development web server with automated rebuilds and reloads diff --git a/docs/manual.txt b/docs/manual.txt index d287099..09f428a 100644 --- a/docs/manual.txt +++ b/docs/manual.txt @@ -3,11 +3,12 @@ .. date: 2012-03-30 23:00:00 UTC-03:00 .. link: .. description: +.. tags: mathjax The Nikola Handbook =================== -:Version: 7.6.0 +:Version: 7.6.4 .. class:: alert alert-info pull-right @@ -17,7 +18,7 @@ The Nikola Handbook All You Need to Know -------------------- -After you have Nikola `installed <#installing-nikola>`_: +After you have Nikola `installed `_: Create an empty site (with a setup wizard): ``nikola init mysite`` @@ -36,7 +37,7 @@ Edit the post: Build the site: ``nikola build`` -Start the test server and open a browser (http://127.0.0.1:8000/): +Start the test server and open a browser: ``nikola serve -b`` @@ -158,268 +159,48 @@ Lock-in With Nikola, you own your files, and you can do anything with them. -Features --------- +Components +---------- -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. +Nikola provides the following features: -If you want to create a blog or a site, Nikola provides: +* Blog support, including: -* Front page (and older posts pages) -* RSS Feeds -* Pages and feeds for each tag you used -* Custom search -* Full yearly archives + * Indexes + * RSS and Atom feeds + * Tags and categories, with pages and feeds + * Archives with custom granularity (yearly or monthly) + * `Comments`_ + * Client-side tag clouds (needs manual configuration) + +* Static pages (not part of the blog) +* `Math`_ rendering (via MathJax) * Custom output paths for generated pages +* Pretty URLs (without ``.html``) that don’t need web server support * Easy page template customization -* Static pages (not part of the blog) -* Internationalization support (my own blog is English/Spanish) -* 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 `__ or - `Markdown `_) +* Internationalization support (my own blog is English and Spanish) +* Sitemap generation (for search engines) +* Custom deployment (if it’s a command, you can use it) +* GitHub Pages deployment +* Themes, easy appearance customization +* `Multiple input formats <#supported-input-formats>`_, including reStructuredText and Markdown * Easy-to-create image galleries -* Support for displaying source code +* Image thumbnail generation +* Support for displaying source code listings * Image slideshows -* Client-side cloud tags - -Also: - -* 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. - -Installing Nikola ------------------ - -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 nikola - -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:: - - pip install nikola[extras] - -Alternatively, you can install those packages one-by-one, when required (Nikola -will tell you what packages are needed) - -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. - -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 (files missing) errors -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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 libxslt1-dev zlib1g-dev - -Red Hat/RPM-based systems:: - - sudo yum install libxslt-devel libxml2-devel zlib-devel - -Python.h not found -~~~~~~~~~~~~~~~~~~ - -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 Windows and Windows support -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Nikola supports Windows! Keep in mind, though, that there are some -caveats: - -#. ``lxml`` and ``Pillow`` require compiled extensions. Compiling them on - Windows is hard for most people. Fortunately, compiled packages exist. - Check their `PyPI `_ pages to find official packages, - `the unofficial Gohlke binaries `_ - site, or get them somewhere else. If you are using virtualenvs, using those - 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 differences include: - - * ``\`` as path separator (instead of ``/``) - * 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``) - -#. Most of our developers run Linux on a daily basis and may not have the full - knowledge required to resolve issues relating to Windows. +* Custom search +* Asset (CSS/JS) bundling +* gzip compression (for sending via your web server) +* Open Graph, Twitter Cards +* Hyphenation +* Custom `post processing filters`_ (eg. for minifying files or better typography) 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 more details, -read `Configuring other input formats`_. - -.. note:: There is a great `quick tutorial to learn reStructuredText. `__ - -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 `__, 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! - . render_posts:stories/manual.html - . render_posts:posts/1.html - . render_posts:stories/1.html - . render_archive:output/2012/index.html - . render_archive:output/archive.html - . render_indexes:output/index.html - . render_pages:output/posts/welcome-to-nikola.html - . render_pages:output/stories/about-nikola.html - . 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! - -That is because `doit `__ 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. +.. class:: lead -Nikola is mostly a series of doit *tasks*, and you can see them by doing ``nikola list``:: - - $ nikola list - Scanning posts....done! - build_bundles - copy_assets - copy_files - deploy - redirect - render_archive - render_galleries - render_indexes - render_listings - render_pages - render_posts - render_rss - render_site - render_sources - render_tags - sitemap - -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 is a tool to create static websites and blogs. For full documentation and more information, please visit https://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 - nikola deploy deploy the site - nikola doit_auto automatically execute tasks when a dependency changes - nikola dumpdb dump dependency DB - nikola forget clear successful run status from internal DB - nikola github_deploy deploy the site to GitHub pages - nikola help show help - nikola ignore ignore task (skip) on subsequent runs - 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_page create a new page in the site - nikola new_post create a new blog post or site page - nikola orphans list all orphans - 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-completion - nikola version print the Nikola version number - - nikola help show help / reference - nikola help show command usage - nikola help show task usage - -The ``serve`` command starts a web server so you can see the site you are creating:: - - $ nikola serve -b - Serving HTTP on 127.0.0.1 port 8000 ... - - -After you do this, a web browser opens at http://127.0.0.1:8000/ and you should see -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 explicitly using ``-a IP_ADDRESS`` -(short version of ``--address``) or ``-p PORT_NUMBER`` (short version of ``--port``) -Example usage:: - - $ nikola serve --address 0.0.0.0 --port 8080 - Serving HTTP on 0.0.0.0 port 8080 ... +To set Nikola up and create your first site, read the `Getting Started Guide `_. Creating a Blog Post -------------------- @@ -435,25 +216,35 @@ easier to keep it in a single location. The contents of your post have to be written (by default) in `reStructuredText `__ but you can use a lot of different markups using the ``-f`` option. -Currently Nikola supports reStructuredText, Markdown, IPython Notebooks, HTML as input, +Currently, Nikola supports reStructuredText, Markdown, IPython (Jupyter) Notebooks, HTML as input, can also use Pandoc for conversion, and has support for BBCode, CreoleWiki, txt2tags, Textile -and more via `plugins `__. -For more details, read `Configuring other input formats`_. +and more via plugins — for more details, read the `input format documentation +<#multiple-input-formats>`__. +You can learn reStructuredText syntax with the `reST quickstart `__. + +Please note that Nikola does not guarantee support for encodings other than +UTF-8. We recommend converting your input files to that encoding. It will +prevent bugs, and Nikola will write UTF-8 output anyway. 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 ``POSTS`` and ``PAGES`` options) -This is how it works:: +This is how it works: + +.. code:: console $ nikola new_post Creating New Post ----------------- - Enter title: How to make money - Your post's text is at: posts/how-to-make-money.txt + Title: How to make money + Scanning posts....done! + INFO: new_post: Your post's text is at: posts/how-to-make-money.rst -The content of that file is as follows:: +The content of that file is as follows: + +.. code:: restructuredtext .. title: How to make money .. slug: how-to-make-money @@ -481,7 +272,9 @@ 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: + +.. code:: python ADDITIONAL_METADATA = { 'author': 'John Doe' @@ -492,63 +285,70 @@ 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) + 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. + 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. + Like tags, except each post can have only one, and they usually have + more descriptive names. filters - See the `Post Processing Filters`_ section. + 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). + 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:: + Set to "True" to disable comments. Example: + + .. code:: restructuredtext - .. nocomments: True + .. 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. + 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! + 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 `_ + More information: `Issue #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. + 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 + .. code:: restructuredtext - 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). + .. 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:: + Change the template used to render this page/post specific page. That + template needs to either be part of the theme, or be placed in a + ``templates/`` folder inside your site. - .. template: story.tmpl + .. code:: restructuredtext - That template needs to either be part of the theme, or be placed in a ``templates/`` - folder inside your site. + .. template: story.tmpl - enclosure - Add an enclosure to this post when it's used in RSS. See `more information about enclosures `__ + enclosure + Add an enclosure to this post when it's used in RSS. See `more information about enclosures `__ .. 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 (i.e. only the 7 base fields, in the order listed above), but without the - explanations:: + explanations: + + .. code:: text How to make money how-to-make-money @@ -558,9 +358,11 @@ to your configuration:: all metadata you want, complete with the explanations — they look just like the beginning of our reST files. - .. title: How to make money - .. slug: how-to-make-money - .. date: 2012-09-15 19:52:05 UTC + .. code:: restructuredtext + + .. title: How to make money + .. slug: how-to-make-money + .. date: 2012-09-15 19:52:05 UTC Both file formats are supported; however, the new format is preferred, if possible. @@ -578,7 +380,9 @@ TRANSLATIONS_PATTERN variable in your configuration file. The default is to put the language code before the file extension, so the German translation of ``some_file.rst`` should be named ``some_file.de.rst``. This is because the TRANSLATIONS_PATTERN variable is by -default set to:: +default set to: + +.. code:: python TRANSLATIONS_PATTERN = "{path}.{lang}.{ext}" @@ -588,46 +392,18 @@ default set to:: 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 -* Hindi -* Italian -* Japanese -* Norwegian Bokmål -* Persian -* Polish -* Portuguese (Brasil) -* Russian -* Slovak -* Slovene -* Spanish -* Turkish -* Urdu - -If you wish to add support for more languages, check out the instructions -at the `theming guide `_. +with the contents, generate the pages using ``nikola build``. + +Nikola supports multiple languages for a post (we have almost 40 translations!). If you wish to +add support for more languages, check out `the Transifex page for Nikola `_ 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 ``POSTS`` -and ``PAGES`` configuration options:: +and ``PAGES`` configuration options: + +.. code:: python # POSTS and PAGES contains (wildcard, destination, template) tuples. # @@ -668,19 +444,26 @@ 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 written into. If no such entry can be found, the post won’t be created. -The ``new_post`` command supports some options:: +The ``new_post`` command supports some options: + +.. code:: text $ nikola help new_post - Purpose: Create a new blog post or site page. + Purpose: create a new blog post or site page Usage: nikola new_post [options] [path] Options: - -p, --page Create a page instead of a blog post. - -t ARG, --title=ARG Title for the page/post. - --tags=ARG Comma-separated tags for the page/post. - -1 Create post with embedded metadata (single file format) - -2 Create post with separate metadata (two file format) - -f ARG, --format=ARG Markup format for post, one of rest, markdown, wiki, bbcode, html, textile, txt2tags + -p, --page Create a page instead of a blog post. (see also: `nikola new_page`) + -t ARG, --title=ARG Title for the post. + -a ARG, --author=ARG Author of the post. + --tags=ARG Comma-separated tags for the post. + -1 Create the post with embedded metadata (single file format) + -2 Create the post with separate metadata (two file format) + -e Open the post (and meta file, if any) in $EDITOR after creation. + -f ARG, --format=ARG Markup format for the post (use --available-formats for list) + -F, --available-formats List all available input formats + -s Schedule the post based on recurrence rule + -i ARG, --import=ARG Import an existing file instead of creating a placeholder The optional ``path`` parameter tells nikola exactly where to put it instead of guessing from your config. So, if you do ``nikola new_post posts/random/foo.txt`` you will have a post in that path, with @@ -694,11 +477,15 @@ 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: + +.. code:: restructuredtext .. TEASER_END -In Markdown (or basically, the resulting HTML of any format):: +In Markdown (or basically, the resulting HTML of any format): + +.. code:: html @@ -709,11 +496,24 @@ page should display the whole contents or only teasers. ``RSS_TEASERS`` works the same way for your RSS feeds. By default, teasers will include a "read more" link at the end. If you want to -change that text, you can use a custom teaser:: +change that text, you can use a custom teaser: + +.. code:: restructuredtext .. TEASER_END: click to read the rest of the article -Or you can completely customize the link using the ``READ_MORE_LINK`` option:: +You can override the default value for ``TEASER_END`` in ``conf.py`` — for +example, the following example will work for ``.. more``, and will be +compatible with both WordPress and Nikola posts: + +..code:: python + + import re + TEASER_REGEXP = re.compile('', re.IGNORECASE) + +Or you can completely customize the link using the ``READ_MORE_LINK`` option. + +.. code:: python # A HTML fragment with the Read more... link. # The following tags exist and are replaced for you: @@ -741,8 +541,8 @@ published immediately. Posts dated in the future are *not* deployed by default 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. -Private (formerly retired) Posts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Private Posts +~~~~~~~~~~~~~ If you add a "private" 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 it will @@ -763,7 +563,9 @@ 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`` to your configuration: + +.. code:: python SCHEDULE_RULE = 'RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR;BYHOUR=7;BYMINUTE=0;BYSECOND=0' @@ -773,7 +575,9 @@ For more details on how to specify a recurrence rule, look at the 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:: +you want: + +.. code:: console $ nikola new_post --schedule # Creates a new post to be posted on Monday, 7am. @@ -797,6 +601,8 @@ types affect the look of your posts, by adding a ``post-YOURINPUTHERE`` CSS class to the post. Each post can have one and exactly one type. Nikola styles the following types in the default themes: +.. class:: table table-bordered + +-----------------+----------------------------+------------------+ | Name(s) | Description | Styling | +=================+============================+==================+ @@ -805,6 +611,95 @@ styles the following types in the default themes: | micro | “small” (short) posts | big serif font | +-----------------+----------------------------+------------------+ +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 +--------------- + +Pages are the same as posts, except that: + +* They are not added to the front page +* They don't appear on the RSS feed +* 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 ``PAGES`` option above). + +You can create the page's files manually or use the ``new_post`` command +with the ``-p`` option, which will place the files in the folder that +has ``use_in_feed`` set to False. + +Supported input formats +----------------------- + +Nikola supports multiple input formats. Out of the box, we have compilers available for: + +* reStructuredText (default and pre-configured) +* `Markdown`_ +* `IPython Notebook/Jupyter`_ +* `HTML`_ +* `PHP`_ +* anything `Pandoc`_ supports (including Textile, DocBook, LaTeX, MediaWiki, + TWiki, OPML, Emacs Org-Mode, txt2tags, Microsoft Word .docx, EPUB, Haddock markup) + +Plus, we have specialized compilers in the Plugins Index for: + +* `AsciiDoc `_ +* `BBCode `_ +* `CommonMark `_ +* `IRC logs `_ +* `Markmin `_ +* `MediaWiki (smc.mw) `_ +* `Misaka `_ +* `ODT `_ +* `Emacs Org-Mode `_ +* `reST with HTML 5 output `_ +* `Textile `_ +* `txt2tags `_ +* `CreoleWiki `_ +* `WordPress posts `_ + Configuring other input formats ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -876,70 +771,13 @@ 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 ---------------- - -Pages are the same as posts, except that: - -* They are not added to the front page -* They don't appear on the RSS feed -* 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 ``PAGES`` option above). - -You can create the page's files manually or use the ``new_post`` command -with the ``-p`` option, which will place the files in the folder that -has ``use_in_feed`` set to False. - Redirections ------------ If you need a page to be available in more than one place, you can define redirections -in your ``conf.py``:: +in your ``conf.py``: + +.. code:: python # A list of redirection tuples, [("foo/from.html", "/bar/to.html")]. # @@ -964,7 +802,9 @@ still should not be terribly hard to grasp. The default ``conf.py`` you get with Nikola should be fairly complete, and is quite commented. -You surely want to edit these options:: +You surely want to edit these options: + +.. code:: python # Data about this site BLOG_AUTHOR = "Your Name" # (translatable) @@ -976,13 +816,13 @@ You surely want to edit these options:: Some options are demarked with a (translatable) comment above or right next to 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 +* 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``. + build your blog using the configuration file ``configurations/test.conf.py``, + you have to execute ``nikola build --conf=configurations/test.conf.py``. Customizing Your Site --------------------- @@ -1024,7 +864,9 @@ Navigation Links 1. A (url, text) tuple, describing a link 2. A (((url, text), (url, text), (url, text)), title) tuple, describing a submenu / sublist. - Example:: + Example: + + .. code:: python NAVIGATION_LINKS = { DEFAULT_LANG: ( @@ -1038,20 +880,16 @@ Navigation Links .. note:: - Support for submenus is theme-dependent. Only one level of - submenus is supported. - - .. note:: + 1. Support for submenus is theme-dependent. Only one level of + submenus is supported. - 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:: + 2. 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.) - 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. + 3. 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 @@ -1138,11 +976,13 @@ with files Nikola generates (it will give an error). .. admonition:: Important - Don't put any files manually in ``output/``. Ever. Really. Maybe someday Nikola - will just wipe ``output/`` and then you will be sorry. So, please don't do that. + Don't put any files manually in ``output/``. Ever. Really. + Maybe someday Nikola will just wipe ``output/`` (when you run ``nikola check -f --clean-files``) and then you will be sorry. So, please don't do that. If you want to copy more than one folder of static files into ``output`` you can -change the FILES_FOLDERS option:: +change the FILES_FOLDERS option: + +.. code:: python # One or more folders containing files to be copied as-is into the output. # The format is a dictionary of "source" "relative destination". @@ -1155,7 +995,10 @@ Getting More Themes There are a few themes for Nikola. They are available at the `Themes Index `_. -Nikola has a built-in theme download/install mechanism to install those themes — the ``install_theme`` command:: +Nikola has a built-in theme download/install mechanism to install those themes — the ``install_theme`` command: + + +.. code:: console $ nikola install_theme -l Themes: @@ -1178,7 +1021,10 @@ request in the `GitHub repository ` 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:: +to create a custom theme by downloading free CSS files from http://bootswatch.com: + + +.. code:: console $ nikola bootswatch_theme -n custom_theme -s spruce -p bootstrap3 [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Creating 'custom_theme' theme @@ -1208,7 +1054,9 @@ 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:: +Here is an example, from my own site's deployment script: + +.. code:: python DEPLOY_COMMANDS = {'default': [ 'rsync -rav --delete output/ ralsina@lateral.netmanagers.com.ar:/srv/www/lateral', @@ -1294,7 +1142,9 @@ I recommend 3rd party comments, and specially DISQUS because: 3) It's free. 4) It's damn nice. -You can disable comments for a post by adding a "nocomments" metadata field to it:: +You can disable comments for a post by adding a "nocomments" metadata field to it: + +.. code:: restructuredtext .. nocomments: True @@ -1358,7 +1208,9 @@ then be copied directly to the corresponding path in the ``output`` directory, s 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:: +The ``conf.py`` options affecting images and gallery pages are these: + +.. code:: python # One or more folders containing galleries. The format is a dictionary of # {"source": "relative_destination"}, where galleries are looked for in @@ -1405,7 +1257,9 @@ You can apply post processing to the files in your site, in order to optimize th or change them in arbitrary ways. For example, you may want to compress all CSS and JS files using yui-compressor. -To do that, you can use the provided helper adding this in your ``conf.py``:: +To do that, you can use the provided helper adding this in your ``conf.py``: + +.. code:: python from nikola import filters @@ -1493,9 +1347,11 @@ jpegoptim Compress JPEG files using `jpegoptim `_ -You can apply filters to specific posts or pages by using the ``filters`` metadata field:: +You can apply filters to specific posts or pages by using the ``filters`` metadata field: + +.. code:: restructuredtext - .. filters:: filters.html_tidy_nowrap, "sed s/foo/bar" + .. filters: filters.html_tidy_nowrap, "sed s/foo/bar" @@ -1509,11 +1365,15 @@ 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. -#. Enable compression in Apache:: +#. Enable compression in Apache: + + .. code:: apache AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript -#. If even after you did the previous step the CSS files are not sent compressed:: +#. If even after you did the previous step the CSS files are not sent compressed: + + .. code:: apache AddType text/css .css @@ -1541,7 +1401,6 @@ like this: .. code:: python - """ MATHJAX_CONFIG = """