diff options
| author |   Unit 193 <unit193@unit193.net> | 2021-02-03 19:17:50 -0500 |
|---|---|---|
| committer | Unit 193 <unit193@unit193.net> | 2021-02-03 19:17:50 -0500 |
| commit | 475d074fd74425efbe783fad08f97f2df0c4909f (patch) | |
| tree | 2acdae53999b3c74b716efa4edb5b40311fa356a /docs | |
| parent | cd502d52787f666fff3254d7d7e7578930c813c2 (diff) | |
| parent | 3a0d66f07b112b6d2bdc2b57bbf717a89a351ce6 (diff) | |
Update upstream source from tag 'upstream/8.1.2'
Update to upstream version '8.1.2'
with Debian dir e5e966a9e6010ef70618dc9a61558fa4db35aceb
Diffstat (limited to 'docs')
58 files changed, 2470 insertions, 1158 deletions
diff --git a/docs/creating-a-site.txt b/docs/creating-a-site.rst index 1e5cf29..ebe9aa6 100644 --- a/docs/creating-a-site.txt +++ b/docs/creating-a-site.rst @@ -1,14 +1,11 @@ +.. title: Creating a Site (Not a Blog) with Nikola .. slug: creating-a-site-not-a-blog-with-nikola .. date: 2015-01-10 10:00:00 UTC .. tags: nikola, python .. link: .. description: -.. title: Creating a Site (Not a Blog) with Nikola .. author: The Nikola Team -Creating a Site (Not a Blog) with Nikola -======================================== - .. class:: lead One of the most frequent questions I get about Nikola is “but how do @@ -48,17 +45,21 @@ configuration file: # Some things in the middle you don't really need to change... # - POSTS = () # you can also keep the current content of POSTS if you want a blog with your site + POSTS = () + # remove destination directory to generate pages in the root directory PAGES = ( - ("pages/*.rst", "", "story.tmpl"), - ("pages/*.txt", "", "story.tmpl"), - ("pages/*.html", "", "story.tmpl"), + ("pages/*.rst", "", "page.tmpl"), + ("pages/*.txt", "", "page.tmpl"), + ("pages/*.html", "", "page.tmpl"), ) # And to avoid a conflict because blogs try to generate /index.html INDEX_PATH = "blog" + # Or you can disable blog indexes altogether: + # DISABLE_INDEXES = True + And now we are ready to create our first page: @@ -115,7 +116,7 @@ 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/>`_ +Nikola theme (called ``bootblog4``) is based on `Bootstrap <http://getbootstrap.com/>`_ you can use anything you like from it: .. code:: rest diff --git a/docs/creating-a-theme.txt b/docs/creating-a-theme.rst index 8cd2a49..a1b737d 100644 --- a/docs/creating-a-theme.txt +++ b/docs/creating-a-theme.rst @@ -1,3 +1,4 @@ +.. title: Creating a Theme .. slug: creating-a-theme .. date: 2015-05-28 18:46:48 UTC .. tags: @@ -6,9 +7,6 @@ .. 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. @@ -17,6 +15,8 @@ create themes. Since I **suck** at designing websites, I asked for opinions on t and got some feedback. Since this is **Not So Hard™**, I will try to make time to port a few and see what happens. +If you are looking for a reference, check out :doc:`Theming reference <theming>` and `Template variables <https://getnikola.com/template-variables.html>`_. + Today’s theme is `Lanyon <https://github.com/poole/lanyon>`__ which is written by `@mdo <https://twitter.com/mdo>`__ and released under a MIT license, which is liberal enough. @@ -113,6 +113,7 @@ then you should use ``base-jinja`` as a parent and ``jinja`` as engine instead:: $ 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). +Also, if you intend to publish your theme on the Index, or want to use it with older versions (v7.8.5 or older), use the ``--legacy-meta`` option for ``nikola theme -n``. You can now build that site using ``nikola build`` and it will look like this: @@ -173,7 +174,7 @@ see something fairly similar: <meta name="viewport" content="width=device-width"> <title>My Nikola Site | My Nikola Site</title> - <link href="assets/css/rst.css" rel="stylesheet" type="text/css"> + <link href="assets/css/rst_base.css" rel="stylesheet" type="text/css"> <link href="assets/css/code.css" rel="stylesheet" type="text/css"> <link href="assets/css/theme.css" rel="stylesheet" type="text/css"> @@ -196,10 +197,11 @@ in a particular way, using a setting called ``CODE_COLOR_SCHEME`` where you can what color scheme the syntax highlighter uses. You can use your own ``assets/css/code.css`` if you don’t like the provided ones. -Nikola **requires** ``assets/css/rst.css`` and ``assets/css/code.css`` to function properly. -We will also add themes for IPython Notebook (``assets/css/ipython.min.css`` +Nikola **requires** ``assets/css/rst_base.css`` and ``assets/css/code.css`` to function properly. +We will also add themes for Jupyter (``assets/css/ipython.min.css`` and ``assets/css/nikola_ipython.css``) into the template; note that they are activated only if you configured your ``POSTS``/``PAGES`` with ipynb support. +There’s also ``assets/css/nikola_rst.css``, which adds Bootstrap 3-style reST notes etc. But how do I tell **our** lanyon theme to use those CSS files instead of whatever it’s using now? By giving our theme its own base_helper.tmpl. @@ -223,7 +225,8 @@ The part we want to change is this: <link href="/assets/css/all-nocdn.css" rel="stylesheet" type="text/css"> %endif %else: - <link href="/assets/css/rst.css" rel="stylesheet" type="text/css"> + <link href="/assets/css/rst_base.css" rel="stylesheet" type="text/css"> + <link href="/assets/css/nikola_rst.css" rel="stylesheet" type="text/css"> <link href="/assets/css/code.css" rel="stylesheet" type="text/css"> <link href="/assets/css/theme.css" rel="stylesheet" type="text/css"> %if has_custom_css: @@ -244,7 +247,8 @@ And we will change it so it uses the lanyon styles instead of theme.css (again, %if use_bundles: <link href="/assets/css/all.css" rel="stylesheet" type="text/css"> %else: - <link href="/assets/css/rst.css" rel="stylesheet" type="text/css"> + <link href="/assets/css/rst_base.css" rel="stylesheet" type="text/css"> + <link href="/assets/css/nikola_rst.css" rel="stylesheet" type="text/css"> <link href="/assets/css/poole.css" rel="stylesheet" type="text/css"> <link href="/assets/css/lanyon.css" rel="stylesheet" type="text/css"> <link href="/assets/css/code.css" rel="stylesheet" type="text/css"> @@ -323,7 +327,6 @@ all the interesting stuff: <%namespace name="base" file="base_helper.tmpl" import="*"/> <%namespace name="header" file="base_header.tmpl" import="*"/> <%namespace name="footer" file="base_footer.tmpl" import="*"/> - <%namespace name="annotations" file="annotation_helper.tmpl"/> ${set_locale(lang)} ${base.html_headstart()} <%block name="extra_head"> @@ -349,7 +352,7 @@ all the interesting stuff: That link which says "Skip to main content" is very important for accessibility, so we will leave it in place. But below, you can see how it creates the "container" div we see in the Nikola page, and the content is created by ``html_header()`` which is defined in ``base_header.tmpl`` The actual ``nav`` element is done -by the ``html_navigation_links`` function out of the ``NAVIGATION_LINKS`` option. +by the ``html_navigation_links`` function out of the ``NAVIGATION_LINKS`` and ``NAVIGATION_ALT_LINKS`` options. (Let's put the alt links after regular ones; Bootstrap puts it on the right side, for example.) So, first, lets change that base template to be more lanyon-like: @@ -359,7 +362,6 @@ So, first, lets change that base template to be more lanyon-like: <%namespace name="base" file="base_helper.tmpl" import="*"/> <%namespace name="header" file="base_header.tmpl" import="*"/> <%namespace name="footer" file="base_footer.tmpl" import="*"/> - <%namespace name="annotations" file="annotation_helper.tmpl"/> ${set_locale(lang)} ${base.html_headstart()} <%block name="extra_head"> @@ -398,7 +400,7 @@ So, first, lets change that base template to be more lanyon-like: And that’s after I exposed the sidebar by clicking on an invisible widget! One problem, which causes that yellow color in the sidebar is a CSS conflict. -We are loading ``rst.css`` which specifies +We are loading ``rst_base.css`` which specifies the background color of ``div.sidebar`` which is more specific than ``lanyon.css``, which specifies for ``.sidebar`` alone. @@ -428,6 +430,10 @@ Another problem is that the contents of the nav element are wrong. They are not <a class="sidebar-nav-item" href="${url}">${text}</a> %endfor ${template_hooks['menu']()} + + %for url, text in navigation_alt_links[lang]: + <a class="sidebar-nav-item" href="${url}">${text}</a> + %endfor ${template_hooks['menu_alt']()} </nav> </%def> @@ -502,7 +508,7 @@ and at the bottom a label for the sidebar toggle. Easy to do in ``base.tmpl`` Getting there! -The sidebar looks bad because of yet more CSS conflicts with ``rst.css``. By +The sidebar looks bad because of yet more CSS conflicts with ``rst_base.css``. By adding some extra styling in ``lanyon.css``, it will look better. .. code:: css @@ -640,7 +646,7 @@ So, it looks like we will have to fix ``html_site_title`` after all: <%def name="html_site_title()"> <h3 id="brand" class="masthead-title"> - <a href="${abs_link(_link("root", None, lang))}" title="${blog_title}" rel="home">${blog_title}</a> + <a href="${_link("root", None, lang)}" title="${blog_title}" rel="home">${blog_title}</a> </h3> </%def> @@ -804,15 +810,33 @@ Doing the same for layout-reverse, sidebar-overlay and the rest is left as an ex Bundles ------- -If you have ``webassets`` installed and the ``USE_BUNDLES`` option set to True, Nikola can put several CSS or JS files together in a larger file, -which makes sites load faster. To do that, your theme needs a ``bundles`` file where the syntax is:: - - outputfile1.js=thing1.js,thing2.js,... - outputfile2.css=thing1.css,thing2.css,... - -For the Lanyon theme, it should be like this:: - - assets/css/all.css=rst.css,code.css,poole.css,lanyon.css,custom.css +If the ``USE_BUNDLES`` option set to True, +Nikola can put several CSS or JS files together in a larger file, which can +makes site load faster for some deployments. To do this, your theme needs +a ``bundles`` file. The file format is a modified +`config <https://docs.python.org/3/library/configparser.html>`_ file with no +defined section; the basic syntax is:: + + outputfile1.js= + thing1.js, + thing2.js, + ... + outputfile2.css= + thing1.css, + thing2.css, + ... + +For the Lanyon theme, it should look like this:: + + assets/css/all.css= + rst_base.css, + nikola_rst.css, + code.css, + poole.css, + lanyon.css, + custom.css, + +**Note:** trailing commas are optional **Note:** Some themes also support the ``USE_CDN`` option meaning that in some cases it will load one bundle with all CSS and in other will load some CSS files from a CDN and others from a bundle. This is complicated and probably not worth the effort. @@ -822,4 +846,6 @@ The End And that’s it, that’s a whole theme. Eventually, once people start using it, they will notice small broken details, which will need handling one at a time. -This theme should be available in http://themes.getnikola.com#lanyon and you can see it in action at https://themes.getnikola.com/v7/lanyon/index.html +This theme should be available in http://themes.getnikola.com/v7/lanyon/ and you can see it in action at https://themes.getnikola.com/v7/lanyon/demo/ . + +What if you want to extend other parts of the theme? Check out the :doc:`Theming reference <theming>`. You can also contribute your improvements to the `nikola-themes <https://github.com/getnikola/nikola>` repository on GitHub. diff --git a/docs/extending.txt b/docs/extending.rst index 4fa935d..70448b9 100644 --- a/docs/extending.txt +++ b/docs/extending.rst @@ -6,13 +6,10 @@ .. description: .. author: The Nikola Team -Extending Nikola -================ - -:Version: 7.8.1 +:Version: 8.1.2 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> -.. class:: alert alert-info pull-right +.. class:: alert alert-primary float-md-right .. contents:: @@ -32,6 +29,9 @@ folder in your site. Plugins come in various flavours, aimed at extending different aspects of Nikola. +Available Plugin Categories +=========================== + Command Plugins --------------- @@ -123,7 +123,7 @@ For your own plugin, just change the values in a sensible way. The 'long': 'port', 'default': 8000, 'type': int, - 'help': 'Port number (default: 8000)', + 'help': 'Port number', }, { 'name': 'address', @@ -131,7 +131,7 @@ For your own plugin, just change the values in a sensible way. The 'long': '--address', 'type': str, 'default': '127.0.0.1', - 'help': 'Address to bind (default: 127.0.0.1)', + 'help': 'Address to bind', }, ) @@ -140,6 +140,7 @@ For your own plugin, just change the values in a sensible way. The out_dir = self.site.config['OUTPUT_FOLDER'] if not os.path.isdir(out_dir): print("Error: Missing '{0}' folder?".format(out_dir)) + return 1 # Exit code on failure. (return 0 not necessary) else: os.chdir(out_dir) httpd = HTTPServer((options['address'], options['port']), @@ -154,12 +155,14 @@ As mentioned above, a plugin can have options, which the user can see by doing .. code-block:: console $ nikola help serve - Purpose: start the test webserver - Usage: nikola serve [options] + nikola serve [options] + start the test webserver Options: - -p ARG, --port=ARG Port number (default: 8000) - -a ARG, ----address=ARG Address to bind (default: 127.0.0.1) + -p ARG, --port=ARG + Port number [default: 8000] + -a ARG, --address=ARG + Address to bind [default: 127.0.0.1] $ nikola serve -p 9000 Serving HTTP on 127.0.0.1 port 9000 ... @@ -267,23 +270,20 @@ provided by plugins: $ nikola list Scanning posts....done! - build_bundles - build_less copy_assets copy_files + create_bundles post_render redirect - render_archive render_galleries - render_galleries_clean - render_indexes render_listings render_pages render_posts - render_rss render_site render_sources - render_tags + render_taxonomies + robots_file + scale_images sitemap These have access to the ``site`` object which contains your timeline and @@ -367,11 +367,13 @@ PageCompiler Plugins -------------------- These plugins implement markup languages, they take sources for posts or pages and -create HTML or other output files. A good example is `the misaka plugin. <https://github.com/getnikola/plugins/tree/master/v7/misaka>`__ +create HTML or other output files. A good example is `the misaka plugin +<https://github.com/getnikola/plugins/tree/master/v8/misaka>`__ or the built-in +compiler plugins. They must provide: -``compile_html`` +``compile`` Function that builds a file. ``create_post`` @@ -381,8 +383,31 @@ If the compiler produces something other than HTML files, it should also impleme returns the preferred extension for the output file. 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. +plugin must set ``supports_metadata`` to ``True`` and implement ``read_metadata`` that will return a dict containing the +metadata contained in the file. Optionally, it may list ``metadata_conditions`` (see `MetadataExtractor Plugins`_ below) + +MetadataExtractor Plugins +------------------------- + +Plugins that extract metadata from posts. If they are based on post content, +they must implement ``_extract_metadata_from_text`` (takes source of a post +returns a dict of metadata). They may also implement +``split_metadata_from_text``, ``extract_text``. If they are based on filenames, +they only need ``extract_filename``. If ``support_write`` is set to True, +``write_metadata`` must be implemented. + +Every extractor must be configured properly. The ``name``, ``source`` (from the +``MetaSource`` enum in ``metadata_extractors``) and ``priority`` +(``MetaPriority``) fields are mandatory. There might also be a list of +``conditions`` (tuples of ``MetaCondition, arg``), used to check if an +extractor can provide metadata, a compiled regular expression used to split +metadata (``split_metadata_re``, may be ``None``, used by default +``split_metadata_from_text``), a list of ``requirements`` (3-tuples: import +name, pip name, friendly name), ``map_from`` (name of ``METADATA_MAPPING`` to +use, if any) and ``supports_write`` (whether the extractor supports writing +metadata in the desired format). + +For more details, see the definition in ``plugin_categories.py`` and default extractors in ``metadata_extractors.py``. RestExtension Plugins --------------------- @@ -457,7 +482,7 @@ Currently Nikola emits the following signals: '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>`__ +One example is the `deploy_hooks plugin. <https://github.com/getnikola/plugins/tree/master/v7/deploy_hooks>`__ ConfigPlugin Plugins -------------------- @@ -465,14 +490,24 @@ ConfigPlugin Plugins Does nothing specific, can be used to modify the site object (and thus the config). Put all the magic you want in ``set_site()``, and don’t forget to run the one -from ``super()``. Example plugin: `navstories <https://github.com/getnikola/plugins/tree/master/v7/navstories>`__ +from ``super()``. Example plugin: `navstories <https://github.com/getnikola/plugins/tree/master/v7/navstories>`__ + +Shortcode Plugins +----------------- + +Shortcode Plugins are a simple way to create a custom shortcode handler. +By default, the ``set_site`` method will register the ``handler`` method as a +shortcode with the plugin’s ``name`` as the shortcode name. + +See the Shortcodes_ section for more details on shortcodes. PostScanner Plugins ------------------- Get posts and pages from "somewhere" to be added to the timeline. -The only currently existing plugin of this kind reads them from disk. - +There are currently two plugins for this: the built-in ``scan_posts``, and +``pkgindex_scan`` (in the Plugin Index), which is used to treat .plugin/.theme ++ README.md as posts to generate the Plugin and Theme Indexes. Plugin Index ============ @@ -501,7 +536,7 @@ Here's the relevant code from the tag plugin. # In set_site site.register_path_handler('tag_rss', self.tag_rss_path) - # And these always take name and lang as arguments and returl a list of + # And these always take name and lang as arguments and return a list of # path elements. def tag_rss_path(self, name, lang): return [_f for _f in [self.site.config['TRANSLATIONS'][lang], @@ -535,9 +570,10 @@ HTML: # In set_site def generate_html_bit(name, ftype='js'): + """Generate HTML for an asset.""" return '<script src="/assets/{t}/{n}.{t}">'.format(n=name, t=ftype) - site.template_hooks['extra_head'].append(generate_html_bit, False, 'fancyplugin', type='js') + site.template_hooks['extra_head'].append(generate_html_bit, False, 'fancyplugin', ftype='js') The second argument to ``append()`` is used to determine whether the function @@ -545,11 +581,11 @@ 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: - .. code-block:: python # In set_site def greeting(addr, endswith='', site=None, context=None): + """Greet someone.""" if context['lang'] == 'en': greet = u'Hello' elif context['lang'] == 'es': @@ -562,24 +598,34 @@ arguments. Example use: site.template_hooks['page_header'].append(greeting, True, u'Nikola Tesla', endswith=u'!') +Dependencies for template hooks: + +* if the input is a string, the string value, alongside arguments to ``append``, is used for calculating dependencies +* if the input is a callable, it attempts ``input.template_registry_identifier``, then ``input.__doc__``, and if neither is available, it uses a static string. + +Make sure to provide at least a docstring, or a identifier, to ensure rebuilds work properly. + Shortcodes ========== -Some (hopefully all) markup compilers support shortcodes in these forms:: +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" +.. code:: text - {{% foo %}}Some text{{% /foo %}} # one argument called "data" containing "Some text"{{% /raw %}} + {{% raw %}}{{% foo %}}{{% /raw %}} # No arguments + {{% raw %}{{% foo bar %}}{{% /raw %}} # One argument, containing "bar" + {{% raw %}{{% foo bar baz=bat %}}{{% /raw %}} # Two arguments, one containing "bar", one called "baz" containing "bat" + + {{% raw %}{{% foo %}}Some text{{% /foo %}}{{% /raw %}} # one argument called "data" containing "Some text" 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 - +To implement your own shortcodes from a plugin, you can create a plugin inheriting ``ShortcodePlugin``. +By default, the ``set_site`` method will register the ``handler`` method as a +shortcode with the plugin’s ``name`` as the shortcode name. To have other +shortcode names, you can call ``Nikola.register_shortcode(name, func)`` with the following arguments: ``name``: @@ -608,7 +654,7 @@ variable keyword arguments): between them, otherwise ``None``. ``lang``: - The current language. + 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 @@ -687,3 +733,23 @@ 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. +Logging +======= + +Plugins often need to produce messages to the screen. All plugins get a logger object (``self.logger``) by default, +configured to work with Nikola (logging level, colorful output, plugin name as the logger name). If you need, you can +also use the global (``nikola.utils.LOGGER``) logger, or you can instantiate custom loggers with +``nikola.utils.get_logger`` or the ``nikola.log`` module. + +Template and Dependency Injection +================================= + +Plugins have access to two injection facilities. + +If your plugin needs custom templates for its features (adding pages, displaying stuff, etc.), you can put them in the +``templates/mako`` and ``templates/jinja`` subfolders in your plugin’s folder. Note that those templates have a very low +priority, so that users can override your plugin’s templates with their own. + +If your plugin needs to inject dependencies, the ``inject_dependency(target, dependency)`` function can be used to add a +``dependency`` for tasks which basename == ``target``. This facility should be limited to cases which really need it, +consider other facilities first (eg. adding post dependencies). diff --git a/docs/internals.txt b/docs/internals.rst index 39055e8..12df2b0 100644 --- a/docs/internals.txt +++ b/docs/internals.rst @@ -6,9 +6,6 @@ .. description: .. author: The Nikola Team -Nikola Internals -================ - .. class:: lead When trying to guide someone into adding a feature in Nikola, it hit me that @@ -85,8 +82,8 @@ one of the existing ones. .. sidebar:: Tests While Nikola is not a hardcore TDD project, we like tests. So, please add them if you can. - You can do doctests, you can do unit tests, you can do integration tests. There is support - for all of them. + You can write unit tests or integration tests. (Doctests are not supported + anymore due to fragility.) Posts and Pages --------------- @@ -97,7 +94,7 @@ posts are added into RSS feeds and pages are not. All of them are in a list call 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 +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. .. sidebar:: scan_posts diff --git a/docs/man/nikola.1.gz b/docs/man/nikola.1.gz Binary files differindex 8aff44e..b8029fb 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 2d3384a..60cda19 100644 --- a/docs/man/nikola.rst +++ b/docs/man/nikola.rst @@ -6,7 +6,7 @@ Nikola A Static Site and Blog Generator -------------------------------- -:Version: Nikola 7.8.1 +:Version: Nikola 8.1.2 :Manual section: 1 :Manual group: User Commands diff --git a/docs/manual.txt b/docs/manual.rst index 8b8544b..4cacbeb 100644 --- a/docs/manual.txt +++ b/docs/manual.rst @@ -3,15 +3,13 @@ .. date: 2012-03-30 23:00:00 UTC-03:00 .. link: .. description: -.. tags: mathjax +.. tags: +.. has_math: true .. author: The Nikola Team -The Nikola Handbook -=================== +:Version: 8.1.2 -:Version: 7.8.1 - -.. class:: alert alert-info pull-right +.. class:: alert alert-primary float-md-right .. contents:: @@ -24,9 +22,9 @@ After you have Nikola `installed <https://getnikola.com/getting-started.html>`_: Create an empty site (with a setup wizard): ``nikola init mysite`` -You can create a site with demo files in it with ``nikola init --demo mysite`` + You can create a site with demo files in it with ``nikola init --demo mysite`` -The rest of these commands have to be executed inside the new ``mysite`` folder. + The rest of these commands have to be executed inside the new ``mysite`` folder. Create a post: ``nikola new_post`` @@ -78,10 +76,10 @@ Nikola can't do: * Twitter * Facebook * An Issue tracker -* Anything with forms, really (except for `comments <#comments-and-annotations>`_!) +* Anything with forms, really (except for `comments`_!) -Keep in mind that "static" doesn't mean **boring**. You can have animations, slides -or whatever fancy CSS/HTML5 thingie you like. It only means all that HTML is +Keep in mind that "static" doesn't mean **boring**. You can have animations +or whatever fancy CSS3/HTML5 thingie you like. It only means all that HTML is generated already before being uploaded. On the other hand, Nikola sites will tend to be content-heavy. What Nikola is good at is at putting what you write out there. @@ -136,7 +134,7 @@ Obsolescence You may say those are long term issues, or that they won't matter for years. Well, I believe things should work forever, or as close to it as we can make them. Nikola's static output and its input files will work as long as you can install - a Python 2.7/3.3 or newer under Linux, Windows, or OS X and can find a server + Python 3.5 or newer under Linux, Windows, or macOS and can find a server that sends files over HTTP. That's probably 10 or 15 years at least. Also, static sites are easily handled by the Internet Archive. @@ -173,7 +171,6 @@ Nikola provides the following features: * 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) * Static pages (not part of the blog) * `Math`_ rendering (via MathJax) @@ -189,7 +186,6 @@ Nikola provides the following features: * Easy-to-create image galleries * Image thumbnail generation * Support for displaying source code listings -* Image slideshows * Custom search * Asset (CSS/JS) bundling * gzip compression (for sending via your web server) @@ -213,7 +209,11 @@ Creating a Blog Post 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 that using ``link://slug/path-handlers``). + + Note that magic links with spaces won’t work with some input formats (eg. + reST), so you should use slugs there (eg. ``link://tag/some-tag`` instead of + ``link://tag/Some Tag``) To create a new post, the easiest way is to run ``nikola new_post``. You will @@ -227,7 +227,7 @@ easier to keep it in a single location. The contents of your post have to be written (by default) in `reStructuredText <http://docutils.sf.net>`__ but you can use a lot of different markups using the ``-f`` option. -Currently, Nikola supports reStructuredText, Markdown, IPython (Jupyter) Notebooks, HTML as input, +Currently, Nikola supports reStructuredText, Markdown, Jupyter Notebooks, HTML as input, can also use Pandoc for conversion, and has support for BBCode, CreoleWiki, txt2tags, Textile and more via plugins — for more details, read the `input format documentation <#multiple-input-formats>`__. @@ -274,43 +274,57 @@ The post page is generated by default using the ``post.tmpl`` template, which yo to customize the output. You can also customize paths and the template filename itself — see `How does Nikola decide where posts should go?` - Metadata fields ~~~~~~~~~~~~~~~ Nikola supports many metadata fields in posts. All of them are -translatable and almost all are optional. The meta field format is: - -.. code:: text - - .. name: value - -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. +translatable and almost all are optional. Basic ````` title - Title of the post. (required) + Title of the post. Using HTML/math in titles is not supported/recommended. + (required) 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) + So, if the slug is "the-slug" the page generated would be "the-slug.html" or + "the-slug/index.html" (if you have the pretty URLs option enabled) + + One special case is setting the slug to "index". This means the page generated + would be "some_folder/index.html", which means it will be open for the URL + that ends in "some_folder" or "some_folder/". + + This is useful in some cases, in others may cause conflicts with other pages + Nikola generates (like blog indexes) and as a side effect it disables + "pretty URLs" for this page. So use with care. + date Date of the post, defaults to now. Multiple date formats are accepted. Adding a timezone is recommended. (required for posts) tags - Comma-separated tags of the post. Some tags have special meaning, including - ``draft``, ``private``, ``mathjax`` + Comma-separated tags of the post. + +status + Can be set to ``published`` (default), ``featured``, ``draft``, or ``private``. + +has_math + If set to ``true`` or ``yes``, MathJax resp. KaTeX support is enabled + for this post. category Like tags, except each post can have only one, and they usually have more descriptive names. +guid + String used as GUID in RSS feeds and as ID in Atom feeds instead of the + permalink. + link Link to original source for content. May be displayed by some themes. @@ -330,9 +344,6 @@ author Author of the post, will be used in the RSS feed and possibly in the post display (theme-dependent) -annotations / noannotations - Override the value of the ``ANNOTATIONS`` option for this specific post or page. - 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>`__ @@ -358,34 +369,28 @@ hyphenate 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>`_ + Set to "True" to disable comments. pretty_url - Set to "False" to disable pretty URL for this page. Example: + Set to "False" to disable pretty URL for this page. 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. + media, feeds, and many other uses. .. code:: restructuredtext .. previewimage: /images/looks_great_on_facebook.png + If a post has no `previewimage` it will try to use the `DEFAULT_PREVIEW_IMAGE` + option from the configuration. + 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) + This image is displayed by ``bootblog4`` for featured posts (see `Featured + Posts`_ for details). template Change the template used to render this page/post specific page. That @@ -394,7 +399,14 @@ template .. code:: restructuredtext - .. template: story.tmpl + .. template: foobar.tmpl + +updated + The last time this post was updated, defaults to the post’s ``date`` + metadata value. It is not displayed by default in most themes, including + the defaults — you can use ``post.formatted_updated(date_format)`` (and + perhaps check ``if post.updated != post.date``) in your post template to + show it. 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 @@ -407,32 +419,209 @@ to your configuration: 'author': 'John Doe' } +url_type + Change the URL_TYPE setting for the given page only. Useful for eg. error + pages which cannot use relative URLs. -.. note:: The Two-File Format + .. code:: restructuredtext - Nikola originally used a separate ``.meta`` file. That will still work! - The format of the meta files is the same as shown above (i.e. only - the 7 base fields, in the order listed above), but without the - explanations: + .. url_type: full_path - .. code:: text +Metadata formats +~~~~~~~~~~~~~~~~ + +Metadata can be in different formats. +Current Nikola versions experimentally supports other metadata formats that make it more compatible with +other static site generators. The currently supported metadata formats are: - How to make money - how-to-make-money - 2012-09-15 19:52:05 UTC +* reST-style comments (``.. name: value`` — default format) +* Two-file format (reST-style, YAML, TOML) +* Jupyter Notebook metadata +* YAML, between ``---`` (Jekyll, Hugo) +* TOML, between ``+++`` (Hugo) +* reST docinfo (Pelican) +* Markdown metadata extension (Pelican) +* HTML meta tags (Pelican) - However, starting with Nikola v7, you can now use ``.meta`` files and put - all metadata you want, complete with the explanations — they look just like - the beginning of our reST files. +You can add arbitrary meta fields in any format. - .. code:: restructuredtext +When you create new posts, by default the metadata will be created as reST style comments. +If you prefer a different format, you can set the ``METADATA_FORMAT`` to one of these values: - .. title: How to make money - .. slug: how-to-make-money - .. date: 2012-09-15 19:52:05 UTC +* ``"Nikola"``: reST comments, wrapped in a HTML comment if needed (default) +* ``"YAML"``: YAML wrapped in "---" +* ``"TOML"``: TOML wrapped in "+++" +* ``"Pelican"``: Native markdown metadata or reST docinfo fields. Nikola style for other formats. - Both file formats are supported; however, the new format is preferred, if - possible. +reST-style comments +``````````````````` + +The “traditional” and default meta field format is: + +.. code:: text + + .. name: value + +If you are not using reStructuredText, make sure the fields are in a HTML comment in output. + +Also, note that this format does not support any multi-line values. Try YAML or reST docinfo if you need those. + +Two-file format +``````````````` + +Meta information can also be specified in separate ``.meta`` files. Those support reST-style metadata, with names and custom fields. They look like the beginning of our reST files: + +.. code:: text + + .. title: How to make money + .. slug: how-to-make-money + .. date: 2012-09-15 19:52:05 UTC + +You can also use YAML or TOML metadata inside those (with the appropriate markers). + +Jupyter Notebook metadata +````````````````````````` + +Jupyter posts can store meta information inside ``.ipynb`` files by using the ``nikola`` key inside notebook metadata. It can be edited by using *Edit → Edit Notebook Metadata* in Jupyter. Note that values are currently only strings. Sample metadata (Jupyter-specific information omitted): + +.. code:: json + + { + "nikola": { + "title": "How to make money", + "slug": "how-to-make-money", + "date": "2012-09-15 19:52:05 UTC" + } + } + + +YAML metadata +````````````` + +YAML metadata should be wrapped by a ``---`` separator (three dashes) and in that case, the usual YAML syntax is used: + +.. code:: yaml + + --- + title: How to make money + slug: how-to-make-money + date: 2012-09-15 19:52:05 UTC + --- + +TOML metadata +````````````` + +TOML metadata should be wrapped by a "+++" separator (three plus signs) and in that case, the usual TOML syntax is used: + +.. code:: yaml + + +++ + title = "How to make money" + slug = "how-to-make-money" + date = "2012-09-15 19:52:05 UTC" + +++ + +reST docinfo +```````````` + +Nikola can extract metadata from reStructuredText docinfo fields and the document itself, too: + +.. code:: restructuredtext + + How to make money + ================= + + :slug: how-to-make-money + :date: 2012-09-15 19:52:05 UTC + +To do this, you need ``USE_REST_DOCINFO_METADATA = True`` in your ``conf.py``, +and Nikola will hide the docinfo fields in the output if you set +``HIDE_REST_DOCINFO = True``. + +.. note:: + + Keys are converted to lowercase automatically. + + This setting also means that the first heading in a post will be removed + and considered a title. This is important if you’re mixing metadata + styles. This can be solved by putting a reST comment before your title. + +Pelican/Markdown metadata +````````````````````````` + +Markdown Metadata (Pelican-style) only works in Markdown files, and requires the ``markdown.extensions.meta`` extension +(see `MARKDOWN_EXTENSIONS <#markdown>`__). The exact format is described in +the `markdown metadata extension docs. <https://python-markdown.github.io/extensions/meta_data/>`__ + +.. code:: text + + title: How to make money + slug: how-to-make-money + date: 2012-09-15 19:52:05 UTC + +Note that keys are converted to lowercase automatically. + +HTML meta tags +`````````````` + +For HTML source files, metadata will be extracted from ``meta`` tags, and the title from the ``title`` tag. +Following Pelican's behaviour, tags can be put in a "tags" meta tag or in a "keywords" meta tag. Example: + +.. code:: html + + <html> + <head> + <title>My super title</title> + <meta name="tags" content="thats, awesome" /> + <meta name="date" content="2012-07-09 22:28" /> + <meta name="modified" content="2012-07-10 20:14" /> + <meta name="category" content="yeah" /> + <meta name="authors" content="Conan Doyle" /> + <meta name="summary" content="Short version for index and feeds" /> + </head> + <body> + This is the content of my super blog post. + </body> + </html> + + +Mapping metadata from other formats +``````````````````````````````````` + +If you import posts from other engines, those may not work with Nikola out of the box due to differing names. However, you can create a mapping to convert meta field names from those formats into what Nikola expects. + +For Pelican, use: + +.. code:: python + + METADATA_MAPPING = { + "rest_docinfo": {"summary": "description", "modified": "updated"}, + "markdown_metadata": {"summary": "description", "modified": "updated"} + "html_metadata": {"summary": "description", "modified": "updated"} + } + +For Hugo, use: + +.. code:: python + + METADATA_MAPPING = { + "yaml": {"lastmod": "updated"}, + "toml": {"lastmod": "updated"} + } + +The following source names are supported: ``yaml``, ``toml``, ``rest_docinfo``, ``markdown_metadata``. + +Additionally, you can use ``METADATA_VALUE_MAPPING`` to perform any extra conversions on metadata for **all** posts of a given format (``nikola`` metadata is also supported). A few examples: + +.. code:: python + + METADATA_VALUE_MAPPING = { + "yaml": {"keywords": lambda value: ', '.join(value)}, # yaml: 'keywords' list -> str + "nikola": { + "widgets": lambda value: value.split(', '), # nikola: 'widgets' comma-separated string -> list + "tags": str.lower # nikola: force lowercase 'tags' (input would be string) + } + } Multilingual posts ~~~~~~~~~~~~~~~~~~ @@ -456,11 +645,19 @@ default set to: TRANSLATIONS_PATTERN = "{path}.{lang}.{ext}" -.. note:: Considered languages +.. admonition:: Considered languages Nikola will only look for translation of input files for languages specified in the TRANSLATIONS variable. +In case you translate your posts, you might also want to adjust various +other settings so that the generated URLs match the translation. You can +find most places in `conf.py` by searching for `(translatable)`. For example, +you might want to localize `/categories/` (search for `TAG_PATH`), `/pages/` +and `/posts/` (search for `POSTS` and `PAGES`, or see the next section), or +how to adjust the URLs for subsequent pages for indexes (search for +`INDEXES_PRETTY_PAGE_URL`). + 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/>`_ @@ -501,6 +698,12 @@ options. The exact mechanism is explained above the config options in the # to feeds, indexes, tag lists and archives and are considered part # of a blog, while PAGES are just independent HTML pages. # + # Finally, note that destination can be translated, i.e. you can + # specify a different translation folder per language. Example: + # PAGES = ( + # ("pages/*.rst", {"en": "pages", "de": "seiten"}, "page.tmpl"), + # ("pages/*.md", {"en": "pages", "de": "seiten"}, "page.tmpl"), + # ) POSTS = ( ("posts/*.rst", "posts", "post.tmpl"), @@ -508,12 +711,12 @@ options. The exact mechanism is explained above the config options in the ("posts/*.html", "posts", "post.tmpl"), ) PAGES = ( - ("pages/*.rst", "pages", "story.tmpl"), - ("pages/*.txt", "pages", "story.tmpl"), - ("pages/*.html", "pages", "story.tmpl"), + ("pages/*.rst", "pages", "page.tmpl"), + ("pages/*.txt", "pages", "page.tmpl"), + ("pages/*.html", "pages", "page.tmpl"), ) -.. note:: POSTS and PAGES are not flat! +.. admonition:: 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, @@ -521,6 +724,12 @@ options. The exact mechanism is explained above the config options in the If you have ``PRETTY_URLS`` enabled, that would be ``output/posts/foo/bar/index.html``. + +.. warning:: + + Removing the ``.rst`` entries is not recommended. Some features (eg. + shortcodes) may not work properly if you do that. + The ``new_post`` command ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -549,10 +758,27 @@ The ``new_post`` command supports some options: -F, --available-formats List all available input formats -s Schedule the post based on recurrence rule -i ARG, --import=ARG Import an existing file instead of creating a placeholder + -d, --date-path Create post with date path (eg. year/month/day, see NEW_POST_DATE_PATH_FORMAT in 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. +"foo" as its slug. You can also provide a directory name, in which case Nikola +will append the file name for you (generated from title). + +The ``-d, --date-path`` option automates creation of ``year/month/day`` or +similar directory structures. It can be enabled on a per-post basis, or you can +use it for every post if you set ``NEW_POST_DATE_PATH = True`` in conf.py. + +.. code:: python + + # Use date-based path when creating posts? + # Can be enabled on a per-post basis with `nikola new_post -d`. + # NEW_POST_DATE_PATH = False + + # What format to use when creating posts with date paths? + # Default is '%Y/%m/%d', other possibilities include '%Y' or '%Y/%m'. + # NEW_POST_DATE_PATH_FORMAT = '%Y/%m/%d' Teasers ~~~~~~~ @@ -560,7 +786,8 @@ Teasers You may not want to show the complete content of your posts either on your index page or in RSS feeds, but to display instead only the beginning of them. -If it's the case, you only need to add a "magical comment" in your post. +If it's the case, you only need to add a "magical comment" ``TEASER_END`` or +``END_TEASER`` in your post. In reStructuredText: @@ -594,7 +821,7 @@ compatible with both WordPress and Nikola posts: .. code:: python import re - TEASER_REGEXP = re.compile('<!--\s*(more|TEASER_END)(:(.+))?\s*-->', re.IGNORECASE) + TEASER_REGEXP = re.compile('<!--\s*(more|TEASER_END|END_TEASER)(:(.+))?\s*-->', re.IGNORECASE) Or you can completely customize the link using the ``READ_MORE_LINK`` option. @@ -611,11 +838,12 @@ Or you can completely customize the link using the ``READ_MORE_LINK`` option. Drafts ~~~~~~ -If you add a "draft" tag to a post, then it will not be shown in indexes and feeds. -It *will* be compiled, and if you deploy it it *will* be made available, so use -with care. If you wish your drafts to be not available in your deployed site, you -can set ``DEPLOY_DRAFTS = False`` in your configuration. This will not work if -lazily include ``nikola build`` in your ``DEPLOY_COMMANDS``. +If you set the ``status`` metadata field of a post to ``draft``, it will not be shown +in indexes and feeds. It *will* be compiled, and if you deploy it it *will* be made +available, so use with care. If you wish your drafts to be not available in your +deployed site, you can set ``DEPLOY_DRAFTS = False`` in your configuration. This will +not work if you include ``nikola build`` in your ``DEPLOY_COMMANDS``, as the +option removes the draft posts before any ``DEPLOY_COMMANDS`` are run. Also if a post has a date in the future, it will not be shown in indexes until you rebuild after that date. This behavior can be disabled by setting @@ -628,9 +856,65 @@ Generally, you want FUTURE_IS_NOW and DEPLOY_FUTURE to be the same value. Private Posts ~~~~~~~~~~~~~ -If you add a "private" tag to a post, then it will not be shown in indexes and feeds. -It *will* be compiled, and if you deploy it it *will* be made available, so it will -not generate 404s for people who had linked to it. +If you set the ``status`` metadata field of a post to ``private``, it will not be shown +in indexes and feeds. It *will* be compiled, and if you deploy it it *will* be made +available, so it will not generate 404s for people who had linked to it. + +Featured Posts +~~~~~~~~~~~~~~ + +Some themes, ``bootblog4`` in particular, support featured posts. To mark a +post as featured, simply set the ``status`` meta field to ``featured``. All +featured posts are available in index templates in a ``featured`` +list, but only if this is the main blog index. + +For bootblog4, you can display up to three posts as featured: one can be shown +in a large gray box (jumbotron), and two more can appear in small white +cards. In order to enable this feature, you need to add ``THEME_CONFIG`` to +your configuration, and set it up properly: + +.. code:: python + + THEME_CONFIG = { + DEFAULT_LANG: { + # Show the latest featured post in a large box, with the previewimage as its background. + 'featured_large': True, + # Show the first (remaining) two featured posts in small boxes. + 'featured_small': True, + # Show featured posts on mobile. + 'featured_on_mobile': True, + # Show image in `featured_large` on mobile. + # `featured_small` displays them only on desktop. + 'featured_large_image_on_mobile': False, + # Strip HTML from featured post text. + 'featured_strip_html': True, + # Contents of the sidebar, If empty, the sidebar is not displayed. + 'sidebar': '' + } + } + +You can pick betweeen (up to) 1, 2, or 3 featured posts. You can mix +``featured_large`` and ``featured_small``, rest assured that Nikola will always +display the latest posts no matter what setup you choose. If only one posts +qualifies for the small cards, one card taking up all the width will appear. + +Both featured box formats display an image to the right. You can set it by changing the ``previewimage`` meta value to the full path to the image (eg. ``.. previewimage: /images/featured1.png``). This works best with images in portrait orientation. + +Note that, due to space constraints, only the large box may show the image on +mobile, below the text (this behavior can be disbled). Small boxes never +display images on mobile. In particular: ``xs`` and ``sm`` display only the +large image, and only if configured; ``md`` displays only the large image, +``lg`` displays all three images. + +The boxes display only the teaser. We recommend keeping it short so +you don’t get an ugly scrollbar. + +Finally, here’s an example (you’ll need to imagine a scrollbar in the right box +yourself): + +.. thumbnail:: https://getnikola.com/images/bootblog4-featured2x.png + :align: center + :alt: An example of how featured posts look in bootblog4. Queuing Posts ~~~~~~~~~~~~~ @@ -748,13 +1032,7 @@ lead to rebuilding all index pages, which might be a problem for larger blogs 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. +There are two taxonomy systems in Nikola, or two ways to organize posts. Those are tags and categories. They are visible on the *Tags and Categories* page, by default available at ``/categories/``. Each tag/category has an index page and feeds. Tags ```` @@ -769,51 +1047,42 @@ Please note that tags are case-sensitive and that you cannot have two tags that 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. +You can also generate a tag cloud with the `tx3_tag_cloud <https://plugins.getnikola.com/v7/tx3_tag_cloud/>`_ plugin or get a data file for a tag cloud with the `tagcloud <https://plugins.getnikola.com/v8/tagcloud/>`_ 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'), - ) +The next unit for organizing your content are categories. A post can have only one category, specified with the ``category`` meta tag. 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). -* through the ``section`` meta field (requires ``POSTS_SECTION_FROM_META`` setting; recommended especially for existing sites which should not change the directory hierarchy) +Categories are handy to organize different parts of your blog, parts that are about different topics. Unlike tags, which you should have tens (hundreds?) of, the list of categories should be shorter. -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). +Nikola v7 used to support a third taxonomy, called sections. Those have been removed, but all the functionality can be recreated by using the ``CATEGORY_DESTPATH`` settings. -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 and categories +``````````````````````````````` -Configuring tags, categories and sections -````````````````````````````````````````` - -There are multiple configuration variables dedicated to each of the three taxonomies. You can set: +There are multiple configuration variables dedicated to each of the two 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 +* ``TAG_TITLES``, ``CATEGORY_TITLES`` to set titles and descriptions for index pages +* ``TAG_DESCRIPTIONS``, ``CATEGORY_DESCRIPTIONS`` to set descriptions for each of the items * ``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 +* ``CATEGORY_DESTPATH_AS_DEFAULT`` to use the destination path as the category if none is specified in the post +* ``CATEGORY_DESTPATH_TRIM_PREFIX`` to trim the prefix that comes from ``POSTS`` for the destination path +* ``CATEGORY_DESTPATH_FIRST_DIRECTORY`` to only use the first directory name for the defaulted category +* ``CATEGORY_DESTPATH_NAMES`` to specify friendly names for defaulted categories +* ``CATEGORY_PAGES_FOLLOW_DESTPATH`` to put category pages next to their related posts (via destpath) + +What if I don’t want a blog? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want a static site that does not have any blog-related elements, see our +`Creating a Site (Not a Blog) with Nikola`__ guide. + +__ https://getnikola.com/creating-a-site-not-a-blog-with-nikola.html Creating a Page --------------- @@ -822,7 +1091,7 @@ Pages are the same as posts, except that: * They are not added to the front page * They don't appear on the RSS feed -* They use the ``story.tmpl`` template instead of ``post.tmpl`` by default +* They use the ``page.tmpl`` template instead of ``post.tmpl`` by default The default configuration expects the page's metadata and text files to be on the ``pages`` folder, but that can be changed (see ``PAGES`` option above). @@ -841,8 +1110,8 @@ Supported input formats Nikola supports multiple input formats. Out of the box, we have compilers available for: * reStructuredText (default and pre-configured) -* `Markdown`_ -* `IPython Notebook/Jupyter`_ +* `Markdown`_ (pre-configured since v7.8.7) +* `Jupyter Notebook`_ * `HTML`_ * `PHP`_ * anything `Pandoc`_ supports (including Textile, DocBook, LaTeX, MediaWiki, @@ -865,6 +1134,11 @@ Plus, we have specialized compilers in the Plugins Index for: * `CreoleWiki <https://plugins.getnikola.com/#wiki>`_ * `WordPress posts <https://plugins.getnikola.com/#wordpress_compiler>`_ +To write posts in a different format, you need to configure the compiler and +paths. To create a post, use ``nikola new_post -f COMPILER_NAME``, eg. ``nikola +new_post -f markdown``. The default compiler used is the first entry in POSTS +or PAGES. + Configuring other input formats ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -900,16 +1174,20 @@ config option: 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 -```````````````````````` +Jupyter Notebook +```````````````` -To use Jupyter notebooks (previously known as IPython Notebooks) as posts/pages, -make sure ``ipynb`` is in your ``COMPILERS`` and that the ``.ipynb`` extension -is defined in ``POSTS`` and ``PAGES``. +To use Jupyter Notebooks as posts/pages, make sure ``ipynb`` is in your +``COMPILERS`` and that the ``.ipynb`` extension is defined in ``POSTS`` and +``PAGES``. The ``-f`` argument to ``new_post`` should be used in the ``ipynb@KERNEL`` format. It defaults to Python in the version used by Nikola if not specified. +Jupyter Notebooks are also supported in stand-alone listings, if Jupyter +support is enabled site-wide. You must have something for ``.ipynb`` in POSTS +or PAGES for the feature to work. + HTML ```` @@ -953,7 +1231,9 @@ To use them from plugins, please see `Extending Nikola <https://getnikola.com/ex Using a shortcode ~~~~~~~~~~~~~~~~~ -In your content files, a shortcode can be called by using this form:: +In your content files, a shortcode can be called by using this form: + +.. code:: text {{% raw %}}{{% name parameters %}}{{% /raw %}} @@ -963,17 +1243,21 @@ The first word is always the name of the shortcode. Parameters follow the name. 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 ;-):: +Example of a paired shortcode (note that we don't have a highlight shortcode yet ;-): + +.. code:: text {{% raw %}}{{% highlight python %}} A bunch of code here {{% /highlight %}}{{% /raw %}} -.. note:: Shortcodes and reStructuredText +.. admonition:: 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**:: + Also, you can use the shortcode **role**: + + .. code:: text :sc:`{{% raw %}}{{% shortcode here %}}{{% /raw %}}` @@ -983,45 +1267,116 @@ Example of a paired shortcode (note that we don't have a highlight shortcode yet 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 %}} +.. warning:: + Some of the shortcodes are implemented as bindings to reST directives. In + order to use them, you need at least one entry for ``*.rst`` in + POSTS/PAGES. chart Create charts via PyGal. This is similar to the `chart directive <#chart>`__ except the syntax is adapted to - shortcodes. This is an example:: + 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"]'%}} + .. code:: text + + {{% raw %}}{{% chart Bar title='Browser usage evolution (in %)' +x_labels='["2002","2003","2004","2005","2006","2007"]' %}} 'Firefox', [None, None, 0, 16.6, 25, 31] 'Chrome', [None, None, None, None, None, None] 'IE', [85.8, 84.6, 84.7, 74.5, 66, 58.6] 'Others', [14.2, 15.4, 15.3, 8.9, 9, 10.4] {{% /chart %}}{{% /raw %}} + Additionally, you can use a file_data argument which can point to a JSON or YAML file, and will be used for both arguments and data. + Example: + + .. code:: json + + { + "x_labels": ["2002","2003","2004","2005","2006","2007"], + "data": { + "Firefox": [null, null, 0, 16.6, 25, 31], + "Chrome": [null, null, null, null, null, null], + "IE": [85.8, 84.6, 84.7, 74.5, 66, 58.6], + "Others": [14.2, 15.4, 15.3, 8.9, 9, 10.4] + } + } + + Which can be used like this: + + .. code:: text + + {{% raw %}}{{% chart Bar title='Browser usage evolution (in %)' data_file="posts/browsers.json" %}} + {{% /chart %}} + {{% /raw %}} + + If the data or any option is available in both the ``data_file`` and the document, the document has priority. + +doc + Will link to a document in the page, see `Doc role for details + <#doc>`__. Example: + + .. code:: restructuredtext + + {{% raw %}}Take a look at {{% doc %}}my other post <creating-a-theme>{{% /doc %}} about theme creating.{{% /raw %}} + +emoji + Insert an emoji. For example: + + .. code:: text + + {{% raw %}}{{% emoji crying_face %}}{{% /raw %}} + + This generates a ``span`` with ``emoji`` CSS class, so you can style it with a nice font if you want. + gist Show GitHub gists. If you know the gist's ID, this will show it in your site: {{% raw %}}{{% gist 2395294 %}} {{% /raw %}} +listing + Used to show a code listing. Example:: + + {{% raw %}}{{% listing hello.py python linenumbers=True %}}{{% /raw %}} + + It takes a file name or path, an optional language to highlight, and a linenumbers option to enable/disable line numbers in the output. + +media + Display media embedded from a URL, for example, this will embed a youtube video: + + .. code:: text + + {{% raw %}}{{% media url=https://www.youtube.com/watch?v=Nck6BZga7TQ %}}{{% /raw %}} + + Note that the shortcode won’t work if your compiler turns URLs into clickable links. + +post-list + Will show a list of posts, see the `Post List directive for details <#post-list>`__. 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. +thumbnail + Display image thumbnails, with optional captions. Examples: + + .. code:: text + + {{% raw %}}{{% thumbnail "/images/foo.png" %}}{{% /thumbnail %}}{{% /raw %}} + {{% raw %}}{{% thumbnail "/images/foo.png" alt="Foo Image" align="center" %}}{{% /thumbnail %}}{{% /raw %}} + {{% raw %}}{{% thumbnail "/images/foo.png" imgclass="image-grayscale" figclass="figure-shadow" %}}<p>Image caption</p>{{% /thumbnail %}}{{% /raw %}} + {{% raw %}}{{% thumbnail "/images/foo.png" alt="Foo Image" title="Insert title-text joke here" align="right" %}}<p class="caption">Foo Image (right-aligned) caption</p>{{% /thumbnail %}}{{% /raw %}} + + The following keyword arguments are supported: + + * alt (alt text for image) + * align (image alignment, left/center/right) + * linktitle (title text for the link, shown by e.g. baguetteBox) + * title (title text for image) + * imgclass (class for image) + * figclass (class for figure, used only if you provide a caption) + + Looks similar to the reST thumbnail directive. Caption should be a HTML fragment. Community shortcodes ~~~~~~~~~~~~~~~~~~~~ @@ -1044,34 +1399,62 @@ 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 :-) +.. note:: Template-based shortcodes use the same template engine as your site’s theme. + See :doc:`extending` for detailed information. -For example, if your ``shortcodes/foo.tmpl`` contains this:: +For example, if your ``shortcodes/foo.tmpl`` contains this: + +.. code:: text This uses the bar variable: ${bar} -And your post contains this:: +And your post contains this: + +.. code:: text {{% raw %}}{{% foo bar=bla %}}{{% /raw %}} -Then the output file will contain:: +Then the output file will contain: + +.. code:: text This uses the bar variable: bla -Finally, you can use a template shortcode without a file, by inserting the template in the shortcode itself:: +Finally, you can use a template shortcode without a file, by inserting the +template in the shortcode itself: - {{% raw %}} - {{% template %}} + +.. code:: html+mako + + {{% raw %}}{{% template %}}{{% /raw %}} + <ul> % for foo in bar: - <li> ${foo} + <li>${foo}</li> % endfor - {{% /template %}} - {{% /raw %}} + </ul> + {{% raw %}}{{% /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. +You can use anything defined in your configuration's ``GLOBAL_CONTEXT`` as +variables in your shortcode template, with a caveat: Because of an unfortunate +implementation detail (a name conflict), ``data`` is called ``global_data`` +when used in a shortcode. + +If you have some template code that you want to appear in both a template and +shortcode, you can put the shared code in a separate template and import it in both +places. Shortcodes can import any template inside ``templates/`` and themes, +and call any macros defined in those. + +For example, if you define a macro ``foo(x, y)`` in +``templates/shared_sc.tmpl``, you can include ``shared_foo.tmpl`` in +``templates/special_post.tmpl`` and ``shortcodes/foo.tmpl`` and then call the +``${shared_foo.foo(x, y)}`` macro. + The Global Context and Data files --------------------------------- @@ -1092,8 +1475,8 @@ 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 +different post languages). Those are accessible as eg. +``${post.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 @@ -1101,6 +1484,9 @@ 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`_) +Data files are also available as ``global_data``, to avoid name conflicts in +shortcodes. (``global_data`` works everywhere.) + Redirections ------------ @@ -1125,9 +1511,12 @@ you can't, this will work. Configuration ------------- -The configuration file is called ``conf.py`` and can be used to customize a lot of -what Nikola does. Its syntax is python, but if you don't know the language, it -still should not be terribly hard to grasp. +The configuration file can be used to customize a lot of what Nikola does. Its +syntax is python, but if you don't know the language, it still should not be +terribly hard to grasp. + +By default, the ``conf.py`` file in the root of the Nikola website will be used. +You can pass a different configuration file to by using the ``--conf`` command line switch. The default ``conf.py`` you get with Nikola should be fairly complete, and is quite commented. @@ -1149,10 +1538,33 @@ them. For those options, two types of values can be provided: * a string, which will be used for all languages * a dict of language-value pairs, to have different values in each language -.. note:: It is possible to load the configuration from another file by specifying - ``--conf=path/to/other.file`` on Nikola's command line. For example, to - build your blog using the configuration file ``configurations/test.conf.py``, - you have to execute ``nikola build --conf=configurations/test.conf.py``. +.. note:: + As of version 8.0.3 it is possible to create configuration files which inherit values from other Python files. + This might be useful if you're working with similar environments. + + Example: + conf.py: + .. code:: python + + BLOG_AUTHOR = "Your Name" + BLOG_TITLE = "Demo Site" + SITE_URL = "https://yourname.github.io/demo-site + BLOG_EMAIL = "joe@demo.site" + BLOG_DESCRIPTION = "This is a demo site for Nikola." + + debug.conf.py: + .. code:: python + + import conf + globals().update(vars(conf)) + SITE_URL = "http://localhost:8000/" + + or + + .. code:: python + + from conf import * + SITE_URL = "http://localhost:8000/" Customizing Your Site --------------------- @@ -1167,7 +1579,7 @@ CSS tweaking for minimal disruption of the provided CSS files. If you feel tempted to touch other files in assets, you probably will be better off - with a `custom theme <theming.html>`__. + with a :doc:`custom theme <theming>`. If you want to use LESS_ or Sass_ for your custom CSS, or the theme you use contains LESS or Sass code that you want to override, you will need to install @@ -1181,7 +1593,7 @@ CSS 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>`__. + :doc:`custom theme <theming>`. Navigation Links The ``NAVIGATION_LINKS`` option lets you define what links go in a sidebar or menu @@ -1212,14 +1624,17 @@ Navigation Links 1. Support for submenus is theme-dependent. Only one level of submenus is supported. - 2. Some themes, including the default Bootstrap 3 theme, may - present issues if the menu is too large. (in ``bootstrap3``, the - navbar can grow too large and cover contents.) + 2. Some themes, including the default Bootstrap theme, may + present issues if the menu is too large. (in Bootstrap, the navbar + can grow too large and cover contents.) 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 highlighted when active. + There’s also ``NAVIGATION_ALT_LINKS``. Themes may display this somewhere + else, or not at all. Bootstrap puts it on the right side of the header. + The ``SEARCH_FORM`` option contains the HTML code for a search form based on duckduckgo.com which should always work, but feel free to change it to something else. @@ -1247,10 +1662,13 @@ Fancy Dates Nikola can use various styles for presenting dates. DATE_FORMAT - The date format to use if there is no JS or fancy dates are off. Compatible with Python’s ``strftime()`` syntax. + The date format to use if there is no JS or fancy dates are off. `Compatible with CLDR syntax. <http://cldr.unicode.org/translation/date-time>`_ -JS_DATE_FORMAT - The date format to use if fancy dates are on. Compatible with ``moment.js`` syntax. +LUXON_DATE_FORMAT + The date format to use with Luxon. A dictionary of dictionaries: the top level is languages, and the subdictionaries are of the format ``{'preset': False, 'format': 'yyyy-MM-dd HH:mm'}``. `Used by Luxon <https://moment.github.io/luxon/docs/manual/formatting>`_ (format can be the preset name, eg. ``'DATE_LONG'``). + +MOMENTJS_DATE_FORMAT (formerly JS_DATE_FORMAT) + The date format to use if fancy dates are on, and the theme is using Moment.js. DATE_FANCINESS = 0 Fancy dates are off, and DATE_FORMAT is used. @@ -1267,41 +1685,53 @@ For Mako: .. code:: html + % if date_fanciness != 0: + %if date_fanciness == 2: + <!-- Polyfill for relative dates in Safari -- best handled with a CDN --> + <script src="https://polyfill.io/v3/polyfill.js?features=Intl.RelativeTimeFormat.%7Elocale.${luxon_locales[lang]}"></script> + %endif <!-- required scripts -- best handled with bundles --> - <script src="/assets/js/moment-with-locales.min.js"></script> + <script src="/assets/js/luxon.min.js"></script> <script src="/assets/js/fancydates.js"></script> <!-- fancy dates code --> <script> - moment.locale("${momentjs_locales[lang]}"); - fancydates(${date_fanciness}, ${js_date_format}); + luxon.Settings.defaultLocale = "${luxon_locales[lang]}"; + fancydates(${date_fanciness}, ${luxon_date_format}); </script> <!-- end fancy dates code --> + %endif For Jinja2: .. code:: html + {% if date_fanciness != 0 %} + {% if date_fanciness == 2 %} + <!-- Polyfill for relative dates in Safari -- best handled with a CDN --> + <script src="https://polyfill.io/v3/polyfill.js?features=Intl.RelativeTimeFormat.%7Elocale.{{ luxon_locales[lang] }}"></script> + {% endif %} <!-- required scripts -- best handled with bundles --> - <script src="/assets/js/moment-with-locales.min.js"></script> + <script src="/assets/js/luxon.min.js"></script> <script src="/assets/js/fancydates.js"></script> <!-- fancy dates code --> <script> - moment.locale("{{ momentjs_locales[lang] }}"); - fancydates({{ date_fanciness }}, {{ js_date_format }}); + luxon.Settings.defaultLocale = "{{ luxon_locales[lang] }}"; + fancydates({{ date_fanciness }}, {{ luxon_date_format }}); </script> <!-- end fancy dates code --> + {% endif %} Adding Files ------------ -Any files you want to be in ``output/`` but are not generated by Nikola (for example, -``favicon.ico``) just put it in ``files/``. Everything there is copied into -``output`` by the ``copy_files`` task. Remember that you can't have files that collide -with files Nikola generates (it will give an error). +Any files you want to be in ``output/`` but are not generated by Nikola (for +example, ``favicon.ico``) should be placed in ``files/``. Remember that you +can't have files that collide with files Nikola generates (it will give an +error). .. admonition:: Important @@ -1360,23 +1790,21 @@ If you create a nice theme, please share it! You can do it as a pull request in the `GitHub repository <https://github.com/getnikola/nikola-themes>`__. One other option is to tweak an existing theme using a different color scheme, -typography and CSS in general. Nikola provides a ``bootswatch_theme`` option -to create a custom theme by downloading free CSS files from http://bootswatch.com: +typography and CSS in general. Nikola provides a ``subtheme`` command +to create a custom theme by downloading free CSS files from http://bootswatch.com +and http://hackerthemes.com .. code:: console - $ nikola bootswatch_theme -n custom_theme -s flatly -p bootstrap3 - [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Creating 'custom_theme' theme - from 'flatly' and 'bootstrap3' - [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Downloading: - http://bootswatch.com//flatly/bootstrap.min.css - [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Downloading: - 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 -their handy `bootswatchlet <http://news.bootswatch.com/post/29555952123/a-bookmarklet-for-bootswatch>`_ + $ nikola subtheme -n custom_theme -s flatly -p bootstrap4 + [2013-10-12T16:46:58Z] NOTICE: subtheme: Creating 'custom_theme' theme + from 'flatly' and 'bootstrap4' + [2013-10-12T16:46:58Z] NOTICE: subtheme: Downloading: + http://bootswatch.com/flatly/bootstrap.min.css + [2013-10-12T16:46:58Z] NOTICE: subtheme: Downloading: + http://bootswatch.com/flatly/bootstrap.css + [2013-10-12T16:46:59Z] NOTICE: subtheme: Theme created. Change the THEME setting to "custom_theme" to use it. Play with it, there's cool stuff there. This feature was suggested by `clodo <http://elgalpondebanquito.com.ar>`_. @@ -1433,12 +1861,11 @@ sure you have ``nikola`` and ``git`` installed on your PATH. 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. + deployed. We recommend and default to ``src``. * ``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``. + ``True``, unless you are automating builds with CI (eg. GitHub Actions/GitLab CI). 4. Create a ``.gitignore`` file. We recommend adding at least the following entries: @@ -1460,57 +1887,56 @@ If you want to use a custom domain, create your ``CNAME`` file in output directory. To add a custom commit message, use the ``-m`` option, followed by your message. -Automated rebuilds with Travis CI -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Automated rebuilds (GitHub Actions, GitLab) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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>`_. +blog from anywhere in the world, you have multiple options: -Automated rebuilds with GitLab -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* `Automating Nikola rebuilds with GitHub Actions <https://getnikola.com/blog/automating-nikola-rebuilds-with-github-actions.html>`_ (easier for GitHub) +* `Example Nikola site for GitLab Pages <https://gitlab.com/pages/nikola>`_ -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 ------------------------- +Comments +-------- While Nikola creates static sites, there is a minimum level of user interaction you are probably expecting: comments. Nikola supports several third party comment systems: -* `DISQUS <http://disqus.com>`_ -* `IntenseDebate <http://www.intensedebate.com/>`_ -* `LiveFyre <http://www.livefyre.com/>`_ -* `Moot <http://moot.it>`_ -* `Google+ <http://plus.google.com>`_ -* `Facebook <http://facebook.com/>`_ -* `isso <http://posativ.org/isso/>`_ +* `DISQUS <https://disqus.com>`_ +* `IntenseDebate <https://www.intensedebate.com/>`_ +* `Muut (Formerly moot) <https://muut.com/>`_ +* `Facebook <https://facebook.com/>`_ +* `Isso <https://posativ.org/isso/>`_ +* `Commento <https://github.com/adtac/commento>`_ +* `Utterances <https://utteranc.es/>`_ By default it will use DISQUS, but you can change by setting ``COMMENT_SYSTEM`` -to one of "disqus", "intensedebate", "livefyre", "moot", "googleplus", -"facebook" or "isso" +to one of "disqus", "intensedebate", "livefyre", "moot", "facebook", "isso" or "commento" .. sidebar:: ``COMMENT_SYSTEM_ID`` The value of ``COMMENT_SYSTEM_ID`` depends on what comment system you are using and you can see it in the system's admin interface. - * For DISQUS it's called the **shortname** - * In IntenseDebate it's the **IntenseDebate site acct** - * In LiveFyre it's the **siteId** - * In Moot it's your **username** - * For Google Plus, ``COMMENT_SYSTEM_ID`` need not be set. WARNING: this will not work correctly in the test server, needs to be deployed to a real server/URL. + * For DISQUS, it's called the **shortname** + * For IntenseDebate, it's the **IntenseDebate site acct** + * For Muut, it's your **username** * For Facebook, you need to `create an app <https://developers.facebook.com/apps>`_ (turn off sandbox mode!) and get an **App ID** - * For isso, it is the URL of isso (must be world-accessible, encoded with + * For Isso, it's the URL of your Isso instance (must be world-accessible, encoded with Punycode (if using Internationalized Domain Names) and **have a trailing slash**, - default ``http://localhost:8080/``) + default ``http://localhost:8080/``). You can add custom config options via + ``GLOBAL_CONTEXT``, e.g., ``GLOBAL_CONTEXT['isso_config'] = {"require-author": "true"}`` + * For Commento, it's the URL of the commento instance as required by the ``serverUrl`` + parameter in commento's documentation. + * For Utterances, it's the **repo name** (``"org/user"``) on GitHub whose + issue tracker is used for comments. Additional Utterances configuration + values can be stored in the ``GLOBAL_CONTEXT``, e.g., + ``GLOBAL_CONTEXT['utterances_config'] = {"issue-term": "title", + "label": "Comments", "theme": "github-light", "crossorigin": "anonymous")``. To use comments in a visible site, you should register with the service and then set the ``COMMENT_SYSTEM_ID`` option. @@ -1556,17 +1982,13 @@ You can disable comments for a post by adding a "nocomments" metadata field to i You need jQuery, but not because Facebook wants it (see Issue #639). -An alternative or complement to comments are annotations. Nikola integrates -the annotation service provided by `AnnotateIt. <http://annotateit.org/>`_ -To use it, set the ``ANNOTATIONS`` option to True. This is specially useful -if you want feedback on specific parts of your writing. - -You can enable or disable annotations for specific posts or pages using the -``annotations`` and ``noannotations`` metadata. +.. admonition:: Utterances Support -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. + You can copy the configuration options from the `Utterances setup page + <https://utteranc.es>`_ into ``GLOBAL_CONTEXT['utterances_config']``, + except for ``repo``, which should be set as ``COMMENT_SYSTEM_ID``. Note + that the either ``issue-term`` or ``issue-number`` must be provided. All + other Utterances configuration options are optional. Images and Galleries -------------------- @@ -1575,16 +1997,42 @@ To create an image gallery, all you have to do is add a folder inside ``gallerie and put images there. Nikola will take care of creating thumbnails, index page, etc. If you click on images on a gallery, or on images with links in post, you will -see a bigger image, thanks to the excellent `colorbox -<http://www.jacklmoore.com/colorbox>`_. If don’t want this behavior, add an -``.islink`` class to your image or link. (The behavior is caused by -``<a class="image-reference">`` if you need to use it outside of galleries and reST -thumbnails.) +see a bigger image, thanks to the excellent `baguetteBox +<https://feimosi.github.io/baguetteBox.js/>`_. If don’t want this behavior, add an +``.islink`` class to your link. The gallery pages are generated using the ``gallery.tmpl`` template, and you can -customize it there (you could switch to another lightbox instead of colorbox, change +customize it there (you could switch to another lightbox instead of baguetteBox, change its settings, change the layout, etc.). +Images in galleries may be provided with captions and given a specific +ordering, by creating a file in the gallery directory called ``metadata.yml``. +This YAML file should contain a ``name`` field for each image in the gallery +for which you wish to provide either a caption or specific ordering. You can also +create localized versions (``metadata.xx.yml``). + +Only one ``metadata.yml`` is needed per gallery. Here is an example, showing names, +captions and ordering. ``caption`` and ``order`` are given special treatment, +anything else is available to templates, as keys of ``photo_array`` images. + +.. code:: yaml + + --- + name: ready-for-the-acid-wash.jpg + --- + name: almost-full.jpg + caption: The pool is now almost full + --- + name: jumping-in.jpg + caption: We're enjoying the new pool already + order: 4 + --- + name: waterline-tiles.jpg + order: 2 + custom: metadata is supported + --- + + Images to be used in normal posts can be placed in the ``images`` folder. These images will be processed and have thumbnails created just as for galleries, but will then be copied directly to the corresponding path in the ``output`` directory, so you @@ -1607,6 +2055,15 @@ The ``conf.py`` options affecting images and gallery pages are these: USE_FILENAME_AS_TITLE = True EXTRA_IMAGE_EXTENSIONS = [] + # Use a thumbnail (defined by ".. previewimage:" in the gallery's index) in + # list of galleries for each gallery + GALLERIES_USE_THUMBNAIL = False + + # Image to use as thumbnail for those galleries that don't have one + # None: show a grey square + # '/url/to/file': show the image in that url + GALLERIES_DEFAULT_THUMBNAIL = None + # If set to False, it will sort by filename instead. Defaults to True GALLERY_SORT_BY_DATE = True @@ -1619,12 +2076,15 @@ The ``conf.py`` options affecting images and gallery pages are these: # 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 thumbnail has ``.thumbnail`` added before the file extension by default, + # but a different naming template can be configured with IMAGE_THUMBNAIL_FORMAT). IMAGE_THUMBNAIL_SIZE = 400 + IMAGE_THUMBNAIL_FORMAT = '{name}.thumbnail{ext}' 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. +format is the same as for posts. You can use the ``title`` and ``previewimage`` +metadata fields to change how the gallery is shown. If you add some image filenames in ``galleries/gallery_name/exclude.meta``, they will be excluded in the gallery page. @@ -1644,7 +2104,7 @@ you can embed the same in your posts with the following reST directive: .. code:: rest - ..image:: /images/tesla.jpg + .. image:: /images/tesla.jpg Which is equivalent to the following HTML code: @@ -1679,7 +2139,9 @@ 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:: +Do this if you want to be absolutely sure that no sensitive information should ever leak: + +.. code:: python PRESERVE_EXIF_DATA = False EXIF_WHITELIST = {} @@ -1687,7 +2149,9 @@ Do this if you want to be absolutely sure that no sensitive information should e Preserve all EXIF data ~~~~~~~~~~~~~~~~~~~~~~ -Do this if you really don't mind people knowing where pictures were taken, or camera settings. +Do this if you really don't mind people knowing where pictures were taken, or camera settings: + +.. code:: python PRESERVE_EXIF_DATA = True EXIF_WHITELIST = {'*': '*'} @@ -1720,7 +2184,9 @@ Each IFD in turn contains a number of tags. For example, 0th contains a ImageWid 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:: +Let's see an example: + +.. code:: python PRESERVE_EXIF_DATA = True EXIF_WHITELIST = { @@ -1737,6 +2203,22 @@ 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>`__ +Handling ICC Profiles +--------------------- + +Your images may contain `ICC profiles. <https://en.wikipedia.org/wiki/ICC_profile>`__ These describe the color space in which the images were created or captured. + +Most desktop web browsers can use embedded ICC profiles to display images accurately. As of early 2018 few mobile browsers consider ICC profiles when displaying images. A notable exception is Safari on iOS. + +By default Nikola strips out ICC profiles when preparing images for your posts and galleries. If you want Nikola to preserve ICC profiles, add this in your ``conf.py``: + +.. code:: python + + PRESERVE_ICC_PROFILES = True + +You may wish to do this if, for example, your site contains JPEG images that use a wide-gamut profile such as "Display P3". + + Post Processing Filters ----------------------- @@ -1748,15 +2230,14 @@ To do that, you can use the provided helper adding this in your ``conf.py``: .. code:: python - from nikola import filters - FILTERS = { - ".css": [filters.yui_compressor], - ".js": [filters.yui_compressor], + ".css": ["filters.yui_compressor"], + ".js": ["filters.yui_compressor"], } -Where ``filters.yui_compressor`` is a helper function provided by Nikola. You can -replace that with strings describing command lines, or arbitrary python functions. +Where ``"filters.yui_compressor"`` points to a helper function provided by Nikola in the +``filters`` module. You can replace that with strings describing command lines, or +arbitrary python functions. If there's any specific thing you expect to be generally useful as a filter, contact me and I will add it to the filters library so that more people use it. @@ -1792,69 +2273,136 @@ The currently available filters are: ".html": [apply_to_text_file(string.upper)] } -html_tidy_nowrap - Prettify HTML 5 documents with `tidy5 <http://www.html-tidy.org/>`_ +filters.html_tidy_nowrap + Prettify HTML 5 documents with `tidy5 <https://www.html-tidy.org/>`_ -html_tidy_wrap - Prettify HTML 5 documents wrapped at 80 characters with `tidy5 <http://www.html-tidy.org/>`_ +filters.html_tidy_wrap + Prettify HTML 5 documents wrapped at 80 characters with `tidy5 <https://www.html-tidy.org/>`_ -html_tidy_wrap_attr - Prettify HTML 5 documents and wrap lines and attributes with `tidy5 <http://www.html-tidy.org/>`_ +filters.html_tidy_wrap_attr + Prettify HTML 5 documents and wrap lines and attributes with `tidy5 <https://www.html-tidy.org/>`_ -html_tidy_mini - Minify HTML 5 into smaller documents with `tidy5 <http://www.html-tidy.org/>`_ +filters.html_tidy_mini + Minify HTML 5 into smaller documents with `tidy5 <https://www.html-tidy.org/>`_ -html_tidy_withconfig - Run `tidy5 <http://www.html-tidy.org/>`_ with ``tidy5.conf`` as the config file (supplied by user) +filters.html_tidy_withconfig + Run `tidy5 <https://www.html-tidy.org/>`_ with ``tidy5.conf`` as the config file (supplied by user) -html5lib_minify +filters.html5lib_minify Minify HTML5 using html5lib_minify -html5lib_xmllike +filters.html5lib_xmllike Format using html5lib -typogrify - Improve typography using `typogrify <http://static.mintchaos.com/projects/typogrify/>`__ +filters.typogrify + Improve typography using `typogrify <https://github.com/mintchaos/typogrify>`__ -typogrify_sans_widont +filters.typogrify_sans_widont Same as typogrify without the widont filter -minify_lines +filters.typogrify_custom + Run typogrify with a custom set or filters. Takes ``typogrify_filters`` (a list of callables) and ``ignore_tags`` (defaults to None). + +filters.minify_lines **THIS FILTER HAS BEEN TURNED INTO A NOOP** and currently does nothing. -normalize_html +filters.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/>`_ +filters.yui_compressor + Compress CSS/JavaScript using `YUI compressor <https://yui.github.io/yuicompressor/>`_ -closure_compiler +filters.closure_compiler Compile, compress, and optimize JavaScript `Google Closure Compiler <https://developers.google.com/closure/compiler/>`_ -optipng +filters.optipng Compress PNG files using `optipng <http://optipng.sourceforge.net/>`_ -jpegoptim - Compress JPEG files using `jpegoptim <http://www.kokkonen.net/tjko/projects.html>`_ +filters.jpegoptim + Compress JPEG files using `jpegoptim <https://www.kokkonen.net/tjko/projects.html>`_ -cssminify - Minify CSS using http://cssminifier.com/ (requires Internet access) +filters.cssminify + Minify CSS using https://cssminifier.com/ (requires Internet access) -jsminify - Minify JS using http://javascript-minifier.com/ (requires Internet access) +filters.jsminify + Minify JS using https://javascript-minifier.com/ (requires Internet access) -jsonminify +filters.jsonminify Minify JSON files (strip whitespace and use minimal separators). -xmlminify +filters.xmlminify Minify XML files. Suitable for Nikola’s sitemaps and Atom feeds. +filters.add_header_permalinks + Add links next to every header, Sphinx-style. You will need to add styling for the `headerlink` class, + in `custom.css`, for example: + + .. code:: css + + /* Header permalinks */ + h1:hover .headerlink, h2:hover .headerlink, + h3:hover .headerlink, h4:hover .headerlink, + h5:hover .headerlink, h6:hover .headerlink { + display: inline; + } + + .headerlink { + display: none; + color: #ddd; + margin-left: 0.2em; + padding: 0 0.2em; + } + + .headerlink:hover { + opacity: 1; + background: #ddd; + color: #000; + text-decoration: none; + } + + Additionally, you can provide a custom list of XPath expressions which should be used for finding headers (``{hx}`` is replaced by headers h1 through h6). + This is required if you use a custom theme that does not use ``"e-content entry-content"`` as a class for post and page contents. + + .. code:: python + + # Default value: + HEADER_PERMALINKS_XPATH_LIST = ['*//div[@class="e-content entry-content"]//{hx}'] + # Include *every* header (not recommended): + # HEADER_PERMALINKS_XPATH_LIST = ['*//{hx}'] + + +filters.deduplicate_ids + Prevent duplicated IDs in HTML output. An incrementing counter is added to + offending IDs. If used alongside ``add_header_permalinks``, it will fix + those links (it must run **after** that filter) + + IDs are numbered from the bottom up, which is useful for indexes (updates + appear at the top). There are exceptions, which may be configured using + ``DEDUPLICATE_IDS_TOP_CLASSES`` — if any of those classes appears sin the + document, the IDs are rewritten top-down, which is useful for posts/pages + (updates appear at the bottom). + + Note that in rare cases, permalinks might not always be *permanent* in case + of edits. + + .. code:: python + + DEDUPLICATE_IDS_TOP_CLASSES = ('postpage', 'storypage') + + You can also use a file blacklist (``HEADER_PERMALINKS_FILE_BLACKLIST``), + useful for some index pages. Paths include the output directory (eg. + ``output/index.html``) + + You can apply filters to specific posts or pages by using the ``filters`` metadata field: .. code:: restructuredtext - .. filters: filters.html_tidy_nowrap, "sed s/foo/bar" + .. filters: filters.html_tidy_nowrap, "sed s/foo/bar %s" + +Please note that applying custom filters (not those provided via Nikola's filter module) +via metadata only works for filters implemented via external programs like in that `sed` example. Optimizing Your Website ----------------------- @@ -1881,7 +2429,7 @@ different ones, or about other web servers, please share! 4. Optionally you can create static compressed copies and save some CPU on your server with the GZIP_FILES option in Nikola. -5. The webassets Nikola plugin can drastically decrease the number of CSS and JS files your site fetches. +5. The bundles Nikola plugin can drastically decrease the number of CSS and JS files your site fetches. 6. Through the filters feature, you can run your files through arbitrary commands, so that images are recompressed, JavaScript is minimized, etc. @@ -1892,33 +2440,60 @@ different ones, or about other web servers, please share! Math ---- -Nikola supports math input via MathJax. It is activated via the math roles and -directives of reStructuredText and the usual LaTeX delimiters -(backslash-parentheses, backslash-brackets) for other input formats. +Nikola supports math input via MathJax (by default) or KaTeX. It is activated +via the math roles and directives of reStructuredText and the usual LaTeX +delimiters for other input formats. + +Configuration +~~~~~~~~~~~~~ + +Nikola uses MathJax by default. If you want to use KaTeX (faster and prettier, +but may not support every feature yet), set ``USE_KATEX = True`` in +``conf.py``. + +To use mathematics in a post, you **must** set the ``has_math`` metadata field +to ``true``. (Exception: posts that are Jupyter Notebooks are automatically +marked as math) -To use mathematics in a post, you must add the ``mathjax`` tag. +.. Note to editors: the paragraph below uses U+200B, zero-width space. Don’t break it. -We **DO NOT** support the old, deprecated and error-prone ``$inline$`` -delimiters by default. If you want to use them, please add them manually, -like this: +By default, Nikola will accept ``\(...\)`` for inline math; ``\[...\]`` and +``$$...$$`` for display math. If you want to use the old ``$...$`` syntax as well +(which may conflict with running text!), you need to use special config for +your renderer: .. code:: python - MATHJAX_CONFIG = """ - <script type="text/x-mathjax-config"> - MathJax.Hub.Config({ - tex2jax: { - inlineMath: [ ['$','$'], ["\\\(","\\\)"] ], - displayMath: [ ['$$','$$'], ["\\\[","\\\]"] ], - processEscapes: true - }, - displayAlign: 'left', // Change this to 'center' to center equations. - "HTML-CSS": { - styles: {'.MathJax_Display': {"margin": 0}} - } - }); - </script> - """ + MATHJAX_CONFIG = """ + <script type="text/x-mathjax-config"> + MathJax.Hub.Config({ + tex2jax: { + inlineMath: [ ['$','$'], ["\\\(","\\\)"] ], + displayMath: [ ['$$','$$'], ["\\\[","\\\]"] ], + processEscapes: true + }, + displayAlign: 'center', // Change this to 'left' if you want left-aligned equations. + "HTML-CSS": { + styles: {'.MathJax_Display': {"margin": 0}} + } + }); + </script> + """ + + KATEX_AUTO_RENDER = """ + delimiters: [ + {left: "$$", right: "$$", display: true}, + {left: "\\\[", right: "\\\]", display: true}, + {left: "$", right: "$", display: false}, + {left: "\\\(", right: "\\\)", display: false} + ] + """ + +*(Note: the previous paragraph uses invisible characters to prevent rendering +TeX for display, so don’t copy the examples with three dots to your posts)* + +Inline usage +~~~~~~~~~~~~ Inline mathematics are produced using the reST `math` **role** or the LaTeX backslash-parentheses delimiters: @@ -1941,6 +2516,9 @@ 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 usage +~~~~~~~~~~~~~ + Display mathematics are produced using the reST `math` **directive** or the LaTeX backslash-brackets delimiters: @@ -2050,7 +2628,7 @@ WordPress code starts like this: .. code:: text - [soundcloud url="http://api.soundcloud.com/tracks/78131362" + [soundcloud url="http://api.soundcloud.com/tracks/78131362" …/] The ID is 78131362 and you can embed the audio with this: @@ -2094,6 +2672,10 @@ Will include the source code from ``foo.py``, highlight its syntax in python mod and also create a ``listings/foo.py.html`` page (or in another directory, depending on ``LISTINGS_FOLDER``) and the listing will have a title linking to it. +The stand-alone ``listings/`` pages also support Jupyter notebooks, if they are +supported site-wide. You must have something for ``.ipynb`` in POSTS or PAGES +for the feature to work. + Listings support the same options `reST includes`__ support (including various options for controlling which parts of the file are included), and also a ``linenos`` option for Sphinx compatibility. @@ -2139,19 +2721,22 @@ To include an image placed in the ``images`` folder (or other folders defined in .. code:: restructuredtext .. thumbnail:: /images/tesla.jpg + :alt: Nikola Tesla The small thumbnail will be placed in the page, and it will be linked to the bigger version of the image when clicked, using -`colorbox <http://www.jacklmoore.com/colorbox>`_ by default. All options supported by +`baguetteBox <https://feimosi.github.io/baguetteBox.js/>`_ by default. All options supported by the reST `image <http://docutils.sourceforge.net/docs/ref/rst/directives.html#image>`_ -directive are supported (except ``target``). If a body element is provided, the -thumbnail will mimic the behavior of the -`figure <http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure>`_ +directive are supported (except ``target``). Providing ``alt`` is recommended, +as this is the image caption. If a body element is provided, the thumbnail will +mimic the behavior of the `figure +<http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure>`_ directive instead: .. code:: restructuredtext .. thumbnail:: /images/tesla.jpg + :alt: Nikola Tesla Nikola Tesla, the man that invented the 20th century. @@ -2160,22 +2745,7 @@ least this basic HTML: .. code:: html - <a class="image-reference" href="images/tesla.jpg"><img src="images/tesla.thumbnail.jpg"></a> - -Slideshows -~~~~~~~~~~ - -To create an image slideshow, you can use the ``slides`` directive. For example: - -.. code:: restructuredtext - - .. slides:: - - /galleries/demo/tesla_conducts_lg.jpg - /galleries/demo/tesla_lightning2_lg.jpg - /galleries/demo/tesla4_lg.jpg - /galleries/demo/tesla_lightning1_lg.jpg - /galleries/demo/tesla_tower1_lg.jpg + <a class="reference" href="images/tesla.jpg" alt="Nikola Tesla"><img src="images/tesla.thumbnail.jpg"></a> Chart ~~~~~ @@ -2198,14 +2768,16 @@ Here's an example of how it works: The argument passed next to the directive (Bar in that example) is the type of chart, and can be one of Line, StackedLine, Bar, StackedBar, HorizontalBar, XY, DateY, Pie, Radar, Dot, Funnel, Gauge, Pyramid. For -examples of what each kind of graph is, `check here <http://pygal.org/chart_types/>`_ +examples of what each kind of graph is, `check here <http://pygal.org/en/stable/documentation/types/index.html>`_ It can take *a lot* of options to let you customize the charts (in the example, title and x_labels). -You can use any option described in `the pygal docs <http://pygal.org/basic_customizations/>`_ +You can use any option described in `the pygal docs <http://pygal.org/en/stable/documentation/configuration/chart.html>`_ Finally, the content of the directive is the actual data, in the form of a label and a list of values, one series per line. +You can also specify a ``:data_file:`` option as described in the documentation for the chart shortcut. + Doc ~~~ @@ -2231,6 +2803,13 @@ and it will produce: Take a look at :doc:`creating-a-theme` to know how to do it. +The reference in angular brackets should be the `slug` for the target page. It supports a fragment, so +things like ``<creating-a-theme#starting-from-somewhere>`` should work. You can also use the title, and +Nikola will slugify it for you, so ``Creating a theme`` is also supported. + +Keep in mind that the important thing is the slug. No attempt is made to check if the fragment points to +an existing location in the page, and references that don't match any page's slugs will cause warnings. + Post List ~~~~~~~~~ @@ -2266,7 +2845,6 @@ Using shortcode syntax (for other compilers): {{% raw %}}{{% post-list stop=5 %}}{{% /post-list %}}{{% /raw %}} - The following options are recognized: * ``start`` : integer @@ -2296,20 +2874,20 @@ The following options are recognized: * 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 + * value: integer, 'now', 'today', or dateutil-compatible date input * ``tags`` : string [, string...] Filter posts to show only posts having at least one of the ``tags``. Defaults to None. +* ``require_all_tags`` : flag + Change tag filter behaviour to show only posts that have all specified ``tags``. + Defaults to False. + * ``categories`` : string [, string...] 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. @@ -2348,6 +2926,16 @@ 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``. +.. sidebar:: Docutils Configuration + + ReStructured Text is "compiled" by docutils, which supports a number of + configuration options. It would be difficult to integrate them all into + Nikola's configuration, so you can just put a ``docutils.conf`` next + to your ``conf.py`` and any settings in its ``[nikola]`` section will be used. + + More information in the `docutils configuration reference <http://docutils.sourceforge.net/docs/user/config.html>`__ + + Importing your WordPress site into Nikola ----------------------------------------- @@ -2445,11 +3033,6 @@ to your content. Nikola supports `Twitter Cards <https://dev.twitter.com/docs/cards>`_. They are implemented to use *Open Graph* tags whenever possible. -.. admonition:: Important - - To use Twitter Cards you need to opt-in on Twitter. - To do so, please visit https://cards-dev.twitter.com/validator - Images displayed come from the `previewimage` meta tag. You can specify the card type by using the `card` parameter in TWITTER_CARD. @@ -2554,6 +3137,10 @@ of the usual pdb call. By default, doit (and thus Nikola) redirects stdout and stderr. Thus, you must use the different call. (Alternatively, you could run with ``nikola build -v 2``, which disables the redirections.) +To show more logging messages, as well as full tracebacks, you need to set an +environment variable: ``NIKOLA_DEBUG=1``. If you want to only see tracebacks, +set ``NIKOLA_SHOW_TRACEBACKS=1``. + Shell Tab Completion ~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/path_handlers.txt b/docs/path_handlers.rst index 2a03d77..d771ae1 100644 --- a/docs/path_handlers.txt +++ b/docs/path_handlers.rst @@ -2,8 +2,15 @@ .. 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. +.. DO NOT EDIT, this file is auto-generated by scripts/document_path_handlers.py + +Nikola supports special links with the syntax ``link://kind/name``. In +templates you can also use ``_link(kind, name)``. You can add query strings +(``?key=value``) for extra arguments, or pass keyword arguments to ``_link`` in +templates (support and behavior depends on path handlers themselves). Fragments +(``#anchor``) will be appended to the transformed link. + +Here are the descriptions for all the supported kinds. .. class:: dl-horizontal @@ -13,15 +20,6 @@ archive 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. @@ -29,7 +27,6 @@ author Example: link://author/joe => /authors/joe.html - author_atom Link to an author's Atom feed. @@ -37,31 +34,27 @@ author_atom Example: link://author_atom/joe => /authors/joe.atom - author_index - Link to the author's index. + Link to the authors index. Example: link://authors/ => /authors/index.html - author_rss Link to an author's RSS feed. Example: - link://author_rss/joe => /authors/joe.rss - + link://author_rss/joe => /authors/joe.xml category - A link to a category. + A link to a category. Takes page number as optional keyword argument. Example: link://category/dogs => /categories/dogs.html - category_atom A link to a category's Atom feed. @@ -69,7 +62,6 @@ category_atom Example: link://category_atom/dogs => /categories/dogs.atom - category_index A link to the category index. @@ -77,7 +69,6 @@ category_index Example: link://category_index => /categories/index.html - category_rss A link to a category's RSS feed. @@ -85,7 +76,6 @@ category_rss Example: link://category_rss/dogs => /categories/dogs.xml - filename Link to post or page by source filename. @@ -135,7 +125,6 @@ index Example: link://index/3 => /index-3.html - index_atom Link to a numbered Atom index. @@ -143,10 +132,16 @@ index_atom Example: link://index_atom/3 => /index-3.atom + +index_rss + A link to the RSS feed path. + + Example: + link://rss => /blog/rss.xml listing - A link to a listing. + Return a link to a listing. It will try to use the file name if it's not ambiguous, or the file path. @@ -158,7 +153,7 @@ listing listing_source - A link to the source code for a listing. + Return 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. @@ -193,34 +188,9 @@ rss 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. + Return a link to a post with given slug, if not ambiguous. Example: @@ -228,12 +198,11 @@ slug tag - A link to a tag's page. + A link to a tag's page. Takes page number as optional keyword argument. Example: link://tag/cats => /tags/cats.html - tag_atom A link to a tag's Atom feed. @@ -241,7 +210,6 @@ tag_atom Example: link://tag_atom/cats => /tags/cats.atom - tag_index A link to the tag index. @@ -249,7 +217,6 @@ tag_index Example: link://tag_index => /tags/index.html - tag_rss A link to a tag's RSS feed. @@ -257,5 +224,4 @@ tag_rss Example: link://tag_rss/cats => /tags/cats.xml - diff --git a/docs/social_buttons.txt b/docs/social_buttons.rst index 82fb8ff..6b52805 100644 --- a/docs/social_buttons.txt +++ b/docs/social_buttons.rst @@ -1,4 +1,4 @@ -.. title: Alternative Social Buttons +.. title: Using Alternative Social Buttons with Nikola .. slug: social_buttons .. date: 2013-08-19 23:00:00 UTC-03:00 .. tags: @@ -6,12 +6,9 @@ .. description: .. author: The Nikola Team -Using Alternative Social Buttons with Nikola -============================================ +:Version: 8.1.2 -:Version: 7.8.1 - -.. class:: alert alert-info pull-right +.. class:: alert alert-primary float-md-right .. contents:: @@ -69,7 +66,7 @@ Part 4: assets ShareNice --------- -`Sharenice <http://sharenice.org>`__ is "written in order to provide social sharing features to +`ShareNice <https://graingert.co.uk/shareNice/>`__ is "written in order to provide social sharing features to web developers and website administrators who wish to maintain and protect their users' privacy" which sounds cool to me. @@ -117,7 +114,7 @@ One bad bit of this so far is that you are now using a script from another site, doesn't let Nikola perform as many optimizations to your page as it could. So, if you really want to go the extra mile to save a few KB and round trips, you *could* install your own copy from the `github repo <https://github.com/mischat/shareNice>`_ and -use that instead of the copy at sharenice.org. +use that instead of the copy at `ShareNice <http://graingert.co.uk/shareNice>`_. Then, you can create your own theme inheriting from the one you are using and add the CSS and JS files from ShareNice into your ``bundles`` configuration so they are combined and diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index 40594aa..dbc21dd 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -34,7 +34,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.mathjax'] templates_path = ['_templates'] # The suffix of source filenames. -source_suffix = '.txt' +source_suffix = '.rst' # The encoding of source files. # source_encoding = 'utf-8-sig' @@ -44,16 +44,16 @@ master_doc = 'index' # General information about the project. project = 'Nikola' -copyright = '2012-2016, The Nikola Contributors' +copyright = '2012-2020, 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.8.1' +version = '8.1.2' # The full version, including alpha/beta/rc tags. -release = '7.8.1' +release = '8.1.2' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -117,7 +117,7 @@ html_theme = 'default' # The name of an image file (relative to this directory) to place at the top # of the sidebar. -# html_logo = None +html_logo = "../../logo/nikola-50px-transparent.png" # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 @@ -241,7 +241,7 @@ man_pages = [ # dir menu entry, description, category) texinfo_documents = [ ('index', 'Nikola', 'Nikola Documentation', - 'The Nikola Contributors', 'Nikola', 'One line description of project.', + 'The Nikola Contributors', 'Nikola', 'A static site generator.', 'Miscellaneous'), ] diff --git a/docs/sphinx/creating-a-site.rst b/docs/sphinx/creating-a-site.rst new file mode 120000 index 0000000..2eb5b8d --- /dev/null +++ b/docs/sphinx/creating-a-site.rst @@ -0,0 +1 @@ +../creating-a-site.rst
\ No newline at end of file diff --git a/docs/sphinx/creating-a-site.txt b/docs/sphinx/creating-a-site.txt deleted file mode 120000 index 85f2ab2..0000000 --- a/docs/sphinx/creating-a-site.txt +++ /dev/null @@ -1 +0,0 @@ -../creating-a-site.txt
\ No newline at end of file diff --git a/docs/sphinx/creating-a-theme.rst b/docs/sphinx/creating-a-theme.rst new file mode 120000 index 0000000..3723833 --- /dev/null +++ b/docs/sphinx/creating-a-theme.rst @@ -0,0 +1 @@ +../creating-a-theme.rst
\ No newline at end of file diff --git a/docs/sphinx/creating-a-theme.txt b/docs/sphinx/creating-a-theme.txt deleted file mode 120000 index 6ddf35a..0000000 --- a/docs/sphinx/creating-a-theme.txt +++ /dev/null @@ -1 +0,0 @@ -../creating-a-theme.txt
\ No newline at end of file diff --git a/docs/sphinx/extending.rst b/docs/sphinx/extending.rst new file mode 120000 index 0000000..8078fc4 --- /dev/null +++ b/docs/sphinx/extending.rst @@ -0,0 +1 @@ +../extending.rst
\ No newline at end of file diff --git a/docs/sphinx/extending.txt b/docs/sphinx/extending.txt deleted file mode 120000 index 1da5af1..0000000 --- a/docs/sphinx/extending.txt +++ /dev/null @@ -1 +0,0 @@ -../extending.txt
\ No newline at end of file diff --git a/docs/sphinx/index.txt b/docs/sphinx/index.rst index 5a63d5a..b448f76 100644 --- a/docs/sphinx/index.txt +++ b/docs/sphinx/index.rst @@ -10,14 +10,23 @@ visible in this version of Nikola docs. .. toctree:: :maxdepth: 5 + :numbered: + :caption: Nikola Documentation manual creating-a-site Creating a Theme <creating-a-theme> theming + template-variables extending internals social_buttons path_handlers + +.. toctree:: + :maxdepth: 5 + :numbered: + :caption: Autogenerated Code Documentation + Code Documentation <modules> diff --git a/docs/sphinx/internals.rst b/docs/sphinx/internals.rst new file mode 120000 index 0000000..44afd4d --- /dev/null +++ b/docs/sphinx/internals.rst @@ -0,0 +1 @@ +../internals.rst
\ No newline at end of file diff --git a/docs/sphinx/internals.txt b/docs/sphinx/internals.txt deleted file mode 120000 index f0f3f05..0000000 --- a/docs/sphinx/internals.txt +++ /dev/null @@ -1 +0,0 @@ -../internals.txt
\ No newline at end of file diff --git a/docs/sphinx/manual.rst b/docs/sphinx/manual.rst new file mode 120000 index 0000000..bf5c954 --- /dev/null +++ b/docs/sphinx/manual.rst @@ -0,0 +1 @@ +../manual.rst
\ No newline at end of file diff --git a/docs/sphinx/manual.txt b/docs/sphinx/manual.txt deleted file mode 120000 index df591d6..0000000 --- a/docs/sphinx/manual.txt +++ /dev/null @@ -1 +0,0 @@ -../manual.txt
\ No newline at end of file diff --git a/docs/sphinx/modules.txt b/docs/sphinx/modules.rst index e310225..e310225 100644 --- a/docs/sphinx/modules.txt +++ b/docs/sphinx/modules.rst diff --git a/docs/sphinx/nikola.packages.datecond.txt b/docs/sphinx/nikola.packages.datecond.rst index bfb59b5..d5aeead 100644 --- a/docs/sphinx/nikola.packages.datecond.txt +++ b/docs/sphinx/nikola.packages.datecond.rst @@ -1,10 +1,7 @@ nikola.packages.datecond package ================================ -Module contents ---------------- - .. automodule:: nikola.packages.datecond - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.packages.pygments_better_html.rst b/docs/sphinx/nikola.packages.pygments_better_html.rst new file mode 100644 index 0000000..41b5b94 --- /dev/null +++ b/docs/sphinx/nikola.packages.pygments_better_html.rst @@ -0,0 +1,7 @@ +nikola.packages.pygments\_better\_html package +============================================== + +.. automodule:: nikola.packages.pygments_better_html + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.packages.rst b/docs/sphinx/nikola.packages.rst new file mode 100644 index 0000000..916b3ec --- /dev/null +++ b/docs/sphinx/nikola.packages.rst @@ -0,0 +1,17 @@ +nikola.packages package +======================= + +.. automodule:: nikola.packages + :members: + :undoc-members: + :show-inheritance: + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + nikola.packages.datecond + nikola.packages.pygments_better_html + nikola.packages.tzlocal diff --git a/docs/sphinx/nikola.packages.txt b/docs/sphinx/nikola.packages.txt deleted file mode 100644 index 3162d85..0000000 --- a/docs/sphinx/nikola.packages.txt +++ /dev/null @@ -1,18 +0,0 @@ -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.rst b/docs/sphinx/nikola.packages.tzlocal.rst new file mode 100644 index 0000000..944562e --- /dev/null +++ b/docs/sphinx/nikola.packages.tzlocal.rst @@ -0,0 +1,35 @@ +nikola.packages.tzlocal package +=============================== + +.. automodule:: nikola.packages.tzlocal + :members: + :undoc-members: + :show-inheritance: + +Submodules +---------- + +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: + diff --git a/docs/sphinx/nikola.packages.tzlocal.txt b/docs/sphinx/nikola.packages.tzlocal.txt deleted file mode 100644 index 2002afc..0000000 --- a/docs/sphinx/nikola.packages.tzlocal.txt +++ /dev/null @@ -1,46 +0,0 @@ -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.rst index 59f9dcb..e597ff0 100644 --- a/docs/sphinx/nikola.plugins.command.auto.txt +++ b/docs/sphinx/nikola.plugins.command.auto.rst @@ -1,10 +1,7 @@ nikola.plugins.command.auto package =================================== -Module contents ---------------- - .. automodule:: nikola.plugins.command.auto - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.command.rst b/docs/sphinx/nikola.plugins.command.rst new file mode 100644 index 0000000..8c97515 --- /dev/null +++ b/docs/sphinx/nikola.plugins.command.rst @@ -0,0 +1,148 @@ +nikola.plugins.command package +============================== + +.. automodule:: nikola.plugins.command + :members: + :undoc-members: + :show-inheritance: + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + nikola.plugins.command.auto + nikola.plugins.command.rst2html + +Submodules +---------- + +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.default\_config module +--------------------------------------------- + +.. automodule:: nikola.plugins.command.default_config + :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.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.subtheme module +-------------------------------------- + +.. automodule:: nikola.plugins.command.subtheme + :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: + diff --git a/docs/sphinx/nikola.plugins.command.rst2html.txt b/docs/sphinx/nikola.plugins.command.rst2html.rst index b6d7a81..492d0a5 100644 --- a/docs/sphinx/nikola.plugins.command.rst2html.txt +++ b/docs/sphinx/nikola.plugins.command.rst2html.rst @@ -1,10 +1,7 @@ nikola.plugins.command.rst2html package ======================================= -Module contents ---------------- - .. automodule:: nikola.plugins.command.rst2html - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.command.txt b/docs/sphinx/nikola.plugins.command.txt deleted file mode 100644 index 653c2f4..0000000 --- a/docs/sphinx/nikola.plugins.command.txt +++ /dev/null @@ -1,150 +0,0 @@ -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.rst b/docs/sphinx/nikola.plugins.compile.markdown.rst new file mode 100644 index 0000000..b27da4e --- /dev/null +++ b/docs/sphinx/nikola.plugins.compile.markdown.rst @@ -0,0 +1,35 @@ +nikola.plugins.compile.markdown package +======================================= + +.. automodule:: nikola.plugins.compile.markdown + :members: + :undoc-members: + :show-inheritance: + +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: + diff --git a/docs/sphinx/nikola.plugins.compile.markdown.txt b/docs/sphinx/nikola.plugins.compile.markdown.txt deleted file mode 100644 index 47e2a0a..0000000 --- a/docs/sphinx/nikola.plugins.compile.markdown.txt +++ /dev/null @@ -1,38 +0,0 @@ -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.rst index a094a80..3f5d0bd 100644 --- a/docs/sphinx/nikola.plugins.compile.rest.txt +++ b/docs/sphinx/nikola.plugins.compile.rest.rst @@ -1,6 +1,11 @@ nikola.plugins.compile.rest package =================================== +.. automodule:: nikola.plugins.compile.rest + :members: + :undoc-members: + :show-inheritance: + Submodules ---------- @@ -8,95 +13,79 @@ nikola.plugins.compile.rest.chart module ---------------------------------------- .. automodule:: nikola.plugins.compile.rest.chart - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.compile.rest.doc module -------------------------------------- .. automodule:: nikola.plugins.compile.rest.doc - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.compile.rest.gist module --------------------------------------- .. automodule:: nikola.plugins.compile.rest.gist - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.compile.rest.listing module ------------------------------------------ .. automodule:: nikola.plugins.compile.rest.listing - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.compile.rest.media module ---------------------------------------- .. automodule:: nikola.plugins.compile.rest.media - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -nikola.plugins.compile.rest.post_list module --------------------------------------------- +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: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.compile.rest.soundcloud module --------------------------------------------- .. automodule:: nikola.plugins.compile.rest.soundcloud - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.compile.rest.thumbnail module -------------------------------------------- .. automodule:: nikola.plugins.compile.rest.thumbnail - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.compile.rest.vimeo module ---------------------------------------- .. automodule:: nikola.plugins.compile.rest.vimeo - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.compile.rest.youtube module ------------------------------------------ .. automodule:: nikola.plugins.compile.rest.youtube - :members: - :undoc-members: - :show-inheritance: - + :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.rst index 6a4951b..e89de36 100644 --- a/docs/sphinx/nikola.plugins.compile.txt +++ b/docs/sphinx/nikola.plugins.compile.rst @@ -1,13 +1,19 @@ nikola.plugins.compile package ============================== +.. automodule:: nikola.plugins.compile + :members: + :undoc-members: + :show-inheritance: + Subpackages ----------- .. toctree:: + :maxdepth: 4 - nikola.plugins.compile.markdown - nikola.plugins.compile.rest + nikola.plugins.compile.markdown + nikola.plugins.compile.rest Submodules ---------- @@ -16,39 +22,31 @@ nikola.plugins.compile.html module ---------------------------------- .. automodule:: nikola.plugins.compile.html - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.compile.ipynb module ----------------------------------- .. automodule:: nikola.plugins.compile.ipynb - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.compile.pandoc module ------------------------------------ .. automodule:: nikola.plugins.compile.pandoc - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.compile.php module --------------------------------- .. automodule:: nikola.plugins.compile.php - :members: - :undoc-members: - :show-inheritance: - + :members: + :undoc-members: + :show-inheritance: -Module contents ---------------- - -.. automodule:: nikola.plugins.compile - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.misc.rst b/docs/sphinx/nikola.plugins.misc.rst new file mode 100644 index 0000000..2cab79e --- /dev/null +++ b/docs/sphinx/nikola.plugins.misc.rst @@ -0,0 +1,27 @@ +nikola.plugins.misc package +=========================== + +.. automodule:: nikola.plugins.misc + :members: + :undoc-members: + :show-inheritance: + +Submodules +---------- + +nikola.plugins.misc.scan\_posts module +-------------------------------------- + +.. automodule:: nikola.plugins.misc.scan_posts + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.misc.taxonomies\_classifier module +------------------------------------------------- + +.. automodule:: nikola.plugins.misc.taxonomies_classifier + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/sphinx/nikola.plugins.misc.txt b/docs/sphinx/nikola.plugins.misc.txt deleted file mode 100644 index 03786d8..0000000 --- a/docs/sphinx/nikola.plugins.misc.txt +++ /dev/null @@ -1,22 +0,0 @@ -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.rst b/docs/sphinx/nikola.plugins.rst new file mode 100644 index 0000000..f3e8680 --- /dev/null +++ b/docs/sphinx/nikola.plugins.rst @@ -0,0 +1,31 @@ +nikola.plugins package +====================== + +.. automodule:: nikola.plugins + :members: + :undoc-members: + :show-inheritance: + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + 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: + diff --git a/docs/sphinx/nikola.plugins.task.txt b/docs/sphinx/nikola.plugins.task.rst index 9a9bcdb..327887a 100644 --- a/docs/sphinx/nikola.plugins.task.txt +++ b/docs/sphinx/nikola.plugins.task.rst @@ -1,12 +1,10 @@ nikola.plugins.task package =========================== -Subpackages ------------ - -.. toctree:: - - nikola.plugins.task.sitemap +.. automodule:: nikola.plugins.task + :members: + :undoc-members: + :show-inheritance: Submodules ---------- @@ -15,151 +13,159 @@ nikola.plugins.task.archive module ---------------------------------- .. automodule:: nikola.plugins.task.archive - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.task.authors module ---------------------------------- .. automodule:: nikola.plugins.task.authors - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.task.bundles module ---------------------------------- .. automodule:: nikola.plugins.task.bundles - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -nikola.plugins.task.copy_assets module --------------------------------------- +nikola.plugins.task.categories module +------------------------------------- + +.. automodule:: nikola.plugins.task.categories + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.copy\_assets module +--------------------------------------- .. automodule:: nikola.plugins.task.copy_assets - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -nikola.plugins.task.copy_files module -------------------------------------- +nikola.plugins.task.copy\_files module +-------------------------------------- .. automodule:: nikola.plugins.task.copy_files - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.task.galleries module ------------------------------------ .. automodule:: nikola.plugins.task.galleries - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.task.gzip module ------------------------------- .. automodule:: nikola.plugins.task.gzip - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.task.indexes module ---------------------------------- .. automodule:: nikola.plugins.task.indexes - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.task.listings module ----------------------------------- .. automodule:: nikola.plugins.task.listings - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + +nikola.plugins.task.page\_index module +-------------------------------------- + +.. automodule:: nikola.plugins.task.page_index + :members: + :undoc-members: + :show-inheritance: nikola.plugins.task.pages module -------------------------------- .. automodule:: nikola.plugins.task.pages - :members: - :undoc-members: - :show-inheritance: + :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: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.task.redirect module ----------------------------------- .. automodule:: nikola.plugins.task.redirect - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.task.robots module --------------------------------- .. automodule:: nikola.plugins.task.robots - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -nikola.plugins.task.rss module ------------------------------- +nikola.plugins.task.scale\_images module +---------------------------------------- -.. automodule:: nikola.plugins.task.rss - :members: - :undoc-members: - :show-inheritance: +.. automodule:: nikola.plugins.task.scale_images + :members: + :undoc-members: + :show-inheritance: -nikola.plugins.task.scale_images module ---------------------------------------- +nikola.plugins.task.sitemap module +---------------------------------- -.. automodule:: nikola.plugins.task.scale_images - :members: - :undoc-members: - :show-inheritance: +.. automodule:: nikola.plugins.task.sitemap + :members: + :undoc-members: + :show-inheritance: nikola.plugins.task.sources module ---------------------------------- .. automodule:: nikola.plugins.task.sources - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.task.tags module ------------------------------- .. automodule:: nikola.plugins.task.tags - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: +nikola.plugins.task.taxonomies module +------------------------------------- -Module contents ---------------- +.. automodule:: nikola.plugins.task.taxonomies + :members: + :undoc-members: + :show-inheritance: -.. automodule:: nikola.plugins.task - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.task.sitemap.txt b/docs/sphinx/nikola.plugins.task.sitemap.rst index 774b09a..774b09a 100644 --- a/docs/sphinx/nikola.plugins.task.sitemap.txt +++ b/docs/sphinx/nikola.plugins.task.sitemap.rst diff --git a/docs/sphinx/nikola.plugins.template.txt b/docs/sphinx/nikola.plugins.template.rst index 48c34e3..3d4b05e 100644 --- a/docs/sphinx/nikola.plugins.template.txt +++ b/docs/sphinx/nikola.plugins.template.rst @@ -1,6 +1,11 @@ nikola.plugins.template package =============================== +.. automodule:: nikola.plugins.template + :members: + :undoc-members: + :show-inheritance: + Submodules ---------- @@ -8,23 +13,15 @@ nikola.plugins.template.jinja module ------------------------------------ .. automodule:: nikola.plugins.template.jinja - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: nikola.plugins.template.mako module ----------------------------------- .. automodule:: nikola.plugins.template.mako - :members: - :undoc-members: - :show-inheritance: - + :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 deleted file mode 100644 index ec0f4d1..0000000 --- a/docs/sphinx/nikola.plugins.txt +++ /dev/null @@ -1,33 +0,0 @@ -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.rst b/docs/sphinx/nikola.rst new file mode 100644 index 0000000..28a15c3 --- /dev/null +++ b/docs/sphinx/nikola.rst @@ -0,0 +1,116 @@ +nikola package +============== + +.. automodule:: nikola + :members: + :undoc-members: + :show-inheritance: + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + nikola.packages + nikola.plugins + +Submodules +---------- + +nikola.filters module +--------------------- + +.. automodule:: nikola.filters + :members: + :undoc-members: + :show-inheritance: + +nikola.hierarchy\_utils module +------------------------------ + +.. automodule:: nikola.hierarchy_utils + :members: + :undoc-members: + :show-inheritance: + +nikola.image\_processing module +------------------------------- + +.. automodule:: nikola.image_processing + :members: + :undoc-members: + :show-inheritance: + +nikola.log module +----------------- + +.. automodule:: nikola.log + :members: + :undoc-members: + :show-inheritance: + +nikola.metadata\_extractors module +---------------------------------- + +.. automodule:: nikola.metadata_extractors + :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.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: + diff --git a/docs/sphinx/nikola.txt b/docs/sphinx/nikola.txt deleted file mode 100644 index fda5e0b..0000000 --- a/docs/sphinx/nikola.txt +++ /dev/null @@ -1,102 +0,0 @@ -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.rst b/docs/sphinx/path_handlers.rst new file mode 120000 index 0000000..9230f5b --- /dev/null +++ b/docs/sphinx/path_handlers.rst @@ -0,0 +1 @@ +../path_handlers.rst
\ No newline at end of file diff --git a/docs/sphinx/path_handlers.txt b/docs/sphinx/path_handlers.txt deleted file mode 120000 index f097a70..0000000 --- a/docs/sphinx/path_handlers.txt +++ /dev/null @@ -1 +0,0 @@ -../path_handlers.txt
\ No newline at end of file diff --git a/docs/sphinx/requirements-docs.txt b/docs/sphinx/requirements-docs.txt index dd22560..443470f 100644 --- a/docs/sphinx/requirements-docs.txt +++ b/docs/sphinx/requirements-docs.txt @@ -1 +1,2 @@ -r ../../requirements-extras.txt +pyparsing>=2.0.2 diff --git a/docs/sphinx/social_buttons.rst b/docs/sphinx/social_buttons.rst new file mode 120000 index 0000000..ff7a368 --- /dev/null +++ b/docs/sphinx/social_buttons.rst @@ -0,0 +1 @@ +../social_buttons.rst
\ No newline at end of file diff --git a/docs/sphinx/social_buttons.txt b/docs/sphinx/social_buttons.txt deleted file mode 120000 index 12021c1..0000000 --- a/docs/sphinx/social_buttons.txt +++ /dev/null @@ -1 +0,0 @@ -../social_buttons.txt
\ No newline at end of file diff --git a/docs/sphinx/support.rst b/docs/sphinx/support.rst new file mode 120000 index 0000000..1970f58 --- /dev/null +++ b/docs/sphinx/support.rst @@ -0,0 +1 @@ +../support.rst
\ No newline at end of file diff --git a/docs/sphinx/template-variables.rst b/docs/sphinx/template-variables.rst new file mode 120000 index 0000000..524a0ed --- /dev/null +++ b/docs/sphinx/template-variables.rst @@ -0,0 +1 @@ +../template-variables.rst
\ No newline at end of file diff --git a/docs/sphinx/theming.rst b/docs/sphinx/theming.rst new file mode 120000 index 0000000..6b552b6 --- /dev/null +++ b/docs/sphinx/theming.rst @@ -0,0 +1 @@ +../theming.rst
\ No newline at end of file diff --git a/docs/sphinx/theming.txt b/docs/sphinx/theming.txt deleted file mode 120000 index ed5f3b3..0000000 --- a/docs/sphinx/theming.txt +++ /dev/null @@ -1 +0,0 @@ -../theming.txt
\ No newline at end of file diff --git a/docs/sphinx/update-modules.sh b/docs/sphinx/update-modules.sh new file mode 100755 index 0000000..b3bd094 --- /dev/null +++ b/docs/sphinx/update-modules.sh @@ -0,0 +1,2 @@ +#!/bin/bash +sphinx-apidoc -Mfo . ../../nikola diff --git a/docs/support.rst b/docs/support.rst index 9cc1949..03c039a 100644 --- a/docs/support.rst +++ b/docs/support.rst @@ -4,9 +4,9 @@ .. description: Get help using Nikola, or contact us. .. author: The Nikola Team -:Version: 7.8.1 +:Version: 8.1.2 -.. class:: alert alert-info pull-right +.. class:: alert alert-primary float-md-right .. contents:: diff --git a/docs/template-variables.rst b/docs/template-variables.rst new file mode 100644 index 0000000..4eff096 --- /dev/null +++ b/docs/template-variables.rst @@ -0,0 +1,521 @@ +.. title: Template variables +.. slug: template-variables +.. date: 2017-04-13 12:00:00 +.. author: The Nikola Team + +:Version: 8.1.2 +:Author: Chris Warrick <chris@getnikola.com> + +Variables available in templates are listed below. + +* This list is maintained by humans, so it may not always be perfect. +* Variables whose types are marked with ``?`` may not always be available or may be None in some cases. +* Templates usually do not have access to the original TranslatableSetting + variables, only to the current locale version (except ``NAVIGATION_LINKS``). +* For function and setting documentation, please consult `code documentation + <https://docs.getnikola.com/en/latest/modules/>`_ and `default configuration + <https://getnikola.com/conf.html>`_ respectively. +* Templates often create their own functions (macros), and import macros from + other templates. Those macros are not listed here. +* This list has a partial documentation of post objects, but no other objects. For full docs, please consult + the code, or auto-generated code docs on `ReadTheDocs <http://nikola.readthedocs.io/>`_. + +Variables and functions come from three places: + +* the global context +* the local context of a page +* the templates themselves and the templates they import + +.. class:: alert alert-primary +.. contents:: + +Global variables +---------------- + +Some variables on the global variables list may be None (the ``?`` symbol is not used). + +.. class:: table table-bordered table-striped + +================================== ================================== ================================================================================ +Name Type Description +================================== ================================== ================================================================================ +``_link`` function ``Nikola.link`` function +``abs_link`` function ``Nikola.abs_link`` function +``atom_path`` TranslatableSetting<str> ``ATOM_PATH`` setting +``author_pages_generated`` bool False +``blog_author`` TranslatableSetting<str> ``BLOG_AUTHOR`` setting +``blog_email`` str ``BLOG_EMAIL`` setting +``blog_description`` TranslatableSetting<str> ``BLOG_DESCRIPTION`` setting +``blog_title`` TranslatableSetting<str> ``BLOG_TITLE`` setting +``blog_url`` str ``SITE_URL`` setting +``body_end`` TranslatableSetting<str> ``BODY_END`` setting +``colorize_str_from_base_color`` function ``utils.colorize_str_from_base_color`` function +``color_hsl_adjust_hex`` function ``utils.color_hsl_adjust_hex`` function +``comment_system_id`` str ``COMMENT_SYSTEM_ID`` setting +``comment_system`` str ``COMMENT_SYSTEM`` setting +``content_footer`` TranslatableSetting<str> ``CONTENT_FOOTER`` setting +``data`` dict data files (from the ``data/`` directory) +``date_fanciness`` int ``DATE_FANCINESS`` setting +``date_format`` TranslatableSetting<str> ``DATE_FORMAT`` setting +``exists`` function ``Nikola.file_exists`` function +``extra_head_data`` TranslatableSetting<str> ``EXTRA_HEAD_DATA`` setting +``favicons`` tuple ``FAVICONS`` setting +``front_index_header`` TranslatableSetting<str> ``FRONT_INDEX_HEADER`` setting +``generate_atom`` bool ``GENERATE_ATOM`` setting +``generate_rss`` bool ``GENERATE_RSS`` setting +``global_data`` dict alias for ``data`` +``has_custom_css`` bool True if custom.css exists +``hidden_authors`` list<str> ``HIDDEN_AUTHORS`` setting +``hidden_categories`` list<str> ``HIDDEN_CATEGORIES`` setting +``hidden_tags`` list<str> ``HIDDEN_TAGS`` setting +``hide_sourcelink`` bool ``SHOW_SOURCELINK`` setting, negated +``index_display_post_count`` int ``INDEX_DISPLAY_POST_COUNT`` setting +``index_file`` str ``INDEX_FILE`` setting +``js_date_format`` TranslatableSetting<str> ``MOMENTJS_DATE_FORMAT`` setting, JSONified +``katex_auto_render`` str ``KATEX_AUTO_RENDER`` setting +``license`` TranslatableSetting<str> ``LICENSE`` setting +``logo_url`` str ``LOGO_URL`` setting +``luxon_date_format`` TranslatableSetting<str> ``LUXON_DATE_FORMAT`` setting, JSONified +``mathjax_config`` str ``MATHJAX_CONFIG`` setting +``messages`` dict<dict<str, str>> translated messages (``{language: {english: translated}}``) +``meta_generator_tag`` bool ``META_GENERATOR_TAG`` setting +``momentjs_locales`` defaultdict<str, str> dictionary of available Moment.js locales +``multiple_authors_per_post`` bool ``MULTIPLE_AUTHORS_PER_POST`` setting +``navigation_links`` TranslatableSetting ``NAVIGATION_LINKS`` setting +``navigation_alt_links`` TranslatableSetting ``NAVIGATION_ALT_LINKS`` setting +``needs_ipython_css`` bool whether or not Jupyter CSS is needed by this site +``posts_sections`` bool ``POSTS_SECTIONS`` setting +``posts_section_are_indexes`` bool ``POSTS_SECTIONS_ARE_INDEXES`` setting +``posts_sections_are_indexes`` bool ``POSTS_SECTIONS_ARE_INDEXES`` setting +``posts_section_colors`` TranslatableSetting ``POSTS_SECTION_COLORS`` setting +``posts_section_descriptions`` Tss ``POSTS_SECTION_DESCRIPTIONS`` setting +``posts_section_from_meta`` bool ``POSTS_SECTION_FROM_META`` setting +``posts_section_name`` TranslatableSetting<str> ``POSTS_SECTION_NAME`` setting +``posts_section_title`` TranslatableSetting<str> ``POSTS_SECTION_TITLE`` setting +``rel_link`` function ``Nikola.rel_link`` function +``rss_link`` str ``RSS_LINK`` setting +``search_form`` TranslatableSetting<str> ``SEARCH_FORM`` setting +``set_locale`` function ``LocaleBorg.set_locale`` function (or None if not available) +``show_blog_title`` bool ``SHOW_BLOG_TITLE`` setting +``show_sourcelink`` bool ``SHOW_SOURCELINK`` setting +``site_has_comments`` bool whether or not a comment system is configured +``social_buttons_code`` TranslatableSetting<str> ``SOCIAL_BUTTONS_CODE`` setting +``sort_posts`` function ``utils.sort_posts`` function +``smartjoin`` function ``utils.smartjoin`` function +``colorize_str`` function ``utils.colorize_str`` function +``template_hooks`` dict<str, TemplateHookRegistry> Template hooks registered by plugins +``theme_color`` str ``THEME_COLOR`` setting +``theme_config`` dict ``THEME_CONFIG`` setting +``timezone`` tzinfo Timezone object (represents the configured timezone) +``translations`` dict<str, str> ``TRANSLATIONS`` setting +``twitter_card`` dict ``TWITTER_CARD`` setting, defaults to an empty dictionary +``url_replacer`` function ``Nikola.url_replacer`` function +``url_type`` str ``URL_TYPE`` setting +``use_bundles`` bool ``USE_BUNDLES`` setting +``use_cdn`` bool ``USE_CDN`` setting +``use_katex`` bool ``USE_KATEX`` setting +``subtheme`` str? ``THEME_REVEAL_CONFIG_SUBTHEME`` setting (only if set — deprecated) +``transition`` str? ``THEME_REVEAL_CONFIG_TRANSITION`` setting (only if set — deprecated) +================================== ================================== ================================================================================ + +Per-page local variables +------------------------ + +Those variables are available on all pages, but their contents are dependent on page contents. + +.. class:: table table-bordered table-striped + +================== ========== =============================================================== +Name Type Description +================== ========== =============================================================== +``description`` str Description of the page +``is_rtl`` bool Whether or not the language is left-to-right +``lang`` str Current language +``pagekind`` list<str> List of strings that identify the type of this page `(docs)`__ +``title`` str Title of the page (taken from post, config, etc.) +``formatmsg`` function Wrapper over ``%`` string formatting +``striphtml`` function Strips HTML tags (Mako only) +``crumbs`` list Breadcrumbs for this page +================== ========== =============================================================== + +__ https://getnikola.com/theming.html#identifying-and-customizing-different-kinds-of-pages-with-a-shared-template + +Variables available in post pages (``post.tmpl``, ``page.tmpl`` etc.) +--------------------------------------------------------------------- + +.. class:: table table-bordered table-striped + +====================== ========== ======================================================== +Name Type Description +====================== ========== ======================================================== +``post`` Post The post object +``permalink`` str Permanent link to the post +``enable_comments`` bool True for posts, ``COMMENTS_IN_PAGES`` setting for pages +====================== ========== ======================================================== + +Variables available in post lists +--------------------------------- + +.. class:: table table-bordered table-striped + +============== ============= ============================================== +Name Type Description +============== ============= ============================================== +``posts`` list<Post> List of post objects that appear in this list +``prevlink`` str Link to previous page +``nextlink`` str Link to next page +============== ============= ============================================== + + +Variables available in indexes +------------------------------ + +.. class:: table table-bordered table-striped + +============================== ============== =============================================================================== +Name Type Description +============================== ============== =============================================================================== +``posts`` list<Post> List of post objects that appear in this list +``index_teasers`` bool ``INDEX_TEASERS`` setting +``show_index_page_navigation`` bool ``SHOW_INDEX_PAGE_NAVIGATION`` setting +``current_page`` int Number of current page +``page_links`` list<str> Links to different pages +``prevlink`` str Link to previous page +``nextlink`` str Link to next page +``prevfeedlink`` str Link to previous page as an Atom feed +``nextfeedlink`` str Link to next page as an Atom feed +``prev_next_links_reversed`` bool Whether or not previous and next links should be reversed (``INDEXES_STATIC``) +``is_frontmost_index`` bool Whether or not this is the front-most index (page 0) +============================== ============== =============================================================================== + +Variables available in taxonomies +--------------------------------- + +Variable names enclosed in ``<>`` are dependent on the taxonomy. + +.. class:: table table-bordered table-striped + +====================== ========================================== =================== +Taxonomy Variable Value +====================== ========================================== =================== +``archive`` ``overview_page_variable_name`` ``archive`` +``author`` ``overview_page_variable_name`` ``authors`` +``category`` ``overview_page_variable_name`` ``categories`` +``category`` ``overview_page_items_variable_name`` ``cat_items`` +``category`` ``overview_page_hierarchy_variable_name`` ``cat_hierarchy`` +``index`` ``overview_page_variable_name`` unavailable (None) +``page_index_folder`` ``overview_page_variable_name`` ``page_folder`` +``section_index`` ``overview_page_variable_name`` ``sections`` +``tag`` ``overview_page_variable_name`` ``tags`` +``tag`` ``overview_page_items_variable_name`` ``items`` +====================== ========================================== =================== + +Templates and settings used by taxonomies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: table table-bordered table-striped + +====================== ================== ================================== ====================================== ============================================== ====================================== ============================== ============================== +Taxonomy Has hierarchy List (one classification) template Index (one classification) template Overview (list of classifications) template Subcategories list template List is an index Show as list of subcategories +====================== ================== ================================== ====================================== ============================================== ====================================== ============================== ============================== +(default settings) no tagindex.tmpl tagindex.tmpl list.tmpl taxonomy_list.tmpl (does not exist) no no +``archive`` yes (0-3 levels) list_post.tmpl archiveindex.tmpl list.tmpl list.tmpl ``ARCHIVES_ARE_INDEXES`` ``not CREATE_FULL_ARCHIVES`` +``author`` no author.tmpl authorindex.tmpl authors.tmpl n/a ``AUTHOR_PAGES_ARE_INDEXES`` no +``category`` yes tag.tmpl tagindex.tmpl tags.tmpl (with tags) n/a ``CATEGORY_PAGES_ARE_INDEXES`` n/a +``index`` no n/a index.tmpl n/a n/a yes no +``page_index_folder`` yes list.tmpl n/a n/a n/a no no +``section_index`` no list.tmpl sectionindex.tmpl n/a n/a ``POSTS_SECTIONS_ARE_INDEXES`` no +``tag`` no tag.tmpl tagindex.tmpl tags.tmpl (with categories) n/a ``TAG_PAGES_ARE_INDEXES`` no +====================== ================== ================================== ====================================== ============================================== ====================================== ============================== ============================== + +Classification overviews +~~~~~~~~~~~~~~~~~~~~~~~~ + +Hierarchy-related variables are available if and only if ``has_hierarchy`` is True. + +.. class:: table table-bordered table-striped + +================================================================== ====== ============================================================================================================================================================================== +Name Type Description +================================================================== ====== ============================================================================================================================================================================== +``<overview_page_variable_name>`` str List of classifications +``<overview_page_items_variable_name>`` list List of items *(name, link)* +``<overview_page_items_variable_name + "_with_postcount">`` list List of items *(name, link, number of posts)* +``<overview_page_hierarchy_variable_name>`` list? List of hierarchies *(name, full name, path, link, indent levels, indent to change before, indent to change after)* +``<overview_page_hierarchy_variable_name + "_with_postcount">`` list? List of hierarchies, with added counts *(name, full name, path, link, indent levels, indent to change before, indent to change after, number of children, number of posts)* +``has_hierarchy`` bool Value of ``has_hierarchy`` for the taxonomy +``permalink`` str Permanent link to page +================================================================== ====== ============================================================================================================================================================================== + +Classification pages (lists) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: table table-bordered table-striped + +=================== ============== ============================================================= +Name Type Description +=================== ============== ============================================================= +``kind`` str The classification name +``items`` list? List of items for ``list.tmpl`` *(title, permalink, None)* +``posts`` list<Post>? List of items for other templates +``permalink`` str Permanent link to page +``other_languages`` list<tuple> List of triples ``(other_lang, other_classification, title)`` +=================== ============== ============================================================= + +Index-style classification pages have ``kind`` in addition to the usual index variables. + +Subclassification page +~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: table table-bordered table-striped + +=================== =========== ============================================================= +Name Type Description +=================== =========== ============================================================= +``items`` list? List of items +``permalink`` str Permanent link to page +``other_languages`` list<tuple> List of triples ``(other_lang, other_classification, title)`` +=================== =========== ============================================================= + +Hierarchical lists +~~~~~~~~~~~~~~~~~~ + +The indenting information can be used to render the items as a tree. The values have the following meanings: + + * ``indent levels`` is a list of pairs ``(current_i, count_i)`` giving the current position (``0``, ..., ``count_i-1``) and maximum (``count_i``) in the hierarchy level ``i``; + * ``indent to change before`` is the difference of hierarchy levels between the previous and the current item; positive values indicate that the current item is indented further in and can be used to open HTML tags before the item; + * ``indent to change after`` is the difference of hierarchy levels between the current and the next item; negative values indicate that the current item is indented further in and can be used to close HTML tags after the item. + +Example: + +.. code:: text + + +--- levels:[(0,3)], before:1, after:0 + +-+- levels:[(1,3)], before:0, after:1 + | +--- levels:[(1,3), (0,2)], before:1, after:0 + | +-+- levels:[(1,3), (1,2)], before:0, after:1 + | +--- levels:[(1,3), (1,2), (0, 1)], before:1, after:-2 + +-+- levels:[(2,3)], before:-2, after:1 + +- levels:[(2,3), (0,1)], before:1, after:-2 + +See ``tags.tmpl`` in the base themes for examples on how to render a tree as nested unordered lists in HTML. + +Variables available in archives +------------------------------- + +The archive navigation variables are available only if ``create_archive_navigation`` is True. + +.. class:: table table-bordered table-striped + +============================== ============== ======================================================================== +Name Type Description +============================== ============== ======================================================================== +``kind`` str Always ``"archive"`` +``archive_name`` str? Name of the archive (only if using indexes) +``create_archive_navigation`` bool ``CREATE_ARCHIVE_NAVIGATION`` setting +``has_archive_navigation`` bool Whether or not archive navigation is available +``up_archive`` str? Link to the archive one level up +``up_archive_name`` str? Name of the archive one level up +``previous_archive`` str? Link to the previous archive +``previous_archive_name`` str? Name of the previous archive +``next_archive`` str? Link to the next archive +``next_archive_name`` str? Name of the next archive +``archive_nodelevel`` int? Level of the archive +``other_languages`` list List of tuples ``(lang, path, name)`` of same archive in other languages +============================== ============== ======================================================================== + + +Variables available in author pages +----------------------------------- + +.. class:: table table-bordered table-striped + +=================== =========== ========================================================================= +Name Type Description +=================== =========== ========================================================================= +``kind`` str Always ``"author"`` +``author`` str Author name +``rss_link`` str Link to RSS (HTML fragment) +``other_languages`` list<tuple> List of tuples ``(lang, author, name)`` of same author in other languages +=================== =========== ========================================================================= + + +Variables available in category pages +------------------------------------- + +.. class:: table table-bordered table-striped + +=================== =========== ============================================================================= +Name Type Description +=================== =========== ============================================================================= +``kind`` str Always ``"category"`` +``category`` str Category name +``category_path`` list<str> Category hierarchy +``rss_link`` str? Link to RSS (HTML fragment, only if using indexes) +``subcategories`` list List of subcategories (contains *name, link* tuples) +``tag`` str Friendly category name +``other_languages`` list<tuple> List of tuples ``(lang, category, name)`` of same category in other languages +=================== =========== ============================================================================= + +Variables available in galleries +-------------------------------- + +.. class:: table table-bordered table-striped + +====================== ========== =============================================================================== +Name Type Description +====================== ========== =============================================================================== +``crumbs`` list Breadcrumbs for this page +``enable_comments`` bool Whether or not comments are enabled in galleries +``folders`` list List of folders (contains *path, title* tuples) +``permalink`` str Permanent link to this page +``photo_array`` list Photo array (contains dicts with image data: *url, url_thumb, title, size{w, h}*) +``photo_array_json`` str Photo array in JSON format +``post`` Post? The Post object for this gallery +``thumbnail_size`` int ``THUMBNAIL_SIZE`` setting +====================== ========== =============================================================================== + + +Variables available in listings +------------------------------- + +.. class:: table table-bordered table-striped + +================== ========== ======================================== +Name Type Description +================== ========== ======================================== +``code`` str Highlighted source code (HTML fragment) +``crumbs`` list Breadcrumbs for this page +``folders`` list<str> List of subfolders +``files`` list<str> List of files in the folder +``source_link`` str Link to the source file +================== ========== ======================================== + +Variables available in sections +------------------------------- + +.. class:: table table-bordered table-striped + +=================== =========== =========================================================================== +Name Type Description +=================== =========== =========================================================================== +``section`` str Section name (internal) +``kind`` str Always ``"section"`` +``other_languages`` list<tuple> List of tuples ``(lang, section, name)`` of same section in other languages +=================== =========== =========================================================================== + +Variables available in tag pages +-------------------------------- + +.. class:: table table-bordered table-striped + +=================== =========== =================================================================== +Name Type Description +=================== =========== =================================================================== +``kind`` str Always ``"tag"`` +``tag`` str Tag name +``other_languages`` list<tuple> List of tuples ``(lang, tag, name)`` of same tag in other languages +=================== =========== =================================================================== + +Variables available in the “Tags and categories” page (``tags.tmpl``) +--------------------------------------------------------------------- + +.. class:: table table-bordered table-striped + +============== ====== =========================================================================================================== +Name Type Description +============== ====== =========================================================================================================== +``items`` list Tags *(name, link)* +``cat_items`` list Categories *(name, full name, path, link, indent levels, indent to change before, indent to change after)* +============== ====== =========================================================================================================== + +For more details about hierarchies, see `Hierarchical lists`_ + +Variables available in shortcodes +--------------------------------- + +*The global context is available in templated shortcodes.* + +.. class:: table table-bordered table-striped + +================== ========== =========================================================================== +Name Type Description +================== ========== =========================================================================== +``lang`` str Current language +``_args`` list<str> Arguments given to the shortcode +``data`` str Shortcode contents +``post`` Post Post object (if available) +``filename`` str? file name, if ``shortcode_function.nikola_shortcode_pass_filename = True`` +================== ========== =========================================================================== + +Variables available in post lists +--------------------------------- + +*The global context is NOT available in post lists.* + +.. class:: table table-bordered table-striped + +================== ========== ===================================== +Name Type Description +================== ========== ===================================== +``posts`` list<Post> Posts that are on the list +``lang`` str Current language +``date_format`` str The date format for current language +``post_list_id`` str GUID of post list +``messages`` dict The messages dictionary +``_link`` function ``Nikola.link`` function +================== ========== ===================================== + +Post object attributes +---------------------- + +*Usable anywhere post objects are accessible.* + +This list only includes variables that make sense for templates. Some function signatures have been shortened to save space, ``?`` means the argument has default value. + +More docs: `nikola.post.Post on ReadTheDocs <http://nikola.readthedocs.io/en/latest/nikola/#nikola.post.Post>`_. Check out the source of the Post class as well. + +=================================================================== ========== ============================================================= +Name Type Description +=================================================================== ========== ============================================================= +``alltags`` list<str> All tags for the post +``author(lang=None)`` str Localized author or ``BLOG_AUTHOR`` +``base_path`` str ``cache`` path with local ``os.sep`` +``category_from_destpath`` bool If category was set by ``CATEGORY_DESTPATH_AS_DEFAULT`` +``data(key, lang=None)`` ? Access to post data +``date`` datetime Date of post (from meta) +``description(key, lang=None)`` str Description of post (from meta) +``destination_path(lang?, extension?, sep?)`` str Destination path of post +``formatted_date(date_format, date=None)`` str Format a date (default: post date) +``formatted_updated(date_format)`` str Format the last update date +``guid(lang=None)`` str GUID of post (used for feeds) +``has_math`` bool If the post has math +``has_pretty_url(lang)`` bool If the post has a pretty URL +``is_draft`` bool If the post is a draft +``is_post`` bool If the post is not a page +``is_private`` bool If the post is private +``is_translation_available(lang)`` bool If the post is available in (translated to) a given language +``is_two_file`` bool If the post uses two-file metadata +``meta(key, lang=None)`` ? Metadata of the post (assumes current language) +``next_post`` Post Next post in the order +``paragraph_count`` int Paragraph count for a post +``permalink(lang?, absolute?, extension?, query?)`` str Permanent link for a post +``post_name`` str Source path, without extension +``post_status`` str Post status meta field (published, featured, private, draft) +``prev_post`` Post Previous post in the order +``previewimage`` str Preview image of the post +``publish_later`` bool True if the post is not yet published (due to date) +``reading_time`` int Approximate reading time in minutes (220 wpm) +``remaining_paragraph_count`` int Paragraph count after the teaser +``remaining_reading_time`` int Reading time after the teaser +``source_link`` str Absolute link to the post's source +``tags`` list<str> Tags for the current language +``tags_for_language(lang)`` list<str> Tags for a given language +``text(lang?, teaser_only?, strip_html?, show_read_more_link?, …)`` str The text of a post +``title(lang=None)`` str Localized title of post +``translated_to`` list<str> List of languages of post +``updated`` datetime Date of last update (from meta) +``use_in_feeds`` bool If this post should be displayed in feeds +=================================================================== ========== ============================================================= + +.. vim: nowrap textwidth=0 diff --git a/docs/theming.txt b/docs/theming.rst index a11306c..c9fb8c2 100644 --- a/docs/theming.txt +++ b/docs/theming.rst @@ -6,20 +6,18 @@ .. description: .. author: The Nikola Team -Theming Nikola -============== - -:Version: 7.8.1 +:Version: 8.1.2 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> -.. class:: alert alert-info pull-right +.. class:: alert alert-primary float-md-right .. contents:: .. class:: lead This document is a reference about themes. If you want a tutorial, please read -`Creating a Theme <creating-a-theme.html>`_ +:doc:`Creating a Theme <creating-a-theme>`. If you’re looking for a ready-made +theme for your site, check out the `Themes Index <https://themes.getnikola.com/>`_. The Structure ------------- @@ -30,17 +28,21 @@ of your site, one folder per theme. The folder name is the theme name. A Nikola theme consists of the following folders (they are *all* optional): assets - This is where you would put your CSS, Javascript and image files. It will be copied + This is where you would put your CSS, JavaScript and image files. It will be copied into ``output/assets`` when you build the site, and the templates will contain - references to them. + references to them. The default subdirectories are ``css``, ``js``, ``xml`` + and ``fonts`` (Bootstrap). - 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 highlighting and reStructuredText, and a - minified copy of jQuery. + The included themes use `Bootstrap <https://getbootstrap.com/>`_, + `baguetteBox <https://feimosi.github.io/baguetteBox.js/>`_, `Justified Layout by Flickr + <http://flickr.github.io/justified-layout/>`_ and `Luxon + <https://moment.github.io/luxon/>`_, so they are in assets, along with CSS files for + syntax highlighting, reStructuredText and Jupyter, as well as a minified + copy of jQuery. If you want to base your theme on other frameworks (or on no framework at all) - just remember to put there everything you need for deployment. + just remember to put there everything you need for deployment. (Not all of + the listed assets are used by ``base``) templates This contains the templates used to generate the pages. While Nikola will use a @@ -51,76 +53,164 @@ messages Nikola tries to be multilingual. This is where you put the strings for your theme so that it can be translated into other languages. -less - Files to be compiled into CSS using `LESS <http://lesscss.org/>`__ - -sass - Files to be compiled into CSS using `Sass <http://sass-lang.com/>`__ +less, sass + Files to be compiled into CSS using LESS and Sass (both require plugins) This mandatory file: -parent - A text file that, on its first line, contains the name of the **parent theme**. - Any resources missing on this theme, will be looked up in the parent theme - (and then in the grandparent, etc). - - The ``parent`` is so you don't have to create a full theme each time: just create an - empty theme, set the parent, and add the bits you want modified. - - I recommend this: - - * If your theme uses Bootstrap 3, inherit the ``bootstrap3`` theme. - * If your theme uses Jinja as a template engine, inherit ``base-jinja`` - or ``bootstrap3-jinja`` - * In any other case, inherit ``base``. +<theme>.theme + An INI file containing theme meta data. The file format is described in + detail below, in the `Theme meta files`_ section. And these optional files: -engine - A text file which, on the first line, contains the name of the template engine - this theme needs. Currently supported values are "mako" and "jinja". +parent, engine + One-line text files that contain the names of parent and engine themes, + respectively. Those are needed for older versions (Nikola v7.8.5 and + older). bundles - A text file containing a list of files to be turned into bundles using WebAssets. - For example:: + A `config <https://docs.python.org/3/library/configparser.html>`_ file + containing a list of files to be turned into bundles. For example: + + .. code:: ini - assets/css/all.css=bootstrap.css,rst.css,code.css,colorbox.css,custom.css + assets/css/all.css= + bootstrap.min.css, + rst_base.css, + nikola_rst.css, + code.css, + baguetteBox.min.css, + theme.css, + custom.css, This creates a file called "assets/css/all.css" in your output that is the combination of all the other file paths, relative to the output file. This makes the page much more efficient because it avoids multiple connections to the server, at the cost of some extra difficult debugging. - WebAssets supports bundling CSS and JS files. + Bundling applies to CSS and JS files. Templates should use either the bundle or the individual files based on the ``use_bundles`` variable, which in turn is set by the ``USE_BUNDLES`` option. +Theme meta files +---------------- + +As of Nikola v7.8.6, Nikola uses meta files for themes. Those are INI files, +with the same name as your theme, and a ``.theme`` extension, eg. +``bootstrap3.theme``. Here is an example, from the bootstrap3 theme: + +.. code:: ini + + [Theme] + engine = mako + parent = base + author = The Nikola Contributors + author_url = https://getnikola.com/ + based_on = Bootstrap 3 <http://getbootstrap.com/> + license = MIT + tags = bootstrap + + [Family] + family = bootstrap3 + jinja_version = bootstrap3-jinja + variants = bootstrap3-gradients, bootstrap3-gradients-jinja + + [Nikola] + bootswatch = True + +The following keys are currently supported: + +* ``Theme`` — contains information about the theme. + + * ``engine`` — engine used by the theme. Should be ``mako`` or ``jinja``. + * ``parent`` — the parent theme. Any resources missing in this theme, will be + looked up in the parent theme (and then in the grandparent, etc). + + The parent is so you don’t have to create a full theme each time: just + create an empty theme, set the parent, and add the bits you want modified. + You **must** define a parent, otherwise many features won’t work due to + missing templates, messages, and assets. + + The following settings are recommended: + + * If your theme uses Bootstrap 3, inherit the ``bootstrap3`` theme. + * If your theme uses Jinja as a template engine, inherit ``base-jinja`` + or ``bootstrap3-jinja`` + * In any other case, inherit ``base``. + + * ``author``, ``author_url`` — used to identify theme author. + * ``based_on`` — optional list of inspirations, frameworks, etc. used in the + theme. Should be comma-separated, the format ``Name <URL>`` is recommended. + * ``license`` — theme license. Pick MIT if you have no preference. + * ``tags`` — optional list of tags (comma-separated) to describe the theme. + +* ``Family`` — contains information about other related themes. All values + optional. (Do not use unless you have related themes.) + + * ``family`` — the name of the main theme in a family, which is also used as + the family name. + * ``mako_version``, ``jinja_version`` — name of the mako/jinja version of the + theme. + * ``variants`` — comma-separated list of stylistic variants (other than the + mako/jinja version listed above) + +* ``Nikola`` — Nikola-specific information, currently optional. + + * ``bootswatch`` — whether or not theme supports Bootswatch styling (optional, + defaults to False) + * ``ignored_assets`` — comma-separated list of assets to ignore (relative to + the ``assets/`` directory, eg. ``css/theme.css``) + Templates --------- In templates there is a number of files whose name ends in ``.tmpl``. Those are the -theme's page templates. They are done using the `Mako <http://makotemplates.org>`_ +theme’s page templates. They are done using the `Mako <http://makotemplates.org>`_ or `Jinja2 <http://jinja.pocoo.org>`_ template languages. If you want to do a theme, you should learn one first. What engine is used by the theme is declared in the ``engine`` file. -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 +Both template engines have 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 so ``post.tmpl`` only define the content, and the layout is inherited from ``base.tmpl``. +Another concept is theme inheritance. You do not need to duplicate all the +default templates in your theme — you can just override the ones you want +changed, and the rest will come from the parent theme. (Every theme needs a +parent.) + +Apart from the `built-in templates`_ listed below, you can add other templates for specific +pages, which the user can then use in his ``POSTS`` or ``PAGES`` option in +``conf.py``. 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. + +If you want to modify (override) a built-in template, use ``nikola theme -c +<name>.tmpl``. This command will copy the specified template file to the +``templates/`` directory of your currently used theme. + +Keep in mind that your theme is *yours*, so you can require whatever data you +want (eg. you may depend on specific custom ``GLOBAL_CONTEXT`` variables, or +post meta attributes). You don’t need to keep the same theme structure as the +default themes do (although many of those names are hardcoded). Inheriting from +at least ``base`` (or ``base-jinja``) is heavily recommended, but not strictly +required (unless you want to share it on the Themes Index). + +Built-in templates +------------------ + These are the templates that come with the included themes: ``base.tmpl`` - This template defines the basic page layout for the site. It's mostly plain HTML + This template defines the basic page layout for the site. It’s mostly plain HTML but defines a few blocks that can be re-defined by inheriting templates. It has some separate pieces defined in ``base_helper.tmpl``, @@ -131,16 +221,28 @@ These are the templates that come with the included themes: Template used to render the multipost indexes. The posts are in a ``posts`` variable. Some functionality is in the ``index_helper.tmpl`` helper template. +``archive_navigation_helper.tmpl`` (internal) + Code that implements archive navigation (previous/up/next). Included by + archive templates. + ``archiveindex.tmpl`` Used to display archives, if ``ARCHIVES_ARE_INDEXES`` is True. - By default, it just inherits ``index.tmpl``. + By default, it just inherits ``index.tmpl``, with added archive navigation + and feeds. -``comments_helper.tmpl`` +``author.tmpl`` + Used to display author pages. + +``authorindex.tmpl`` + Used to display author indexes, if ``AUTHOR_PAGES_ARE_INDEXES`` is True. + By default, it just inherits ``index.tmpl``, with added feeds. + +``comments_helper.tmpl`` (internal) This template handles comments. You should probably never touch it :-) It uses a bunch of helper templates, one for each supported comment system (all of which start with ``comments_helper``) -``crumbs.tmpl``, ``slides.tmpl`` +``ui_helper.tmpl``, ``pagination_helper.tmpl`` These templates help render specific UI items, and can be tweaked as needed. ``gallery.tmpl`` @@ -158,11 +260,12 @@ These are the templates that come with the included themes: + ``title``: The title of the image. + ``size``: A dict containing ``w`` and ``h``, the real size of the thumbnail. - * ``photo_array_json``: a JSON dump of photo_array, used in the bootstrap theme by flowr.js + * ``photo_array_json``: a JSON dump of photo_array, used by the + ``justified-layout`` script ``list.tmpl`` Template used to display generic lists of links, which it gets in ``items``, - a list of (text, link) elements. + a list of *(text, link, count)* elements. ``list_post.tmpl`` Template used to display generic lists of posts, which it gets in ``posts``. @@ -170,6 +273,9 @@ These are the templates that come with the included themes: ``listing.tmpl`` Used to display code listings. +``math_helper.tmpl`` (internal) + Used to add MathJax/KaTeX code to pages. + ``post.tmpl`` Template used by default for blog posts, gets the data in a ``post`` object which is an instance of the Post class. Some functionality is in the @@ -178,7 +284,11 @@ These are the templates that come with the included themes: ``post_list_directive.tmpl`` Template used by the ``post_list`` reStructuredText directive. -``story.tmpl`` +``sectionindex.tmpl`` + Used to display section indexes, if ``POST_SECTIONS_ARE_INDEXES`` is True. + By default, it just inherits ``index.tmpl``, with added feeds. + +``page.tmpl`` Used for pages that are not part of a blog, usually a cleaner, less intrusive layout than ``post.tmpl``, but same parameters. @@ -187,18 +297,17 @@ These are the templates that come with the included themes: ``tagindex.tmpl`` Used to show the contents of a single tag or category, if ``TAG_PAGES_ARE_INDEXES`` is True. - By default, it just inherits ``index.tmpl``. + By default, it just inherits ``index.tmpl``, with added feeds and some + extra features. ``tags.tmpl`` Used to display the list of tags and categories. -You can add other templates for specific pages, which the user can then use in his ``POSTS`` -or ``PAGES`` option in ``conf.py``. Also, keep in mind that your theme is yours, -there is no reason why you would need to maintain the inheritance as it is, or not -require whatever data you want. +Variables available in templates +-------------------------------- -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. +The full, complete list of variables available in templates is maintained in a separate +document: `Template variables <https://getnikola.com/template-variables.html>`_ Customizing themes to user color preference and section colors -------------------------------------------------------------- @@ -217,27 +326,34 @@ 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: +color can be made lighter using this code: .. code:: html+mako - <span style="color:${color_hsl_adjust_hex(theme_color, adjust_l=0.05)}"> + <!-- Mako --> + <span style="color: ${color_hsl_adjust_hex(theme_color, adjust_l=0.05)}"> + +.. code:: html+jinja + + <!-- Jinja2 --> + <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 +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 +the ``base_helper.tmpl`` is used in all pages, ``index.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 +(archives, author pages, and tag pages), and others again to the front page and in every post pages: .. code:: html+mako + <!-- Mako --> <head> … % if 'index' in pagekind: @@ -253,6 +369,25 @@ and in every post pages: % endif </head> +.. code:: html+jinja + + <!-- Jinja2 --> + <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`` @@ -260,16 +395,30 @@ depending on what you want to achieve. .. code:: html+mako + <!-- Mako --> % if 'index' in pagekind: - % if 'author_page' in postkind: + % if 'author_page' in pagekind: <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: + % elif 'tag_page' in pagekind: <p>This is a filtered selection of posts tagged “${tag}”, visit the <a href="/">front page</a> to see all posts.</p> % endif % endif +.. code:: html+jinja + + <!-- Jinja2 --> + {% if 'index' in pagekind %} + {% if 'author_page' in pagekind %} + <p>These posts were written by {{ author }}. See posts by all + authors on the <a href="/">front page</a>.</p> + {% elif 'tag_page' in pagekind %} + <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: |