diff options
Diffstat (limited to 'docs')
31 files changed, 2143 insertions, 251 deletions
diff --git a/docs/creating-a-site.txt b/docs/creating-a-site.txt index 0891753..1e5cf29 100644 --- a/docs/creating-a-site.txt +++ b/docs/creating-a-site.txt @@ -4,6 +4,7 @@ .. link: .. description: .. title: Creating a Site (Not a Blog) with Nikola +.. author: The Nikola Team Creating a Site (Not a Blog) with Nikola ======================================== @@ -19,7 +20,9 @@ Nikola’s `own site <https://getnikola.com/>`_ is a fairly generic one. Let’s step by step on how you can do something like that. As usual when starting a nikola site, you start with ``nikola init`` which creates a -empty (mostly) configured site:: +empty (mostly) configured site: + +.. code:: console $ nikola init mysite Creating Nikola Site @@ -30,13 +33,7 @@ empty (mostly) configured site:: Then we go into the new ``mysite`` folder, and make the needed changes in the ``conf.py`` configuration file: -.. code-block:: python - - - ############################################## - # Configuration, please edit - ############################################## - +.. code:: python # Data about this site BLOG_AUTHOR = "Roberto Alsina" @@ -51,15 +48,21 @@ configuration file: # Some things in the middle you don't really need to change... # - POSTS = [] - PAGES = [("pages/*.txt", "", "story.tmpl")] + POSTS = () + # you can also keep the current content of POSTS if you want a blog with your site + PAGES = ( + ("pages/*.rst", "", "story.tmpl"), + ("pages/*.txt", "", "story.tmpl"), + ("pages/*.html", "", "story.tmpl"), + ) # And to avoid a conflict because blogs try to generate /index.html INDEX_PATH = "blog" +And now we are ready to create our first page: -And now we are ready to create our first page:: +.. code:: console $ nikola new_page Creating New Page @@ -67,11 +70,11 @@ And now we are ready to create our first page:: Title: index Scanning posts....done! - [1970-01-01T00:00:00Z] INFO: new_page: Your page's text is at: stories/index.rst + [1970-01-01T00:00:00Z] INFO: new_page: Your page's text is at: pages/index.rst -.. note:: The ``-p`` option in the ``nikola new_post`` command means we are creating a page and not a blog post. +We can now build and preview our site: -We can now build and preview our site:: +.. code:: console $ nikola build Scanning posts.done! @@ -87,7 +90,7 @@ And you can see your (very empty) site in http://localhost:8000/ So, what’s in that ``pages/index.txt`` file? -.. code-block:: rest +.. code:: rest .. title: index .. slug: index @@ -101,19 +104,21 @@ So, what’s in that ``pages/index.txt`` file? ``title`` is the page title, ``slug`` is the name of the generated HTML file (in this case it would be ``index.html``). ``date``, ``tags`` and ``link`` -doesn’t matter at all in stories. ``description`` is useful for SEO purposes +doesn’t matter at all in pages. ``description`` is useful for SEO purposes if you care for that. -And below, the content. By default you are expected to use -`reStructuredText <https://getnikola.com/quickstart.html>`_ but -Nikola supports a ton of formats, including Markdown, plain HTML, BBCode, -Wiki, and Textile. +And below, the content. By default Nikola uses +`reStructuredText <https://getnikola.com/quickstart.html>`_ but it supports +a ton of formats, including Markdown, plain HTML, Jupyter Notebooks, BBCode, +Wiki, and Textile. We will use reStructuredText for this example, but some +people might find it a bit too limiting — if that is the case, try using HTML +for your pages (Nikola does this on the index page, for example). So, let's give the page a nicer title, and some fake content. Since the default Nikola theme (called ``bootstrap3``) is based on `Bootstrap <http://getbootstrap.com/>`_ you can use anything you like from it: -.. code-block:: rest +.. code:: rest .. title: Welcome To The Fake Site .. slug: index @@ -150,10 +155,11 @@ you can use anything you like from it: .. admonition:: TIP: Nice URLs If you like your URLs without the ``.html`` then you want to create folders and - put the pages in ``index.html`` inside them using the ``PRETTY_URLS`` option. + put the pages in ``index.html`` inside them using the ``PRETTY_URLS`` option + (on by default) And that's it. You will want to change the NAVIGATION_LINKS option to create a reasonable -menu for your site, you will want to modify the theme (check ``nikola help bootswatch_theme`` +menu for your site, you may want to modify the theme (check ``nikola help bootswatch_theme`` for a quick & dirty solution), and you may want to add a blog later on, for company news or whatever. @@ -161,9 +167,13 @@ or whatever. First, change the ``POSTS`` option like this: - .. code-block:: python + .. code:: python - POSTS = [("posts/*.txt", "blog", "post.tmpl", True)] + POSTS = ( + ("posts/*.rst", "blog", "post.tmpl"), + ("posts/*.txt", "blog", "post.tmpl"), + ("posts/*.html", "blog", "post.tmpl"), + ) Create a post with ``nikola new_post`` and that's it, you now have a blog in the ``/blog/`` subdirectory of your site — you may want to link to diff --git a/docs/creating-a-theme.txt b/docs/creating-a-theme.txt index 7113b1a..8cd2a49 100644 --- a/docs/creating-a-theme.txt +++ b/docs/creating-a-theme.txt @@ -1,4 +1,3 @@ -.. title: Creating A Theme .. slug: creating-a-theme .. date: 2015-05-28 18:46:48 UTC .. tags: @@ -7,6 +6,9 @@ .. description: .. type: text +Creating a Theme +================ + Nikola is a static site and blog generator. So is Jekyll. While I like what we have done with Nikola, I do admit that Jekyll (and others!) have many more, and nicer themes than Nikola does. @@ -72,7 +74,7 @@ First, we create a site with some content in it. We’ll use the ``nikola init`` Creating Nikola Site ==================== - This is Nikola v7.4.1. We will now ask you a few easy questions about your new site. + This is Nikola v7.8.0. We will now ask you a few easy questions about your new site. If you do not want to answer and want to go with the defaults instead, simply restart with the `-q` parameter. --- Questions about the site --- Site title [My Nikola Site]: @@ -105,12 +107,10 @@ First, we create a site with some content in it. We’ll use the ``nikola init`` Then, we create an empty theme inheriting from base. This theme will use Mako templates. If you prefer Jinja2, -then you should use ``base-jinja`` instead:: +then you should use ``base-jinja`` as a parent and ``jinja`` as engine instead:: $ cd lanyon-port/ - $ mkdir themes - $ mkdir themes/lanyon - $ echo base > themes/lanyon/parent + $ nikola theme -n lanyon --parent base --engine mako Edit ``conf.py`` and set ``THEME = 'lanyon'``. Also set ``USE_BUNDLES = False`` (just do it for now, we’ll get to bundles later). @@ -205,11 +205,11 @@ But how do I tell **our** lanyon theme to use those CSS files instead of whateve By giving our theme its own base_helper.tmpl. That file is a **template** used to generate parts of the pages. It’s large and -complicated but we don’t need to change a lot of it. First, get it from -`Nikola’s source code <https://github.com/getnikola/nikola/blob/master/nikola/data/themes/base/templates/base_helper.tmpl>`__ and put a copy in ``themes/lanyon/templates/base_helper.tmpl``:: +complicated but we don’t need to change a lot of it. First, make a copy in your +theme (note this command requires setting your ``THEME`` in ``conf.py`` to +``lanyon``):: - $ mkdir themes/lanyon/templates - $ curl https://raw.githubusercontent.com/getnikola/nikola/master/nikola/data/themes/base/templates/base_helper.tmpl > themes/lanyon/templates/base_helper.tmpl + $ nikola theme -c base_helper.tmpl The part we want to change is this: diff --git a/docs/extending.txt b/docs/extending.txt index bb94003..4fa935d 100644 --- a/docs/extending.txt +++ b/docs/extending.txt @@ -4,11 +4,12 @@ .. tags: .. link: .. description: +.. author: The Nikola Team Extending Nikola ================ -:Version: 7.6.4 +:Version: 7.8.1 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> .. class:: alert alert-info pull-right @@ -62,13 +63,13 @@ When you run ``nikola --help`` you will see something like this: nikola import_feed import a RSS/Atom dump nikola import_wordpress import a WordPress dump nikola init create a Nikola site in the specified folder - nikola install_theme install theme into current site nikola list list tasks from dodo file nikola mincss apply mincss to the generated site nikola new_post create a new blog post or site page nikola run run tasks nikola serve start the test webserver nikola strace use strace to list file_deps and targets + nikola theme manage themes nikola version print the Nikola version number nikola help show help / reference @@ -122,7 +123,7 @@ For your own plugin, just change the values in a sensible way. The 'long': 'port', 'default': 8000, 'type': int, - 'help': 'Port nummber (default: 8000)', + 'help': 'Port number (default: 8000)', }, { 'name': 'address', @@ -157,7 +158,7 @@ As mentioned above, a plugin can have options, which the user can see by doing Usage: nikola serve [options] Options: - -p ARG, --port=ARG Port nummber (default: 8000) + -p ARG, --port=ARG Port number (default: 8000) -a ARG, ----address=ARG Address to bind (default: 127.0.0.1) $ nikola serve -p 9000 @@ -171,8 +172,8 @@ TemplateSystem Plugins ---------------------- Nikola supports Mako and Jinja2. If you prefer some other templating -system, then you will have to write a TemplateSystem plugin. Here's how they work. -First, you have to create a .plugin file. Here's the one for the Mako plugin: +system, then you will have to write a ``TemplateSystem`` plugin. Here's how they work. +First, you have to create a ``.plugin`` file. Here's the one for the Mako plugin: .. code-block:: ini @@ -252,10 +253,10 @@ Task Plugins ------------ If you want to do something that depends on the data in your site, you -probably want to do a Task plugin, which will make it be part of the -``nikola build`` command. There are the currently available tasks, all +probably want to do a ``Task`` plugin, which will make it be part of the +``nikola build`` command. These are the currently available tasks, all provided by plugins: -T + .. sidebar:: Other Tasks There are also ``LateTask`` plugins, which are executed later, @@ -379,7 +380,7 @@ They must provide: If the compiler produces something other than HTML files, it should also implement ``extension`` which returns the preferred extension for the output file. -These plugins can also be used to extract metadata from file. To do so, the +These plugins can also be used to extract metadata from a file. To do so, the plugin may implement ``read_metadata`` that will return a dict containing the metadata contained in the file. @@ -388,7 +389,8 @@ RestExtension Plugins Implement directives for reStructuredText, see `media.py <https://github.com/getnikola/nikola/blob/master/nikola/plugins/compile/rest/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: +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 @@ -396,17 +398,18 @@ If your output depends on a config value, you need to make your post record a de 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``. +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 <https://github.com/getnikola/nikola/blob/master/nikola/plugins/compile/markdown/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. +Note that Python markdown extensions are often also available as separate +packages. This is only meant to ship extensions along with Nikola. SignalHandler Plugins --------------------- @@ -444,6 +447,16 @@ Currently Nikola emits the following signals: 'undeployed': # all files not deployed since they are either future posts/drafts } +``compiled`` + When a post/page is compiled from its source to html, before anything else is done with it. The signal + data is in the form:: + + { + 'source': # the path to the source file + 'dest': # the path to the cache file for the post/page + 'post': # the Post object for the post/page + } + One example is the `deploy_hooks plugin. <https://github.com/getnikola/plugins/tree/master/v6/deploy_hooks>`__ ConfigPlugin Plugins @@ -457,7 +470,7 @@ from ``super()``. Example plugin: `navstories <https://github.com/getnikola/plu PostScanner Plugins ------------------- -Get posts and stories from "somewhere" to be added to the timeline. +Get posts and pages from "somewhere" to be added to the timeline. The only currently existing plugin of this kind reads them from disk. @@ -476,7 +489,7 @@ Path/Link Resolution Mechanism Any plugin can register a function using ``Nikola.register_path_handler`` to allow resolution of paths and links. These are useful for templates, which -can access them via _link. +can access them via ``_link``. For example, you can always get a link to the path for the feed of the "foo" tag by using ``_link('tag_rss', 'foo')`` or the ``link://tag_rss/foo`` URL. @@ -492,7 +505,7 @@ Here's the relevant code from the tag plugin. # path elements. def tag_rss_path(self, name, lang): return [_f for _f in [self.site.config['TRANSLATIONS'][lang], - self.site.config['TAG_PATH'], self.slugify_name(name) + ".xml"] if + self.site.config['TAG_PATH'], self.slugify_name(name, lang) + ".xml"] if _f] Template Hooks @@ -528,7 +541,7 @@ HTML: The second argument to ``append()`` is used to determine whether the function -needs access to the current template context and the site. If it it set to +needs access to the current template context and the site. If it is set to ``True``, the function will also receive ``site`` and ``context`` keyword arguments. Example use: @@ -548,3 +561,129 @@ arguments. Example use: endswith=endswith) + t site.template_hooks['page_header'].append(greeting, True, u'Nikola Tesla', endswith=u'!') + +Shortcodes +========== + +Some (hopefully all) markup compilers support shortcodes in these forms:: + + {{% raw %}}{{% foo %}} # No arguments + {{% foo bar %}} # One argument, containing "bar" + {{% foo bar baz=bat %}} # Two arguments, one containing "bar", one called "baz" containing "bat" + + {{% foo %}}Some text{{% /foo %}} # one argument called "data" containing "Some text"{{% /raw %}} + +So, if you are creating a plugin that generates markup, it may be a good idea +to register it as a shortcode in addition of to restructured text directive or +markdown extension, thus making it available to all markup formats. + +To implement your own shortcodes from a plugin, you can create a plugin inheriting ``ShortcodePlugin`` and +from its ``set_site`` method, call + +``Nikola.register_shortcode(name, func)`` with the following arguments: + +``name``: + Name of the shortcode ("foo" in the examples above) +``func``: + A function that will handle the shortcode + +The shortcode handler **must** return a two-element tuple, ``(output, dependencies)`` + +``output``: + The text that will replace the shortcode in the document. + +``dependencies``: + A list of all the files on disk which will make the output be considered + out of date. For example, if the shortcode uses a template, it should be + the path to the template file. + +The shortcode handler **must** accept the following named arguments (or +variable keyword arguments): + +``site``: + An instance of the Nikola class, to access site state + +``data``: + If the shortcut is used as opening/closing tags, it will be the text + between them, otherwise ``None``. + +``lang``: + The current language. + +If the shortcode tag has arguments of the form ``foo=bar`` they will be +passed as named arguments. Everything else will be passed as positional +arguments in the function call. + +So, for example:: + + {{% raw %}}{{% foo bar baz=bat beep %}}Some text{{% /foo %}}{{% /raw %}} + +Assuming you registered ``foo_handler`` as the handler function for the +shortcode named ``foo``, this will result in the following call when the above +shortcode is encountered:: + + foo_handler("bar", "beep", baz="bat", data="Some text", site=whatever) + +Template-based Shortcodes +------------------------- + +Another way to define a new shortcode is to add a template file to the +``shortcodes`` directory of your site. The template file must have the +shortcode name as the basename and the extension ``.tmpl``. For example, if you +want to add a new shortcode named ``foo``, create the template file as +``shortcodes/foo.tmpl``. + +When the shortcode is encountered, the matching template will be rendered with +its context provided by the arguments given in the shortcode. Keyword arguments +are passed directly, i.e. the key becomes the variable name in the template +namespace with a matching string value. Non-keyword arguments are passed as +string values in a tuple named ``_args``. As for normal shortcodes with a +handler function, ``site`` and ``data`` will be added to the keyword arguments. + +Example: + +The following shortcode: + +.. code:: text + + {{% raw %}}{{% foo bar="baz" spam %}}{{% /raw %}} + +With a template in ``shortcodes/foo.tmpl`` with this content (using Jinja2 +syntax in this example) + +.. code:: jinja + + <div class="{{ _args[0] if _args else 'ham' }}">{{ bar }}</div> + +Will result in this output + +.. code:: html + + <div class="spam">baz</div> + + +State and Cache +=============== + +Sometimes your plugins will need to cache things to speed up further actions. Here are the conventions for that: + +* If it's a file, put it somewhere in ``self.site.config['CACHE_FOLDER']`` (defaults to ``cache/``. +* If it's a value, use ``self.site.cache.set(key, value)`` to set it and ``self.site.cache.get(key)`` to get it. + The key should be a string, the value should be json-encodable (so, be careful with datetime objects) + +The values and files you store there can **and will** be deleted sometimes by the user. They should always be +things you can reconstruct without lossage. They are throwaways. + +On the other hand, sometimes you want to save something that is **not** a throwaway. These are things that may +change the output, so the user should not delete them. We call that **state**. To save state: + +* If it's a file, put it somewhere in the working directory. Try not to do that please. +* If it's a value, use ``self.site.state.set(key, value)`` to set it and ``self.state.cache.get(key)`` to get it. + The key should be a string, the value should be json-encodable (so, be careful with datetime objects) + +The ``cache`` and ``state`` objects are rather simplistic, and that's intentional. They have no default values: if +the key is not there, you will get ``None`` and like it. They are meant to be both threadsafe, but hey, who can +guarantee that sort of thing? + +There are no sections, and no access protection, so let's not use it to store passwords and such. Use responsibly. + diff --git a/docs/internals.txt b/docs/internals.txt index 448a6f7..39055e8 100644 --- a/docs/internals.txt +++ b/docs/internals.txt @@ -4,6 +4,7 @@ .. tags: .. link: .. description: +.. author: The Nikola Team Nikola Internals ================ @@ -87,14 +88,14 @@ one of the existing ones. You can do doctests, you can do unit tests, you can do integration tests. There is support for all of them. -Posts and Stories ------------------ +Posts and Pages +--------------- -Nikola has a concept of posts and stories. Both are more or less the same thing, except -posts are added into RSS feeds and stories are not. All of them are in a list called +Nikola has a concept of posts and pages. Both are more or less the same thing, except +posts are added into RSS feeds and pages are not. All of them are in a list called "the timeline" formed by objects of class ``Post``. -When you are creating a task that needs the list of posts and/or stories (for example, +When you are creating a task that needs the list of posts and/or pages (for example, the RSS creation plugin) on task execution time, your plugin should call ``self.site.scan_posts()`` in ``gen_tasks`` to ensure the timeline is created and available in ``self.site.timeline``. You should not modify the timeline, because it will cause consistency issues. diff --git a/docs/man/nikola.1.gz b/docs/man/nikola.1.gz Binary files differindex db17fa8..8aff44e 100644 --- a/docs/man/nikola.1.gz +++ b/docs/man/nikola.1.gz diff --git a/docs/man/nikola.rst b/docs/man/nikola.rst index 633cb33..2d3384a 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.4 +:Version: Nikola 7.8.1 :Manual section: 1 :Manual group: User Commands @@ -92,7 +92,7 @@ The most basic commands needed to get by are: check for dangling links or unknown files ``nikola deploy [[preset [preset...]]`` deploy the site using the ``DEPLOY_COMMANDS`` setting -``nikola github_deploy``` +``nikola github_deploy [-m COMMIT_MESSAGE]``` deploy the site to GitHub Pages ``nikola serve [-p PORT] [-a ADDRESS] [-d|--detach] [-b|--browser] [-6|--ipv6]`` start development web server @@ -100,8 +100,8 @@ The most basic commands needed to get by are: start development web server with automated rebuilds and reloads ``nikola plugin [options]`` manage plugins from the Plugins Index (https://plugins.getnikola.com/) -``nikola install_theme [name]`` - install themes from the Themes Index (https://themes.getnikola.com/) +``nikola theme [options]`` + manage themes from the Themes Index (https://themes.getnikola.com/) Use ``nikola help`` to get a list of all commands. diff --git a/docs/manual.txt b/docs/manual.txt index 09f428a..8b8544b 100644 --- a/docs/manual.txt +++ b/docs/manual.txt @@ -4,11 +4,12 @@ .. link: .. description: .. tags: mathjax +.. author: The Nikola Team The Nikola Handbook =================== -:Version: 7.6.4 +:Version: 7.8.1 .. class:: alert alert-info pull-right @@ -121,7 +122,7 @@ Security A smaller software stack implies less security risk. -Obsolescense +Obsolescence If you create a site using (for example) WordPress, what happens when WordPress releases a new version? You have to update your WordPress. That is not optional, because of security and support issues. If I release a new version of Nikola, and @@ -130,7 +131,7 @@ Obsolescense Also, in the longer term, the very foundations of dynamic sites shift. Can you still deploy a blog software based on Django 0.96? What happens when your - host stops supporting the php version you rely on? And so on. + host stops supporting the PHP version you rely on? And so on. 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. @@ -147,7 +148,7 @@ Cost and Performance On a static site, the highly optimized HTTP server reads the file from disk (or, if it's a popular file, from disk cache), and sends it to the user. You could - probably serve a bazillion (technical term) pageviews from a phone using + probably serve a bazillion (technical term) page views from a phone using static sites. Lock-in @@ -169,6 +170,7 @@ Nikola provides the following features: * Indexes * RSS and Atom feeds * Tags and categories, with pages and feeds + * Author pages and feeds (not generated if ``ENABLE_AUTHOR_PAGES`` is set to ``False`` or there is only one author) * Archives with custom granularity (yearly or monthly) * `Comments`_ * Client-side tag clouds (needs manual configuration) @@ -205,6 +207,15 @@ To set Nikola up and create your first site, read the `Getting Started Guide <ht Creating a Blog Post -------------------- +.. sidebar:: Magic Links + + You will want to do things like "link from one post to another" or "link to an image gallery", + etc. Sure, you can just figure out the URLs for each thing and use that. Or you can use + Nikola's special link URLs. Those are done using the syntax ``link://kind/name`` and + a full list of the included ones is `here <link://slug/path-handlers>`__ (BTW, I linked + to that using ``link://slug/path-handlers``) + + To create a new post, the easiest way is to run ``nikola new_post``. You will be asked for a title for your post, and it will tell you where the post's file is located. @@ -222,9 +233,9 @@ and more via plugins — for more details, read the `input format documentation <#multiple-input-formats>`__. You can learn reStructuredText syntax with the `reST quickstart <https://getnikola.com/quickstart.html>`__. -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. +Please note that Nikola does not support encodings other than UTF-8. Make sure +to convert your input files to that encoding to avoid issues. 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 @@ -256,90 +267,146 @@ The content of that file is as follows: Write your post here. -The ``slug`` is the page name. Since often titles will have -characters that look bad on URLs, it's generated as a "clean" version of the title. -The third line is the post's date, and is set to "now". +You can edit these files with your favorite text editor, and once you are happy +with the contents, generate the pages using ``nikola build``. -The other lines are optional. Tags are comma-separated. The ``link`` is an original -source for the content, and ``description`` is mostly useful for SEO. -``type`` is the post type, whatever you set here (prepended with ``post-``) -will become a CSS class of the ``<article>`` element for this post. Defaults to -``text`` (resulting in a ``post-text`` class) +The post page is generated by default using the ``post.tmpl`` template, which you can use +to customize the output. You can also customize paths and the template filename +itself — see `How does Nikola decide where posts should go?` -You can add your own metadata fields in the same manner, if you use a theme that -supports them (for example: ``.. author: John Doe``) -To add these metadata fields to all new posts by default, you can set the -variable ``ADDITIONAL_METADATA`` in your configuration. For example, you can -add the author metadata to all new posts by default, by adding the following -to your configuration: +Metadata fields +~~~~~~~~~~~~~~~ -.. code:: python +Nikola supports many metadata fields in posts. All of them are +translatable and almost all are optional. The meta field format is: - ADDITIONAL_METADATA = { - 'author': 'John Doe' - } +.. code:: text -.. sidebar:: Other Metadata Fields + .. name: value - Nikola will also use other metadata fields: +You can add your own metadata fields in the same manner. If you are not using +reStructuredText, make sure the fields are in a HTML comment in output. - author - Author of the post, will be used in the RSS feed and possibly in the post - display (theme-dependent) +Basic +````` - annotations / noannotations - Override the value of the ``ANNOTATIONS`` option for this specific post or page. +title + Title of the post. (required) - category - Like tags, except each post can have only one, and they usually have - more descriptive names. +slug + Slug of the post. Used as the last component of the page URL. We recommend + and default to using a restricted character set (``a-z0-9-_``) because + other symbols may cause issues in URLs. (required) - filters - See the `Post Processing Filters`_ section. +date + Date of the post, defaults to now. Multiple date formats are accepted. + Adding a timezone is recommended. (required for posts) - 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). +tags + Comma-separated tags of the post. Some tags have special meaning, including + ``draft``, ``private``, ``mathjax`` - nocomments - Set to "True" to disable comments. Example: +category + Like tags, except each post can have only one, and they usually have + more descriptive names. - .. code:: restructuredtext +link + Link to original source for content. May be displayed by some themes. - .. nocomments: True +description + Description of the post. Used in ``<meta>`` tags for SEO. - password - The post will be encrypted and invisible until the reader enters the password. - Also, the post's sourcecode will not be available. +type + Type of the post. See `Post Types`_ for details. Whatever you set here + (prepended with ``post-``) will become a CSS class of the ``<article>`` + element for this post. Defaults to ``text`` (resulting in a ``post-text`` + class) - 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! +Extra +````` - More information: `Issue #1547 <https://github.com/getnikola/nikola/issues/1547>`_ +author + Author of the post, will be used in the RSS feed and possibly in the post + display (theme-dependent) - 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. +annotations / noannotations + Override the value of the ``ANNOTATIONS`` option for this specific post or page. - .. code:: restructuredtext +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>`__ - .. previewimage: images/looks_great_on_facebook.png +data + Path to an external data file (JSON/YAML/TOML dictionary), relative to ``conf.py``. + Its keys are available for templates as ``post.data('key')``. - 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). + Translated posts can have different values for this field, and the correct one will be + used. - template - 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. + See `The Global Context and Data files`_ for more details. This is + especially useful used in combination with `shortcodes`_. - .. code:: restructuredtext +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). + +hyphenate + Set "True" if you want this document to be hyphenated even if you have + hyphenation disabled by default. + +nocomments + Set to "True" to disable comments. Example: + +password + The post will be encrypted and invisible until the reader enters the password. + Also, the post's source code 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>`_ + +pretty_url + Set to "False" to disable pretty URL for this page. Example: + +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. + + .. code:: restructuredtext + + .. 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). + +section + Section for the post (instead of inferring from output path; requires + ``POSTS_SECTION_FROM_META`` setting) + +template + 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. + + .. code:: restructuredtext - .. template: story.tmpl + .. template: story.tmpl + +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: + +.. code:: python + + ADDITIONAL_METADATA = { + 'author': 'John Doe' + } - 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 @@ -367,6 +434,9 @@ to your configuration: Both file formats are supported; however, the new format is preferred, if possible. +Multilingual posts +~~~~~~~~~~~~~~~~~~ + If you are writing a multilingual site, you can also create a per-language post file (for example: ``how-to-make-money.es.txt`` with the default TRANSLATIONS_PATTERN, see below). This one can replace metadata of the default language, for example: @@ -391,28 +461,28 @@ default set to: Nikola will only look for translation of input files for languages specified in the TRANSLATIONS variable. -You can edit these files with your favourite text editor, and once you are happy -with the contents, generate the pages using ``nikola build``. - -Nikola supports multiple languages for a post (we have almost 40 translations!). If you wish to +Nikola supports multiple languages for a post (we have almost 50 translations!). If you wish to add support for more languages, check out `the Transifex page for Nikola <https://www.transifex.com/projects/p/nikola/>`_ -The post page is generated using the ``post.tmpl`` template, which you can use -to customize the output. +How does Nikola decide where posts should go? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The place where the post will be placed by ``new_post`` is based on the ``POSTS`` -and ``PAGES`` configuration options: +The place where the post will be placed by ``new_post`` (the first one that +matches the given format) and the final post destination (the first one that +matches a given file) is based on the ``POSTS`` and ``PAGES`` configuration +options. The exact mechanism is explained above the config options in the +``conf.py`` file, and also reproduced below: .. code:: python # POSTS and PAGES contains (wildcard, destination, template) tuples. # - # The wildcard is used to generate a list of reSt source files - # (whatever/thing.txt). + # The wildcard is used to generate a list of post source files + # (whatever/thing.rst, for example). # # That fragment could have an associated metadata file (whatever/thing.meta), # and optionally translated files (example for Spanish, with code "es"): - # whatever/thing.es.txt and whatever/thing.es.meta + # whatever/thing.es.rst and whatever/thing.es.meta # # This assumes you use the default TRANSLATIONS_PATTERN. # @@ -421,24 +491,39 @@ and ``PAGES`` configuration options: # # These files are combined with the template to produce rendered # pages, which will be placed at - # output / TRANSLATIONS[lang] / destination / pagename.html + # output/TRANSLATIONS[lang]/destination/pagename.html # # where "pagename" is the "slug" specified in the metadata file. + # The page might also be placed in /destination/pagename/index.html + # if PRETTY_URLS are enabled. # # The difference between POSTS and PAGES is that POSTS are added - # to feeds and are considered part of a blog, while PAGES are - # just independent HTML pages. + # to feeds, indexes, tag lists and archives and are considered part + # of a blog, while PAGES are just independent HTML pages. # POSTS = ( - ("posts/*.txt", "posts", "post.tmpl"), ("posts/*.rst", "posts", "post.tmpl"), + ("posts/*.txt", "posts", "post.tmpl"), + ("posts/*.html", "posts", "post.tmpl"), ) PAGES = ( - ("stories/*.txt", "stories", "story.tmpl"), - ("stories/*.rst", "stories", "story.tmpl"), + ("pages/*.rst", "pages", "story.tmpl"), + ("pages/*.txt", "pages", "story.tmpl"), + ("pages/*.html", "pages", "story.tmpl"), ) +.. note:: POSTS and PAGES are not flat! + + Even if the syntax may suggest you can't, you can create any directory structure you want + inside ``posts/`` or ``pages/`` and it will be reflected in the output. For example, + ``posts/foo/bar.txt`` would produce ``output/posts/foo/bar.html``, assuming the slug is also ``bar``. + + If you have ``PRETTY_URLS`` enabled, that would be ``output/posts/foo/bar/index.html``. + +The ``new_post`` command +~~~~~~~~~~~~~~~~~~~~~~~~ + ``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 @@ -465,7 +550,7 @@ The ``new_post`` command supports some options: -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. +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 "foo" as its slug. @@ -491,9 +576,9 @@ In Markdown (or basically, the resulting HTML of any format): By default all your RSS feeds will be shortened (they'll contain only teasers) whereas your index page will still show complete posts. You can change -this behaviour with your ``conf.py``: ``INDEX_TEASERS`` defines whether index -page should display the whole contents or only teasers. ``RSS_TEASERS`` -works the same way for your RSS feeds. +this behavior with your ``conf.py``: ``INDEX_TEASERS`` defines whether index +page should display the whole contents or only teasers. ``FEED_TEASERS`` +works the same way for your Atom and 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: @@ -506,7 +591,7 @@ 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 +.. code:: python import re TEASER_REGEXP = re.compile('<!--\s*(more|TEASER_END)(:(.+))?\s*-->', re.IGNORECASE) @@ -523,7 +608,6 @@ Or you can completely customize the link using the ``READ_MORE_LINK`` option. # }} A literal } (U+007D RIGHT CURLY BRACKET) # READ_MORE_LINK = '<p class="more"><a href="{link}">{read_more}…</a></p>' - Drafts ~~~~~~ @@ -571,6 +655,9 @@ Monday, Wednesday and Friday at 7am, add the following For more details on how to specify a recurrence rule, look at the `iCal specification <http://www.kanzaki.com/docs/ical/rrule.html>`_. +Or if you are scared of this format, many calendaring applications (eg. Google +Calendar) offer iCal exports, so you can copy-paste the repeat rule from a +generated iCal (``.ics``) file (which is a human-readable text file). 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 @@ -635,6 +722,9 @@ 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. +Something similar happens with authors. To use full indexes in authors, set +``AUTHOR_PAGES_ARE_INDEXES`` to ``True``. + Static indexes `````````````` @@ -654,6 +744,77 @@ 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). + +Post taxonomy +~~~~~~~~~~~~~ + +There are three taxonomy systems in Nikola, or three ways to organize posts. Those are: + +* tags +* categories +* sections + +Tags and categories are visible on the *Tags and Categories* page, by default available at ``/categories/``. Each tag/category/section has an index page and feeds. + +Tags +```` + +Tags are the smallest and most basic of the taxonomy items. A post can have multiple tags, specified using the ``tags`` metadata entry (comma-separated). You should provide many tags to help your readers, and perhaps search engines, find content on your site. + +Please note that tags are case-sensitive and that you cannot have two tags that differ only in case/punctuation (eg. using ``nikola`` in one post and ``Nikola`` in another will lead to a crash): + +.. code:: text + + ERROR: Nikola: You have tags that are too similar: Nikola and nikola + ERROR: Nikola: Tag Nikola is used in: posts/second-post.rst + ERROR: Nikola: Tag nikola is used in: posts/1.rst + +Nikola uses some tags to mark a post as “special” — those are ``draft``, ``private``, ``mathjax`` (for math support). + +You can also generate a tag cloud with the `tx3_tag_cloud <https://plugins.getnikola.com/#tx3_tag_cloud>`_ plugin. + +Categories +`````````` + +The next unit for organizing your content are categories. A post can have only one category, specified with the ``category`` meta tag. Those are *deprecated* and replaced by sections. They are displayed alongside tags. You can have categories and tags with the same name (categories’ RSS and HTML files are prefixed with ``cat_`` by default). + +Sections +```````` + +Sections are the newest feature for taxonomy, and are not supported in themes by default. There are two ways to assign a section to a post: + +* through the directory structure (first directory is the section name, eg. ``/code/my-project/`` is in the `code` category) — your POSTS should have those directories as the second element, eg. + + .. code:: python + + POSTS = ( + ('posts/code/*.rst', 'code', 'posts'), + ) + +* through the ``section`` meta field (requires ``POSTS_SECTION_FROM_META`` setting; recommended especially for existing sites which should not change the directory hierarchy) + +Sections are meant to be used to organize different parts of your blog, parts that are about different topics. Unlike tags, which you should have tens (hundreds?) of, you should ideally have less than 10 sections (though it depends on what your blog needs; there is no hard limit). + +With sections, you can also use some custom styling — if you install ``husl``, you can use ``post.section_color()`` from within templates to get a distinct color for the section of a post, which you can then use in some inline CSS for the section name. + +You can find some examples and more information in the `original announcement +<https://getnikola.com/blog/new-feature-in-nikola-sections.html>`_ + +Configuring tags, categories and sections +````````````````````````````````````````` + +There are multiple configuration variables dedicated to each of the three taxonomies. You can set: + +* ``TAG_PATH``, ``TAGS_INDEX_PATH``, ``CATEGORY_PATH``, ``CATEGORY_PREFIX`` to configure paths used for tags and categories +* ``POST_SECTION_NAME``, ``POST_SECTION_TITLE`, `TAG_PAGES_TITLES``, ``CATEGORY_PAGES_TITLES`` to set friendly section names and titles for index pages +* ``POST_SECTION_DESCRIPTIONS``, `TAG_PAGES_DESCRIPTIONS``, ``CATEGORY_PAGES_DESCRIPTIONS`` to set descriptions for each of the items +* ``POST_SECTION_COLORS`` to customize colors for each section +* ``CATEGORY_ALLOW_HIERARCHIES`` and ``CATEGORY_OUTPUT_FLAT_HIERARCHIES`` to allow hierarchical categories +* ``TAG_PAGES_ARE_INDEXES`` and ``CATEGORY_PAGES_ARE_INDEXES`` to display full-size indexes instead of simple post lists +* ``WRITE_TAG_CLOUDS`` to enable/disable generating tag cloud files +* ``HIDDEN_TAGS``. ``HIDDEN_CATEGORIES`` to make some tags/categories invisible in lists +* ``POSTS_SECTION_FROM_META`` to use ``.. section:`` in posts instead of inferring paths from paths + Creating a Page --------------- @@ -664,12 +825,16 @@ Pages are the same as posts, except that: * They use the ``story.tmpl`` template instead of ``post.tmpl`` by default The default configuration expects the page's metadata and text files to be on the -``stories`` folder, but that can be changed (see ``PAGES`` option above). +``pages`` 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. +In some places (including default directories and templates), pages are called +*stories* for historic reasons. Both are synonyms for the same thing: pages +that are not blog posts. + Supported input formats ----------------------- @@ -732,6 +897,9 @@ config option: MARKDOWN_EXTENSIONS = ['fenced_code', 'codehilite', 'extra'] +Nikola comes with some Markdown Extensions built-in and enabled by default, +namely a gist directive, a podcast directive, and ``~~strikethrough~~`` support. + IPython Notebook/Jupyter ```````````````````````` @@ -771,6 +939,168 @@ 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. +Shortcodes +---------- + +This feature is "inspired" (copied wholesale) from `Hugo <https://gohugo.io/extras/shortcodes/>`__ so I will +steal part of their docs too. + +A shortcode is a simple snippet inside a content file that Nikola will render using a predefined template or +custom code from a plugin. + +To use them from plugins, please see `Extending Nikola <https://getnikola.com/extending.html#shortcodes>`__ + +Using a shortcode +~~~~~~~~~~~~~~~~~ + +In your content files, a shortcode can be called by using this form:: + + {{% raw %}}{{% name parameters %}}{{% /raw %}} + +Shortcode parameters are space delimited. Parameters with spaces can be quoted (or backslash escaped). + +The first word is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional or both. The format for named parameters models that of HTML with the format name="value". + +Some shortcodes use or require closing shortcodes. Like HTML, the opening and closing shortcodes match (name only), the closing being prepended with a slash. + +Example of a paired shortcode (note that we don't have a highlight shortcode yet ;-):: + + {{% raw %}}{{% highlight python %}} A bunch of code here {{% /highlight %}}{{% /raw %}} + +.. note:: Shortcodes and reStructuredText + + In reStructuredText shortcodes may fail because docutils turns URL into links and everything breaks. + For some shortcodes there are alternative docutils directives (example, you can use the media + **directive** instead of the media shortcode. + + Also, you can use the shortcode **role**:: + + :sc:`{{% raw %}}{{% shortcode here %}}{{% /raw %}}` + + That role passes text unaltered, so shortcodes behave correctly. + + +Built-in shortcodes +~~~~~~~~~~~~~~~~~~~ + +doc + Will link to a document in the page, see `Doc directive for details + <#doc>`__. Example: + + .. code:: restructuredtext + + {{% raw %}}Take a look at {{% doc %}}my other post <creating-a-theme>{{% /doc %}} about theme creating.{{% /raw %}} + +post-list + Will show a list of posts, see the `Post List directive for details <#post-list>`__ + +media + Display media embedded from a URL, for example, this will embed a youtube video:: + + {{% raw %}}{{% media url="https://www.youtube.com/watch?v=Nck6BZga7TQ" %}}{{% /raw %}} + + +chart + Create charts via PyGal. This is similar to the `chart directive <#chart>`__ except the syntax is adapted to + shortcodes. This is an example:: + + {{% raw %}}{{% chart Bar title='Browser usage evolution (in %)' %}} + x_labels='["2002","2003","2004","2005","2006","2007","2008","2009","2010","2011","2012"]'%}} + 'Firefox', [None, None, 0, 16.6, 25, 31] + 'Chrome', [None, None, None, None, None, None] + 'IE', [85.8, 84.6, 84.7, 74.5, 66, 58.6] + 'Others', [14.2, 15.4, 15.3, 8.9, 9, 10.4] + {{% /chart %}}{{% /raw %}} + +gist + Show GitHub gists. If you know the gist's ID, this will show it in your site: + + {{% raw %}}{{% gist 2395294 %}} {{% /raw %}} + + +raw + Passes the content along, mostly used so I can write this damn section and you can see the shortcodes instead + of them being munged into shortcode **output**. I can't show an example because Inception. + + +Community shortcodes +~~~~~~~~~~~~~~~~~~~~ + +Shortcodes created by the community are available in `the shortcodes repository on GitHub <https://github.com/getnikola/shortcodes>`_. + +Template-based shortcodes +~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you put a template in ``shortcodes/`` called ``mycode.tmpl`` then Nikola +will create a shortcode called ``mycode`` you can use. Any options you pass to +the shortcode will be available as variables for that template. Non-keyword +options will be passed in a tuple variable named ``_args``. + +The post in which the shortcode is being used is available as the ``post`` +variable, so you can access the title as ``post.title``, and data loaded +via the ``data`` field in the metadata using ``post.data(key)``. + +If you use the shortcode as paired, then the contents between the paired tags +will be available in the ``data`` variable. If you want to access the Nikola +object, it will be available as ``site``. Use with care :-) + +See :doc:`extending` for detailed information. + +For example, if your ``shortcodes/foo.tmpl`` contains this:: + + This uses the bar variable: ${bar} + +And your post contains this:: + + {{% raw %}}{{% foo bar=bla %}}{{% /raw %}} + +Then the output file will contain:: + + This uses the bar variable: bla + +Finally, you can use a template shortcode without a file, by inserting the template in the shortcode itself:: + + {{% raw %}} + {{% template %}} + % for foo in bar: + <li> ${foo} + % endfor + {{% /template %}} + {{% /raw %}} + +In that case, the template engine used will be your theme's and the arguments you pass, +as well as the global context from your ``conf.py``, are available to the template you +are creating. + +The Global Context and Data files +--------------------------------- + +There is a ``GLOBAL_CONTEXT`` field in your ``conf.py`` where you can +put things you want to make available to your templates. + +It will also contain things you put in a ``data/`` directory within your +site. You can use JSON, YAML or TOML files (with the appropriate file +extensions: json/js, yaml/yml, toml/tml) that decode to Python dictionaries. +For example, if you create ``data/foo.json`` containing this: + +.. code:: json + + {"bar": "baz"} + +Then your templates can use things like ``${data['foo']['bar']}`` and +it will be replaced by "baz". + +Individual posts can also have a data file. Those are specified using the +``data`` meta field (path relative to ``conf.py``, can be different in +different languages). Those are accessible as eg. +``${post.meta('data')['bar']`` in templates. `Template-based shortcodes`_ are a +good idea in this case. + +Data files can be useful for eg. auto-generated sites, where users provide +JSON/YAML/TOML files and Nikola generates a large page with data from all data +files. (This is especially useful with some automatic rebuild feature, like +those documented in `Deployment`_) + Redirections ------------ @@ -813,7 +1143,7 @@ You surely want to edit these options: BLOG_EMAIL = "joe@demo.site" BLOG_DESCRIPTION = "This is a demo site for Nikola." # (translatable) -Some options are demarked with a (translatable) comment above or right next to +Some options are marked 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 @@ -849,11 +1179,10 @@ CSS tweaking .. _LESS: http://lesscss.org/ .. _Sass: http://sass-lang.com/ -Template tweaking +Template tweaking and creating themes If you really want to change the pages radically, you will want to do a `custom theme <theming.html>`__. - Navigation Links The ``NAVIGATION_LINKS`` option lets you define what links go in a sidebar or menu (depending on your theme) so you can link to important pages, or to other sites. @@ -889,7 +1218,7 @@ Navigation Links 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. + with ``/index.html`` — or else they won’t be highlighted 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 @@ -990,17 +1319,28 @@ change the FILES_FOLDERS option: # FILES_FOLDERS = {'files': '' } # Which means copy 'files' into 'output' -Getting More Themes -------------------- +Custom Themes +------------- + +If you prefer to have a custom appearance for your site, and modifying CSS +files and settings (see `Customizing Your Site`_ for details) is not enough, +you can create your own theme. See the :doc:`theming` and +:doc:`creating-a-theme` for more details. You can put them in a ``themes/`` +folder and set ``THEME`` to the directory name. You can also put them in +directories listed in the ``EXTRA_THEMES_DIRS`` configuration variable. + +Getting Extra Themes +-------------------- There are a few themes for Nikola. They are available at 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 has a built-in theme download/install mechanism to install those themes +— the ``theme`` command: .. code:: console - $ nikola install_theme -l + $ nikola theme -l Themes: ------- blogtxt @@ -1008,10 +1348,10 @@ 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: + $ nikola theme -i blogtxt + [2013-10-12T16:46:13Z] NOTICE: theme: Downloading: https://themes.getnikola.com/v6/blogtxt.zip - [2013-10-12T16:46:15Z] NOTICE: install_theme: Extracting: blogtxt into themes + [2013-10-12T16:46:15Z] NOTICE: theme: Extracting: blogtxt into themes And there you are, you now have themes/blogtxt installed. It's very rudimentary, but it should work in most cases. @@ -1026,13 +1366,13 @@ to create a custom theme by downloading free CSS files from http://bootswatch.co .. code:: console - $ nikola bootswatch_theme -n custom_theme -s spruce -p bootstrap3 + $ nikola bootswatch_theme -n custom_theme -s flatly -p bootstrap3 [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Creating 'custom_theme' theme - from 'spruce' and 'bootstrap3' + from 'flatly' and 'bootstrap3' [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Downloading: - http://bootswatch.com//spruce/bootstrap.min.css + http://bootswatch.com//flatly/bootstrap.min.css [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Downloading: - http://bootswatch.com//spruce/bootstrap.css + http://bootswatch.com//flatly/bootstrap.css [2013-10-12T16:46:59Z] NOTICE: bootswatch_theme: Theme created. Change the THEME setting to "custom_theme" to use it. You can even try what different swatches do on an existing site using @@ -1044,9 +1384,8 @@ Play with it, there's cool stuff there. This feature was suggested by Deployment ---------- -Nikola doesn't really have a concept of deployment. However, if you can specify your -deployment procedure as a series of commands, you can put them in the ``DEPLOY_COMMANDS`` -option, and run them with ``nikola deploy``. +If you can specify your 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 @@ -1073,25 +1412,68 @@ 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 +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 -user.github.io/organization.github.io, this MUST be set to ``master``, -and the branch containing the sources must be changed to something -else, like ``deploy``, using the ``GITHUB_SOURCE_BRANCH`` option. The -remote name to which the changes are pushed is ``origin`` by default, -and can be changed using the ``GITHUB_REMOTE_NAME`` option. You also, -obviously, need to have ``git`` on your PATH, and should be able to -push to the repository specified as the remote. +In order to use this feature, you need to configure a few things first. Make +sure you have ``nikola`` and ``git`` installed on your PATH. + +1. Initialize a Nikola site, if you haven’t already. +2. Initialize a git repository in your Nikola source directory by running: + + .. code:: text + + git init . + git remote add origin git@github.com:user/repository.git + +3. Setup branches and remotes in ``conf.py``: + + * ``GITHUB_DEPLOY_BRANCH`` is the branch where Nikola-generated HTML files + will be deployed. It should be ``gh-pages`` for project pages and + ``master`` for user pages (user.github.io). + * ``GITHUB_SOURCE_BRANCH`` is the branch where your Nikola site source will be + deployed. We default to ``master``, but user pages should use ``src`` or + something else. + * ``GITHUB_REMOTE_NAME`` is the remote to which changes are pushed. + * ``GITHUB_COMMIT_SOURCE`` controls whether or not the source branch is + automatically committed to and pushed. We recommend setting it to + ``True``. + +4. Create a ``.gitignore`` file. We recommend adding at least the following entries: -This command performs the following actions, when it is run: + .. code:: text -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``! + cache + .doit.db + __pycache__ + output + +5. If you set ``GITHUB_COMMIT_SOURCE`` to False, you must switch to your source + branch and commit to it. Otherwise, this is done for you. +6. Run ``nikola github_deploy``. This will build the site, commit the output + folder to your deploy branch, and push to GitHub. Your website should be up + and running within a few minutes. + +If you want to use a custom domain, create your ``CNAME`` file in +``files/CNAME`` on the source branch. Nikola will copy it to the +output directory. To add a custom commit message, use the ``-m`` option, +followed by your message. + +Automated rebuilds with Travis CI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want automated rebuilds and GitHub Pages deployment, allowing you to +blog from anywhere in the world, follow this guide: +`Automating Nikola rebuilds with Travis CI +<https://getnikola.com/blog/automating-nikola-rebuilds-with-travis-ci.html>`_. + +Automated rebuilds with GitLab +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +GitLab also offers rebuild automation if you want to use Nikola with GitLab +Pages. Check out the example `Nikola site on GitLab +<https://gitlab.com/pages/nikola>`_. Comments and Annotations ------------------------ @@ -1122,10 +1504,9 @@ to one of "disqus", "intensedebate", "livefyre", "moot", "googleplus", * In IntenseDebate it's the **IntenseDebate site acct** * In LiveFyre it's the **siteId** * In Moot it's your **username** - * For Google Plus, ``COMMENT_SYSTEM_ID`` need not be set, but you must - `verify your authorship <https://plus.google.com/authorship>`_ + * For Google Plus, ``COMMENT_SYSTEM_ID`` need not be set. WARNING: this will not work correctly in the test server, needs to be deployed to a real server/URL. * For Facebook, you need to `create an app - <https://developers.facebook.com/apps>` (turn off sandbox mode!) + <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, encoded with Punycode (if using Internationalized Domain Names) and **have a trailing slash**, @@ -1183,7 +1564,7 @@ if you want feedback on specific parts of your writing. You can enable or disable annotations for specific posts or pages using the ``annotations`` and ``noannotations`` metadata. -Annotations require JQuery and are therefore not supported in the base theme. +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. @@ -1196,7 +1577,9 @@ and put images there. Nikola will take care of creating thumbnails, index page, 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. +``.islink`` class to your image or link. (The behavior is caused by +``<a class="image-reference">`` if you need to use it outside of galleries and reST +thumbnails.) 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 @@ -1227,16 +1610,19 @@ The ``conf.py`` options affecting images and gallery pages are these: # 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}. - + # Folders containing images to be used in normal posts or pages. + # IMAGE_FOLDERS is a dictionary of the form {"source": "destination"}, + # where "source" is the folder containing the images to be published, and + # "destination" is the folder under OUTPUT_PATH containing the images copied + # to the site. Thumbnail images will be created there as well. IMAGE_FOLDERS = {'images': 'images'} + + # 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). IMAGE_THUMBNAIL_SIZE = 400 -If you add a file in ``galleries/gallery_name/index.txt`` its contents will be +If you add a reST 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. @@ -1250,6 +1636,107 @@ be stripped. For example ``03_an_amazing_sunrise.jpg`` will be render as *An ama Here is a `demo gallery </galleries/demo>`_ of historic, public domain Nikola Tesla pictures taken from `this site <http://kerryr.net/pioneers/gallery/tesla.htm>`_. +Embedding Images +~~~~~~~~~~~~~~~~ + +Assuming that you have your pictures stored in a folder called ``images`` (as configured above), +you can embed the same in your posts with the following reST directive: + +.. code:: rest + + ..image:: /images/tesla.jpg + +Which is equivalent to the following HTML code: + +.. code:: html + + <img src="/images/tesla.jpg"> + +Please take note of the leading forward-slash ``/`` which refers to the root +output directory. (Make sure to use this even if you’re not deploying to +web server root.) + +You can also use thumbnails with the ``.. thumbnail::`` reST directive. For +more details, and equivalent HTML code, see `Thumbnails`_. + +Handling EXIF Data +------------------ + +Your images contain a certain amount of extra data besides the image itself, +called the `EXIF metadata. <https://en.wikipedia.org/wiki/Exchangeable_image_file_format>`__ +It contains information about the camera you used to take the picture, when it was taken, +and maybe even the location where it was taken. + +This is both useful, because you can use it in some apps to locate all the pictures taken +in a certain place, or with a certain camera, but also, since the pictures Nikola +publishes are visible to anyone on the Internet, a privacy risk worth considering +(Imagine if you post pictures taken at home with GPS info, you are publishing your +home address!) + +Nikola has some support for managing it, so let's go through a few scenarios to +see which one you prefer. + +Strip all EXIF data +~~~~~~~~~~~~~~~~~~~ + +Do this if you want to be absolutely sure that no sensitive information should ever leak:: + + PRESERVE_EXIF_DATA = False + EXIF_WHITELIST = {} + +Preserve all EXIF data +~~~~~~~~~~~~~~~~~~~~~~ + +Do this if you really don't mind people knowing where pictures were taken, or camera settings. + + PRESERVE_EXIF_DATA = True + EXIF_WHITELIST = {'*': '*'} + +Preserve some EXIF data +~~~~~~~~~~~~~~~~~~~~~~~ + +Do this if you really know what you are doing. EXIF data comes separated in a few IFD blocks. +The most common ones are: + +0th + Information about the image itself + +Exif + Information about the camera and the image + +1st + Information about embedded thumbnails (usually nothing) + +thumbnail + An embedded thumbnail, in JPEG format (usually nothing) + +GPS + Geolocation information about the image + +Interop + Not too interesting at this point. + +Each IFD in turn contains a number of tags. For example, 0th contains a ImageWidth tag. +You can tell Nikola exactly which IFDs to keep, and within each IFD, which tags to keep, +using the EXIF_WHITELIST option. + +Let's see an example:: + + PRESERVE_EXIF_DATA = True + EXIF_WHITELIST = { + "0th": ["Orientation", "ImageWidth", "ImageLength"], + "Interop": "*", + } + +So, we preserve EXIF data, and the whitelisted IFDs are "0th" and "Interop". That means +GPS, for example, will be totally deleted. + +Then, for the Interop IFD, we keep everything, and for the 0th IFD we only keep three tags, +listed there. + +There is a huge number of EXIF tags, described in `the standard <http://www.cipa.jp/std/documents/e/DC-008-2012_E.pdf>`__ + + Post Processing Filters ----------------------- @@ -1279,13 +1766,14 @@ The currently available filters are: .. sidebar:: Creating your own filters You can use any program name that works in place as a filter, like ``sed -i`` - and you can use arbitrary python functions as filters, too. + and you can use arbitrary Python functions as filters, too. - If your program doesn't run in-place, then you can use Nikola's runinplace function. + If your program doesn't run in-place, then you can use Nikola's ``runinplace`` function (from the ``filters`` module). For example, this is how the yui_compressor filter is implemented: .. code-block:: python + from nikola.filters import runinplace def yui_compressor(infile): return runinplace(r'yui-compressor --nomunge %1 -o %2', infile) @@ -1334,6 +1822,10 @@ typogrify_sans_widont minify_lines **THIS FILTER HAS BEEN TURNED INTO A NOOP** and currently does nothing. +normalize_html + Pass HTML through LXML to normalize it. For example, it will resolve ``"`` to actual + quotes. Usually not needed. + yui_compressor Compress CSS/JavaScript using `YUI compressor <http://yui.github.io/yuicompressor/>`_ @@ -1346,6 +1838,17 @@ optipng jpegoptim Compress JPEG files using `jpegoptim <http://www.kokkonen.net/tjko/projects.html>`_ +cssminify + Minify CSS using http://cssminifier.com/ (requires Internet access) + +jsminify + Minify JS using http://javascript-minifier.com/ (requires Internet access) + +jsonminify + Minify JSON files (strip whitespace and use minimal separators). + +xmlminify + Minify XML files. Suitable for Nikola’s sitemaps and Atom feeds. You can apply filters to specific posts or pages by using the ``filters`` metadata field: @@ -1353,8 +1856,6 @@ You can apply filters to specific posts or pages by using the ``filters`` metada .. filters: filters.html_tidy_nowrap, "sed s/foo/bar" - - Optimizing Your Website ----------------------- @@ -1362,38 +1863,40 @@ One of the main goals of Nikola is to make your site fast and light. So here are tips we have found when setting up Nikola with Apache. If you have more, or 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 +1. 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: +2. 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: +3. If even after you did the previous step the CSS files are not sent compressed: .. code:: apache AddType text/css .css -#. Optionally you can create static compressed copies and save some CPU on your server +4. 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. +5. The webassets Nikola plugin can drastically decrease the number of CSS and JS files your site fetches. -#. Through the filters feature, you can run your files through arbitrary commands, so that images +6. Through the filters feature, you can run your files through arbitrary commands, so that images are recompressed, JavaScript is minimized, etc. -#. The USE_CDN option offloads standard JavaScript and CSS files to a CDN so they are not +7. The USE_CDN option offloads standard JavaScript and CSS files to a CDN so they are not downloaded from your server. 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. +directives of reStructuredText and the usual LaTeX delimiters +(backslash-parentheses, backslash-brackets) for other input formats. + +To use mathematics in a post, you must add the ``mathjax`` tag. We **DO NOT** support the old, deprecated and error-prone ``$inline$`` delimiters by default. If you want to use them, please add them manually, @@ -1417,7 +1920,8 @@ like this: </script> """ -Inline mathematics are produced using the reST `math` **role** or the ``\(…\)`` delimiters: +Inline mathematics are produced using the reST `math` **role** or the LaTeX +backslash-parentheses delimiters: Euler’s formula: :math:`e^{ix} = \cos x + i\sin x` @@ -1427,13 +1931,18 @@ In reST: Euler’s formula: :math:`e^{ix} = \cos x + i\sin x` -In other input formats: +In HTML and other input formats: .. code:: text Euler’s formula: \(e^{ix} = \cos x + i\sin x\) -Display mathematics are produced using the reST `math` **directive** or the ``\[…\]`` delimiters: +Note that some input formats (including Markdown) require using **double +backslashes** in the delimiters (``\\(inline math\\)``). Please check your +output first before reporting bugs. + +Display mathematics are produced using the reST `math` **directive** or the +LaTeX backslash-brackets delimiters: .. math:: @@ -1448,12 +1957,17 @@ In reST: \int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C -In other input formats: +In HTML and other input formats: .. code:: text \[\int \frac{dx}{1+ax}=\frac{1}{a}\ln(1+ax)+C\] +Note that some input formats (including Markdown) require using **double +backslashes** in the delimiters (``\\[display math\\]``). Please check your +output first before reporting bugs. + + reStructuredText Extensions --------------------------- @@ -1494,6 +2008,14 @@ Once you have that, all you need to do is: .. youtube:: 8N_tupPBtWQ +Supported options: ``height``, ``width``, ``align`` (one of ``left``, +``center``, ``right``) — all are optional. Example: + +.. code:: restructuredtext + + .. youtube:: 8N_tupPBtWQ + :align: center + Vimeo ~~~~~ @@ -1516,6 +2038,9 @@ You can override this if you wish: :height: 240 :width: 320 +Supported options: ``height``, ``width``, ``align`` (one of ``left``, +``center``, ``right``) — all are optional. + Soundcloud ~~~~~~~~~~ @@ -1537,6 +2062,9 @@ You can also embed playlists, via the `soundcloud_playlist` directive which work .. soundcloud_playlist:: 9411706 +Supported options: ``height``, ``width``, ``align`` (one of ``left``, +``center``, ``right``) — all are optional. + Code ~~~~ @@ -1610,9 +2138,7 @@ To include an image placed in the ``images`` folder (or other folders defined in .. code:: restructuredtext - .. thumbnail:: ../tesla.jpg - -(make sure to check the file paths!) + .. thumbnail:: /images/tesla.jpg The small thumbnail will be placed in the page, and it will be linked to the bigger version of the image when clicked, using @@ -1625,10 +2151,17 @@ directive instead: .. code:: restructuredtext - .. thumbnail:: ../tesla.jpg + .. thumbnail:: /images/tesla.jpg Nikola Tesla, the man that invented the 20th century. +If you want to include a thumbnail in a non-reST post, you need to produce at +least this basic HTML: + +.. code:: html + + <a class="image-reference" href="images/tesla.jpg"><img src="images/tesla.thumbnail.jpg"></a> + Slideshows ~~~~~~~~~~ @@ -1727,6 +2260,13 @@ with the tag ``nikola``: .. post-list:: :tags: nikola +Using shortcode syntax (for other compilers): + +.. code:: text + + {{% raw %}}{{% post-list stop=5 %}}{{% /post-list %}}{{% /raw %}} + + The following options are recognized: * ``start`` : integer @@ -1749,6 +2289,15 @@ The following options are recognized: Sort post list by one of each post's attributes, usually ``title`` or a custom ``priority``. Defaults to None (chronological sorting). +* ``date``: string + Show posts that match date range specified by this option. Format: + + * comma-separated clauses (AND) + * clause: attribute comparison_operator value (spaces optional) + * attribute: year, month, day, hour, month, second, weekday, isoweekday; or empty for full datetime + * comparison_operator: == != <= >= < > + * value: integer or dateutil-compatible date input + * ``tags`` : string [, string...] Filter posts to show only posts having at least one of the ``tags``. Defaults to None. @@ -1757,13 +2306,21 @@ The following options are recognized: Filter posts to show only posts having one of the ``categories``. Defaults to None. +* ``sections`` : string [, string...] + Filter posts to show only posts having one of the ``sections``. + Defaults to None. + * ``slugs`` : string [, string...] Filter posts to show only posts having at least one of the ``slugs``. Defaults to None. +* ``post_type`` (or ``type``) : string + Show only ``posts``, ``pages`` or ``all``. + Replaces ``all``. Defaults to ``posts``. + * ``all`` : flag - Shows all posts and pages in the post list. - Defaults to show only posts with set *use_in_feeds*. + (deprecated, use ``post_type`` instead) + Shows all posts and pages in the post list. Defaults to show only posts. * ``lang`` : string The language of post *titles* and *links*. @@ -1785,9 +2342,12 @@ 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 +We recommend using pages with dates in the past (1970-01-01) to avoid dependency issues. +If you are using this as a shortcode, flags (``reverse``, ``all``) are meant to be used +with a ``True`` argument, eg. ``all=True``. + Importing your WordPress site into Nikola ----------------------------------------- @@ -1881,7 +2441,7 @@ 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. +to your content. Nikola supports `Twitter Cards <https://dev.twitter.com/docs/cards>`_. They are implemented to use *Open Graph* tags whenever possible. @@ -2019,7 +2579,12 @@ Nikola is released under the `MIT license <https://getnikola.com/license.html>`_ components shipped along with Nikola, or required by it are released under other licenses. -If you are not familiar with free software licensing: In general, you should be able to -do pretty much anything you want, unless you modify Nikola. If you modify it, and share -it with someone else, that someone else should get all your modifications under the same -license you got it. +If you are not familiar with free software licensing, here is a brief +explanation (this is NOT legal advice): In general, you can do pretty much +anything you want — including modifying Nikola, using and redistributing the +original version or the your modified version. However, if you redistribute +Nikola to someone else, either a modified version or the original version, the +full copyright notice and license text must be included in your distribution. +Nikola is provided “as is”, and the Nikola contributors are not liable for any +damage caused by the software. Read the `full license text +<https://getnikola.com/license.html>`_ for details. diff --git a/docs/path_handlers.txt b/docs/path_handlers.txt new file mode 100644 index 0000000..2a03d77 --- /dev/null +++ b/docs/path_handlers.txt @@ -0,0 +1,261 @@ +.. title: Path Handlers for Nikola +.. slug: path-handlers +.. author: The Nikola Team + +Nikola supports special links with the syntax ``link://kind/name``. In the templates you can also +use ``_link(kind, name)`` Here is the description for all the supported kinds. + +.. class:: dl-horizontal + +archive + Link to archive path, name is the year. + + Example: + + link://archive/2013 => /archives/2013/index.html + + +archive_atom + Link to atom archive path, name is the year. + + Example: + + link://archive_atom/2013 => /archives/2013/index.atom + + +author + Link to an author's page. + + Example: + + link://author/joe => /authors/joe.html + + +author_atom + Link to an author's Atom feed. + + Example: + + link://author_atom/joe => /authors/joe.atom + + +author_index + Link to the author's index. + + Example: + + link://authors/ => /authors/index.html + + +author_rss + Link to an author's RSS feed. + + Example: + + link://author_rss/joe => /authors/joe.rss + + +category + A link to a category. + + Example: + + link://category/dogs => /categories/dogs.html + + +category_atom + A link to a category's Atom feed. + + Example: + + link://category_atom/dogs => /categories/dogs.atom + + +category_index + A link to the category index. + + Example: + + link://category_index => /categories/index.html + + +category_rss + A link to a category's RSS feed. + + Example: + + link://category_rss/dogs => /categories/dogs.xml + + +filename + Link to post or page by source filename. + + Example: + + link://filename/manual.txt => /docs/handbook.html + + +gallery + Link to an image gallery's path. + + It will try to find a gallery with that name if it's not ambiguous + or with that path. For example: + + link://gallery/london => /galleries/trips/london/index.html + + link://gallery/trips/london => /galleries/trips/london/index.html + + +gallery_global + Link to the global gallery path, which contains all the images in galleries. + + There is only one copy of an image on multilingual blogs, in the site root. + + link://gallery_global/london => /galleries/trips/london/index.html + + link://gallery_global/trips/london => /galleries/trips/london/index.html + + (a ``gallery`` link could lead to eg. /en/galleries/trips/london/index.html) + + +gallery_rss + Link to an image gallery's RSS feed. + + It will try to find a gallery with that name if it's not ambiguous + or with that path. For example: + + link://gallery_rss/london => /galleries/trips/london/rss.xml + + link://gallery_rss/trips/london => /galleries/trips/london/rss.xml + + +index + Link to a numbered index. + + Example: + + link://index/3 => /index-3.html + + +index_atom + Link to a numbered Atom index. + + Example: + + link://index_atom/3 => /index-3.atom + + +listing + A link to a listing. + + It will try to use the file name if it's not ambiguous, or the file path. + + Example: + + link://listing/hello.py => /listings/tutorial/hello.py.html + + link://listing/tutorial/hello.py => /listings/tutorial/hello.py.html + + +listing_source + A link to the source code for a listing. + + It will try to use the file name if it's not ambiguous, or the file path. + + Example: + + link://listing_source/hello.py => /listings/tutorial/hello.py + + link://listing_source/tutorial/hello.py => /listings/tutorial/hello.py + + +post_path + Link to the destination of an element in the POSTS/PAGES settings. + + Example: + + link://post_path/posts => /blog + + +root + Link to the current language's root. + + Example: + + link://root_path => / + + link://root_path => /translations/spanish/ + + +rss + A link to the RSS feed path. + + Example: + + link://rss => /blog/rss.xml + + +section_index + Link to the index for a section. + + Example: + + link://section_index/cars => /cars/index.html + + +section_index_atom + Link to the Atom index for a section. + + Example: + + link://section_index_atom/cars => /cars/index.atom + + +section_index_rss + Link to the RSS feed for a section. + + Example: + + link://section_index_rss/cars => /cars/rss.xml + + +slug + A link to a post with given slug, if not ambiguous. + + Example: + + link://slug/yellow-camaro => /posts/cars/awful/yellow-camaro/index.html + + +tag + A link to a tag's page. + + Example: + + link://tag/cats => /tags/cats.html + + +tag_atom + A link to a tag's Atom feed. + + Example: + + link://tag_atom/cats => /tags/cats.atom + + +tag_index + A link to the tag index. + + Example: + + link://tag_index => /tags/index.html + + +tag_rss + A link to a tag's RSS feed. + + Example: + + link://tag_rss/cats => /tags/cats.xml + + diff --git a/docs/social_buttons.txt b/docs/social_buttons.txt index 151c906..82fb8ff 100644 --- a/docs/social_buttons.txt +++ b/docs/social_buttons.txt @@ -4,11 +4,12 @@ .. tags: .. link: .. description: +.. author: The Nikola Team Using Alternative Social Buttons with Nikola ============================================ -:Version: 7.6.4 +:Version: 7.8.1 .. class:: alert alert-info pull-right diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index 3cd48af..40594aa 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -27,11 +27,8 @@ from __future__ import unicode_literals # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -try: - import sphinxcontrib.gist # NOQA - extensions = ['sphinxcontrib.gist'] -except ImportError: - extensions = [] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.mathjax'] +# extensions.append('sphinxcontrib.gist') # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -47,16 +44,16 @@ master_doc = 'index' # General information about the project. project = 'Nikola' -copyright = '2012-2015, The Nikola Contributors' +copyright = '2012-2016, The Nikola Contributors' # The version info for the project yo're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '7.6.4' +version = '7.8.1' # The full version, including alpha/beta/rc tags. -release = '7.6.4' +release = '7.8.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/sphinx/index.txt b/docs/sphinx/index.txt index c677caf..5a63d5a 100644 --- a/docs/sphinx/index.txt +++ b/docs/sphinx/index.txt @@ -5,14 +5,19 @@ Those are the docs for the current GitHub master. It might be incompatible with the stable release. The docs for the stable release are available `on the Nikola website <https://getnikola.com/documentation.html>`_. +Please note that some examples of Nikola-specific reST syntax might not be +visible in this version of Nikola docs. + .. toctree:: :maxdepth: 5 manual creating-a-site - creating-a-theme + Creating a Theme <creating-a-theme> theming extending internals - tests social_buttons + path_handlers + Code Documentation <modules> + diff --git a/docs/sphinx/modules.txt b/docs/sphinx/modules.txt new file mode 100644 index 0000000..e310225 --- /dev/null +++ b/docs/sphinx/modules.txt @@ -0,0 +1,7 @@ +nikola +====== + +.. toctree:: + :maxdepth: 4 + + nikola diff --git a/docs/sphinx/nikola.packages.datecond.txt b/docs/sphinx/nikola.packages.datecond.txt new file mode 100644 index 0000000..bfb59b5 --- /dev/null +++ b/docs/sphinx/nikola.packages.datecond.txt @@ -0,0 +1,10 @@ +nikola.packages.datecond package +================================ + +Module contents +--------------- + +.. automodule:: nikola.packages.datecond + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.packages.txt b/docs/sphinx/nikola.packages.txt new file mode 100644 index 0000000..3162d85 --- /dev/null +++ b/docs/sphinx/nikola.packages.txt @@ -0,0 +1,18 @@ +nikola.packages package +======================= + +Subpackages +----------- + +.. toctree:: + + nikola.packages.datecond + nikola.packages.tzlocal + +Module contents +--------------- + +.. automodule:: nikola.packages + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.packages.tzlocal.txt b/docs/sphinx/nikola.packages.tzlocal.txt new file mode 100644 index 0000000..2002afc --- /dev/null +++ b/docs/sphinx/nikola.packages.tzlocal.txt @@ -0,0 +1,46 @@ +nikola.packages.tzlocal package +=============================== + +Submodules +---------- + +nikola.packages.tzlocal.darwin module +------------------------------------- + +.. automodule:: nikola.packages.tzlocal.darwin + :members: + :undoc-members: + :show-inheritance: + +nikola.packages.tzlocal.unix module +----------------------------------- + +.. automodule:: nikola.packages.tzlocal.unix + :members: + :undoc-members: + :show-inheritance: + +nikola.packages.tzlocal.win32 module +------------------------------------ + +.. automodule:: nikola.packages.tzlocal.win32 + :members: + :undoc-members: + :show-inheritance: + +nikola.packages.tzlocal.windows_tz module +----------------------------------------- + +.. automodule:: nikola.packages.tzlocal.windows_tz + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: nikola.packages.tzlocal + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.command.auto.txt b/docs/sphinx/nikola.plugins.command.auto.txt new file mode 100644 index 0000000..59f9dcb --- /dev/null +++ b/docs/sphinx/nikola.plugins.command.auto.txt @@ -0,0 +1,10 @@ +nikola.plugins.command.auto package +=================================== + +Module contents +--------------- + +.. automodule:: nikola.plugins.command.auto + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.command.rst2html.txt b/docs/sphinx/nikola.plugins.command.rst2html.txt new file mode 100644 index 0000000..b6d7a81 --- /dev/null +++ b/docs/sphinx/nikola.plugins.command.rst2html.txt @@ -0,0 +1,10 @@ +nikola.plugins.command.rst2html package +======================================= + +Module contents +--------------- + +.. automodule:: nikola.plugins.command.rst2html + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.command.txt b/docs/sphinx/nikola.plugins.command.txt new file mode 100644 index 0000000..653c2f4 --- /dev/null +++ b/docs/sphinx/nikola.plugins.command.txt @@ -0,0 +1,150 @@ +nikola.plugins.command package +============================== + +Subpackages +----------- + +.. toctree:: + + nikola.plugins.command.auto + nikola.plugins.command.rst2html + +Submodules +---------- + +nikola.plugins.command.bootswatch_theme module +---------------------------------------------- + +.. automodule:: nikola.plugins.command.bootswatch_theme + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.check module +----------------------------------- + +.. automodule:: nikola.plugins.command.check + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.console module +------------------------------------- + +.. automodule:: nikola.plugins.command.console + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.deploy module +------------------------------------ + +.. automodule:: nikola.plugins.command.deploy + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.github_deploy module +------------------------------------------- + +.. automodule:: nikola.plugins.command.github_deploy + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.import_wordpress module +---------------------------------------------- + +.. automodule:: nikola.plugins.command.import_wordpress + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.init module +---------------------------------- + +.. automodule:: nikola.plugins.command.init + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.install_theme module +------------------------------------------- + +.. automodule:: nikola.plugins.command.install_theme + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.new_page module +-------------------------------------- + +.. automodule:: nikola.plugins.command.new_page + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.new_post module +-------------------------------------- + +.. automodule:: nikola.plugins.command.new_post + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.orphans module +------------------------------------- + +.. automodule:: nikola.plugins.command.orphans + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.plugin module +------------------------------------ + +.. automodule:: nikola.plugins.command.plugin + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.serve module +----------------------------------- + +.. automodule:: nikola.plugins.command.serve + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.status module +------------------------------------ + +.. automodule:: nikola.plugins.command.status + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.theme module +----------------------------------- + +.. automodule:: nikola.plugins.command.theme + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.command.version module +------------------------------------- + +.. automodule:: nikola.plugins.command.version + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: nikola.plugins.command + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.compile.markdown.txt b/docs/sphinx/nikola.plugins.compile.markdown.txt new file mode 100644 index 0000000..47e2a0a --- /dev/null +++ b/docs/sphinx/nikola.plugins.compile.markdown.txt @@ -0,0 +1,38 @@ +nikola.plugins.compile.markdown package +======================================= + +Submodules +---------- + +nikola.plugins.compile.markdown.mdx_gist module +----------------------------------------------- + +.. automodule:: nikola.plugins.compile.markdown.mdx_gist + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.markdown.mdx_nikola module +------------------------------------------------- + +.. automodule:: nikola.plugins.compile.markdown.mdx_nikola + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.markdown.mdx_podcast module +-------------------------------------------------- + +.. automodule:: nikola.plugins.compile.markdown.mdx_podcast + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: nikola.plugins.compile.markdown + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.compile.rest.txt b/docs/sphinx/nikola.plugins.compile.rest.txt new file mode 100644 index 0000000..a094a80 --- /dev/null +++ b/docs/sphinx/nikola.plugins.compile.rest.txt @@ -0,0 +1,102 @@ +nikola.plugins.compile.rest package +=================================== + +Submodules +---------- + +nikola.plugins.compile.rest.chart module +---------------------------------------- + +.. automodule:: nikola.plugins.compile.rest.chart + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.rest.doc module +-------------------------------------- + +.. automodule:: nikola.plugins.compile.rest.doc + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.rest.gist module +--------------------------------------- + +.. automodule:: nikola.plugins.compile.rest.gist + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.rest.listing module +------------------------------------------ + +.. automodule:: nikola.plugins.compile.rest.listing + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.rest.media module +---------------------------------------- + +.. automodule:: nikola.plugins.compile.rest.media + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.rest.post_list module +-------------------------------------------- + +.. automodule:: nikola.plugins.compile.rest.post_list + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.rest.slides module +----------------------------------------- + +.. automodule:: nikola.plugins.compile.rest.slides + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.rest.soundcloud module +--------------------------------------------- + +.. automodule:: nikola.plugins.compile.rest.soundcloud + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.rest.thumbnail module +-------------------------------------------- + +.. automodule:: nikola.plugins.compile.rest.thumbnail + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.rest.vimeo module +---------------------------------------- + +.. automodule:: nikola.plugins.compile.rest.vimeo + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.rest.youtube module +------------------------------------------ + +.. automodule:: nikola.plugins.compile.rest.youtube + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: nikola.plugins.compile.rest + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.compile.txt b/docs/sphinx/nikola.plugins.compile.txt new file mode 100644 index 0000000..6a4951b --- /dev/null +++ b/docs/sphinx/nikola.plugins.compile.txt @@ -0,0 +1,54 @@ +nikola.plugins.compile package +============================== + +Subpackages +----------- + +.. toctree:: + + nikola.plugins.compile.markdown + nikola.plugins.compile.rest + +Submodules +---------- + +nikola.plugins.compile.html module +---------------------------------- + +.. automodule:: nikola.plugins.compile.html + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.ipynb module +----------------------------------- + +.. automodule:: nikola.plugins.compile.ipynb + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.pandoc module +------------------------------------ + +.. automodule:: nikola.plugins.compile.pandoc + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.compile.php module +--------------------------------- + +.. automodule:: nikola.plugins.compile.php + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: nikola.plugins.compile + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.misc.txt b/docs/sphinx/nikola.plugins.misc.txt new file mode 100644 index 0000000..03786d8 --- /dev/null +++ b/docs/sphinx/nikola.plugins.misc.txt @@ -0,0 +1,22 @@ +nikola.plugins.misc package +=========================== + +Submodules +---------- + +nikola.plugins.misc.scan_posts module +------------------------------------- + +.. automodule:: nikola.plugins.misc.scan_posts + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: nikola.plugins.misc + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.task.sitemap.txt b/docs/sphinx/nikola.plugins.task.sitemap.txt new file mode 100644 index 0000000..774b09a --- /dev/null +++ b/docs/sphinx/nikola.plugins.task.sitemap.txt @@ -0,0 +1,10 @@ +nikola.plugins.task.sitemap package +=================================== + +Module contents +--------------- + +.. automodule:: nikola.plugins.task.sitemap + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.task.txt b/docs/sphinx/nikola.plugins.task.txt new file mode 100644 index 0000000..9a9bcdb --- /dev/null +++ b/docs/sphinx/nikola.plugins.task.txt @@ -0,0 +1,165 @@ +nikola.plugins.task package +=========================== + +Subpackages +----------- + +.. toctree:: + + nikola.plugins.task.sitemap + +Submodules +---------- + +nikola.plugins.task.archive module +---------------------------------- + +.. automodule:: nikola.plugins.task.archive + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.authors module +---------------------------------- + +.. automodule:: nikola.plugins.task.authors + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.bundles module +---------------------------------- + +.. automodule:: nikola.plugins.task.bundles + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.copy_assets module +-------------------------------------- + +.. automodule:: nikola.plugins.task.copy_assets + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.copy_files module +------------------------------------- + +.. automodule:: nikola.plugins.task.copy_files + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.galleries module +------------------------------------ + +.. automodule:: nikola.plugins.task.galleries + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.gzip module +------------------------------- + +.. automodule:: nikola.plugins.task.gzip + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.indexes module +---------------------------------- + +.. automodule:: nikola.plugins.task.indexes + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.listings module +----------------------------------- + +.. automodule:: nikola.plugins.task.listings + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.pages module +-------------------------------- + +.. automodule:: nikola.plugins.task.pages + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.posts module +-------------------------------- + +.. automodule:: nikola.plugins.task.posts + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.py3_switch module +------------------------------------- + +.. automodule:: nikola.plugins.task.py3_switch + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.redirect module +----------------------------------- + +.. automodule:: nikola.plugins.task.redirect + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.robots module +--------------------------------- + +.. automodule:: nikola.plugins.task.robots + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.rss module +------------------------------ + +.. automodule:: nikola.plugins.task.rss + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.scale_images module +--------------------------------------- + +.. automodule:: nikola.plugins.task.scale_images + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.sources module +---------------------------------- + +.. automodule:: nikola.plugins.task.sources + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.tags module +------------------------------- + +.. automodule:: nikola.plugins.task.tags + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: nikola.plugins.task + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.template.txt b/docs/sphinx/nikola.plugins.template.txt new file mode 100644 index 0000000..48c34e3 --- /dev/null +++ b/docs/sphinx/nikola.plugins.template.txt @@ -0,0 +1,30 @@ +nikola.plugins.template package +=============================== + +Submodules +---------- + +nikola.plugins.template.jinja module +------------------------------------ + +.. automodule:: nikola.plugins.template.jinja + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.template.mako module +----------------------------------- + +.. automodule:: nikola.plugins.template.mako + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: nikola.plugins.template + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.txt b/docs/sphinx/nikola.plugins.txt new file mode 100644 index 0000000..ec0f4d1 --- /dev/null +++ b/docs/sphinx/nikola.plugins.txt @@ -0,0 +1,33 @@ +nikola.plugins package +====================== + +Subpackages +----------- + +.. toctree:: + + nikola.plugins.command + nikola.plugins.compile + nikola.plugins.misc + nikola.plugins.task + nikola.plugins.template + +Submodules +---------- + +nikola.plugins.basic_import module +---------------------------------- + +.. automodule:: nikola.plugins.basic_import + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: nikola.plugins + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.txt b/docs/sphinx/nikola.txt new file mode 100644 index 0000000..fda5e0b --- /dev/null +++ b/docs/sphinx/nikola.txt @@ -0,0 +1,102 @@ +nikola package +============== + +Subpackages +----------- + +.. toctree:: + + nikola.packages + nikola.plugins + +Submodules +---------- + +nikola.filters module +--------------------- + +.. automodule:: nikola.filters + :members: + :undoc-members: + :show-inheritance: + +nikola.image_processing module +------------------------------ + +.. automodule:: nikola.image_processing + :members: + :undoc-members: + :show-inheritance: + +nikola.nikola module +-------------------- + +.. automodule:: nikola.nikola + :members: + :undoc-members: + :show-inheritance: + +nikola.plugin_categories module +------------------------------- + +.. automodule:: nikola.plugin_categories + :members: + :undoc-members: + :show-inheritance: + +nikola.post module +------------------ + +.. automodule:: nikola.post + :members: + :undoc-members: + :show-inheritance: + +nikola.rc4 module +----------------- + +.. automodule:: nikola.rc4 + :members: + :undoc-members: + :show-inheritance: + +nikola.shortcodes module +------------------------ + +.. automodule:: nikola.shortcodes + :members: + :undoc-members: + :show-inheritance: + +nikola.state module +------------------- + +.. automodule:: nikola.state + :members: + :undoc-members: + :show-inheritance: + +nikola.utils module +------------------- + +.. automodule:: nikola.utils + :members: + :undoc-members: + :show-inheritance: + +nikola.winutils module +---------------------- + +.. automodule:: nikola.winutils + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: nikola + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/path_handlers.txt b/docs/sphinx/path_handlers.txt new file mode 120000 index 0000000..f097a70 --- /dev/null +++ b/docs/sphinx/path_handlers.txt @@ -0,0 +1 @@ +../path_handlers.txt
\ No newline at end of file diff --git a/docs/sphinx/requirements-docs.txt b/docs/sphinx/requirements-docs.txt new file mode 100644 index 0000000..dd22560 --- /dev/null +++ b/docs/sphinx/requirements-docs.txt @@ -0,0 +1 @@ +-r ../../requirements-extras.txt diff --git a/docs/support.rst b/docs/support.rst index bfcc24d..9cc1949 100644 --- a/docs/support.rst +++ b/docs/support.rst @@ -2,8 +2,9 @@ .. slug: contact .. date: 1970-01-01 15:00:00 .. description: Get help using Nikola, or contact us. +.. author: The Nikola Team -:Version: 7.5.1 +:Version: 7.8.1 .. class:: alert alert-info pull-right @@ -41,7 +42,7 @@ Report a Bug, Request a Feature Bug reports should be sent to the `Issue tracker`_ at GitHub. -Feature requests should be sent to the or to the `Issue tracker`_ or to +Feature requests should be sent to the `Issue tracker`_ or to the `mailing list`_, especially if they require further discussion. Administrativia @@ -59,15 +60,17 @@ Administrators .. class:: table table-bordered -+----------------+-----------------+-----------+-----------------------+ -| Name | GitHub Nickname | Location | E-mail | -+================+=================+===========+=======================+ -| Roberto Alsina | ralsina | Argentina | roberto@getnikola.com | -+----------------+-----------------+-----------+-----------------------+ -| Damián Avila | damianavila | Argentina | damian@getnikola.com | -+----------------+-----------------+-----------+-----------------------+ -| Chris Warrick | Kwpolska | Poland | chris@getnikola.com | -+----------------+-----------------+-----------+-----------------------+ ++----------------------+-----------------+-----------+-----------------------+ +| Name | GitHub Nickname | Location | E-mail | ++======================+=================+===========+=======================+ +| Roberto Alsina | ralsina | Argentina | roberto@getnikola.com | ++----------------------+-----------------+-----------+-----------------------+ +| Damián Avila | damianavila | Argentina | damian@getnikola.com | ++----------------------+-----------------+-----------+-----------------------+ +| Daniel Aleksandersen | Aeyoun | Norway | daniel@getnikola.com | ++----------------------+-----------------+-----------+-----------------------+ +| Chris Warrick | Kwpolska | Poland | chris@getnikola.com | ++----------------------+-----------------+-----------+-----------------------+ .. _mailing list: http://groups.google.com/group/nikola-discuss .. _Issue tracker: https://github.com/getnikola/nikola/issues diff --git a/docs/theming.txt b/docs/theming.txt index 4b6b4a7..a11306c 100644 --- a/docs/theming.txt +++ b/docs/theming.txt @@ -4,11 +4,12 @@ .. tags: .. link: .. description: +.. author: The Nikola Team Theming Nikola ============== -:Version: 7.6.4 +:Version: 7.8.1 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> .. class:: alert alert-info pull-right @@ -35,7 +36,7 @@ assets The included themes use `Bootstrap <http://twitter.github.com/bootstrap/>`_ and `Colorbox <http://www.jacklmoore.com/colorbox>`_ so they are in assets, - along with CSS files for syntax highligting and reStructuredText, and a + along with CSS files for syntax highlighting and reStructuredText, and a minified copy of jQuery. If you want to base your theme on other frameworks (or on no framework at all) @@ -105,6 +106,12 @@ should learn one first. What engine is used by the theme is declared in the ``en The rest of this document explains Mako templates, but Jinja2 is fairly similar. +.. Tip:: + + If you are using Mako templates, and want some extra speed when building the site + you can install Beaker and `make templates be cached <http://docs.makotemplates.org/en/latest/caching.html>`__ + + Mako has a nifty concept of template inheritance. That means that, a template can inherit from another and only change small bits of the output. For example, ``base.tmpl`` defines the whole layout for a page but has only a placeholder for content @@ -118,7 +125,7 @@ These are the templates that come with the included themes: It has some separate pieces defined in ``base_helper.tmpl``, ``base_header.tmpl`` and ``base_footer.tmpl`` so they can be - easily overriden. + easily overridden. ``index.tmpl`` Template used to render the multipost indexes. The posts are in a ``posts`` variable. @@ -193,6 +200,100 @@ require whatever data you want. Also, you can specify a custom template to be used by a post or page via the ``template`` metadata, and custom templates can be added in the ``templates/`` folder of your site. +Customizing themes to user color preference and section colors +-------------------------------------------------------------- + +The user’s preference for theme color is exposed in templates as +``theme_color`` set in the ``THEME_COLOR`` option. + +Each section has an assigned color that is either set by the user or auto +selected by adjusting the hue of the user’s ``THEME_COLOR``. The color is +exposed in templates through ``post.section_color(lang)``. The function that +generates the colors from strings and any given color (by section name and +theme color for sections) is exposed through the +``colorize_str_from_base_color(string, hex_color)`` function + +Hex color values, like that returned by the theme or section color can be +altered in the HSL colorspace through the function +``color_hsl_adjust_hex(hex_string, adjust_h, adjust_s, adjust_l)``. +Adjustments are given in values between 1.0 and -1.0. For example, the theme +color can be made lighter using: + +.. code:: html+mako + + <span style="color:${color_hsl_adjust_hex(theme_color, adjust_l=0.05)}"> + +Identifying and customizing different kinds of pages with a shared template +--------------------------------------------------------------------------- + +Nikola provides a `pagekind` in each template contexts that can be used to +modify shared templates based on the context it’s being used. For example, +the ``base_helper.tmpl`` is used in all pages, ``indexes.tmpl`` is used in +many contexts and you may want to add or remove something from only one of +these contexts. + +Example of conditionally loading different resources on all index pages +(archives, author pages, and tag pages), and others again o the front page +and in every post pages: + +.. code:: html+mako + + <head> + … + % if 'index' in pagekind: + <link href="/assets/css/multicolumn.css" rel="stylesheet"> + % endif + % if 'front_page' in pagekind: + <link href="/assets/css/fancy_homepage.css" rel="stylesheet"> + <script src="/assets/js/post_carousel.js"></script> + % endif + % if 'post_page' in pagekind: + <link href="/assets/css/article.css" rel="stylesheet"> + <script src="/assets/js/comment_system.js"></script> + % endif + </head> + +Promoting visits to the front page when visiting other filtered +``index.tmpl`` page variants such as author pages and tag pages. This +could have been included in ``index.tmpl`` or maybe in ``base.tmpl`` +depending on what you want to achieve. + +.. code:: html+mako + + % if 'index' in pagekind: + % if 'author_page' in postkind: + <p>These posts were written by ${author}. See posts by all + authors on the <a href="/">front page</a>.</p> + % elif 'tag_page' in postkind: + <p>This is a filtered selection of posts tagged “${tag}”, visit + the <a href="/">front page</a> to see all posts.</p> + % endif + % endif + + +List of page kinds provided by default plugins: + +* front_page +* index +* index, archive_page +* index, author_page +* index, main_index +* index, section_page +* index, tag_page +* list +* list, archive_page +* list, author_page +* list, section_page +* list, tag_page +* list, tags_page +* post_page +* page_page +* story_page +* listing +* generic_page +* gallery_front +* gallery_page + Messages and Translations ------------------------- |