diff options
Diffstat (limited to 'docs')
24 files changed, 169 insertions, 142 deletions
diff --git a/docs/extending.rst b/docs/extending.rst index db72509..395d839 100644 --- a/docs/extending.rst +++ b/docs/extending.rst @@ -6,7 +6,7 @@ .. description: .. author: The Nikola Team -:Version: 8.1.3 +:Version: 8.2.0 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> .. class:: alert alert-primary float-md-right @@ -492,6 +492,14 @@ Does nothing specific, can be used to modify the site object (and thus the confi 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>`__ + +CommentSystem Plugins +--------------------- + +Can be used to add a new comment system. (It doesn’t do anything by itself.) It’s expected to provide templates named ``comment_helper_foo.tmpl``. + +Example plugin: `cactuscomments <https://github.com/getnikola/plugins/tree/master/v8/cactuscomments>`__ + Shortcode Plugins ----------------- diff --git a/docs/man/nikola.1.gz b/docs/man/nikola.1.gz Binary files differindex 5361cd0..c6b9ec8 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 611b189..470fe48 100644 --- a/docs/man/nikola.rst +++ b/docs/man/nikola.rst @@ -6,7 +6,7 @@ Nikola A Static Site and Blog Generator -------------------------------- -:Version: Nikola 8.1.3 +:Version: Nikola 8.2.0 :Manual section: 1 :Manual group: User Commands diff --git a/docs/manual.rst b/docs/manual.rst index 0dc56cf..f4ab0f0 100644 --- a/docs/manual.rst +++ b/docs/manual.rst @@ -7,7 +7,7 @@ .. has_math: true .. author: The Nikola Team -:Version: 8.1.3 +:Version: 8.2.0 .. class:: alert alert-primary float-md-right @@ -285,12 +285,12 @@ Basic title Title of the post. Using HTML/math in titles is not supported/recommended. - (required) + If not specified, the file name will be used. 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) + other symbols may cause issues in URLs. If not specified, the file name will be used. 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) @@ -652,14 +652,14 @@ default set to: 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 +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`). +``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/>`_ +add support for more languages, check out `the Transifex page for Nikola <https://www.transifex.com/projects/p/nikola/>`_. How does Nikola decide where posts should go? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1332,10 +1332,14 @@ emoji gist Show GitHub gists. If you know the gist's ID, this will show it in your site: - {{% raw %}}{{% gist 2395294 %}} {{% /raw %}} + .. code:: text + + {{% raw %}}{{% gist 2395294 %}} {{% /raw %}} listing - Used to show a code listing. Example:: + Used to show a code listing. Example: + + .. code:: text {{% raw %}}{{% listing hello.py python linenumbers=True %}}{{% /raw %}} @@ -1913,7 +1917,9 @@ Nikola supports several third party comment systems: * `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", "facebook", "isso" or "commento" +to one of "disqus", "intensedebate", "livefyre", "moot", "facebook", "isso", "commento" or "utterances". +It is also possible to use a comment system added by a plugin, see the +`Cactus Comments plugin <https://plugins.getnikola.com/#cactuscomments>`_ for an example. .. sidebar:: ``COMMENT_SYSTEM_ID`` @@ -2301,7 +2307,33 @@ filters.typogrify_sans_widont Same as typogrify without the widont filter filters.typogrify_custom - Run typogrify with a custom set or filters. Takes ``typogrify_filters`` (a list of callables) and ``ignore_tags`` (defaults to None). + Run typogrify with a custom set of filters or ignored HTML elements. Takes one or + both of the arguments ``typogrify_filters`` or ``ignore_tags``. ``typogrify_filters`` + must be a list of typogrify filter callables to run. ``ignore_tags`` must be a list + of strings specifying HTML tags, CSS classes (prefixed with ``.``), tag ``id`` names + (prefixed with ``#``), or a tag and a class or id. The following code should be + placed in ``conf.py``. + + .. code-block:: python + + from nikola.filters import typogrify_custom + import functools + # This filter will ignore HTML elements with the CSS class "typo-ignore" + FILTERS = { + ".html": [functools.partial(typogrify_custom, ignore_tags=[".typo-ignore"])] + } + # Alternatively, to specify ``typogrify_filters`` + import typogrify.filters as typo + FILTERS = { + ".html": [functools.partial(typogrify_custom, typogrify_filters=[typo.amp])] + } + + The default value for ``typogrify_filters`` is + ``[typo.amp, typo.widont, typo.smartypants, typo.caps, typo.initial_quotes]`` and the + default value for ``ignore_tags`` is ``["title", ".math"]``. If ``ignore_tags`` is + specified, the default tags will be appended to the supplied list. See the + `documentation <https://github.com/mintchaos/typogrify/blob/master/typogrify/filters.py#L8-L14>`__ + for the ``process_ignores`` function in typogrify. filters.minify_lines **THIS FILTER HAS BEEN TURNED INTO A NOOP** and currently does nothing. @@ -2390,9 +2422,10 @@ filters.deduplicate_ids 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 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: diff --git a/docs/social_buttons.rst b/docs/social_buttons.rst index 0612b04..f1bfc08 100644 --- a/docs/social_buttons.rst +++ b/docs/social_buttons.rst @@ -6,7 +6,7 @@ .. description: .. author: The Nikola Team -:Version: 8.1.3 +:Version: 8.2.0 .. class:: alert alert-primary float-md-right diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index 7d34890..15c1ac0 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -1,5 +1,9 @@ # -*- coding: utf-8 -*- -# + +from __future__ import unicode_literals +import os +import sys + # Nikola documentation build configuration file, created by # sphinx-quickstart on Sun Sep 22 17:43:37 2013. # @@ -15,19 +19,17 @@ # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -# sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, os.path.abspath(os.path.dirname(__file__))) # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. # needs_sphinx = '1.0' -from __future__ import unicode_literals - # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.mathjax'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.mathjax', 'nikola_titles_for_sphinx'] # extensions.append('sphinxcontrib.gist') # Add any paths that contain templates here, relative to this directory. @@ -36,6 +38,8 @@ templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' +source_parsers = {'.rst': 'nikola_titles_for_sphinx.NikolaTitlesRSTParser'} + # The encoding of source files. # source_encoding = 'utf-8-sig' @@ -51,9 +55,9 @@ copyright = '2012-2021, The Nikola Contributors' # built documents. # # The short X.Y version. -version = '8.1.3' +version = '8.2.0' # The full version, including alpha/beta/rc tags. -release = '8.1.3' +release = '8.2.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst index b448f76..f5d710e 100644 --- a/docs/sphinx/index.rst +++ b/docs/sphinx/index.rst @@ -22,6 +22,7 @@ visible in this version of Nikola docs. internals social_buttons path_handlers + support .. toctree:: :maxdepth: 5 diff --git a/docs/sphinx/nikola.packages.rst b/docs/sphinx/nikola.packages.rst index 916b3ec..ec65fb1 100644 --- a/docs/sphinx/nikola.packages.rst +++ b/docs/sphinx/nikola.packages.rst @@ -14,4 +14,3 @@ Subpackages nikola.packages.datecond nikola.packages.pygments_better_html - nikola.packages.tzlocal diff --git a/docs/sphinx/nikola.packages.tzlocal.rst b/docs/sphinx/nikola.packages.tzlocal.rst deleted file mode 100644 index 944562e..0000000 --- a/docs/sphinx/nikola.packages.tzlocal.rst +++ /dev/null @@ -1,35 +0,0 @@ -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.plugins.command.rst b/docs/sphinx/nikola.plugins.command.rst index 8c97515..831364f 100644 --- a/docs/sphinx/nikola.plugins.command.rst +++ b/docs/sphinx/nikola.plugins.command.rst @@ -145,4 +145,3 @@ nikola.plugins.command.version module :members: :undoc-members: :show-inheritance: - diff --git a/docs/sphinx/nikola.plugins.compile.markdown.rst b/docs/sphinx/nikola.plugins.compile.markdown.rst index b27da4e..3453a9e 100644 --- a/docs/sphinx/nikola.plugins.compile.markdown.rst +++ b/docs/sphinx/nikola.plugins.compile.markdown.rst @@ -32,4 +32,3 @@ nikola.plugins.compile.markdown.mdx\_podcast module :members: :undoc-members: :show-inheritance: - diff --git a/docs/sphinx/nikola.plugins.compile.rest.rst b/docs/sphinx/nikola.plugins.compile.rest.rst index 3f5d0bd..ef2c101 100644 --- a/docs/sphinx/nikola.plugins.compile.rest.rst +++ b/docs/sphinx/nikola.plugins.compile.rest.rst @@ -88,4 +88,3 @@ nikola.plugins.compile.rest.youtube module :members: :undoc-members: :show-inheritance: - diff --git a/docs/sphinx/nikola.plugins.compile.rst b/docs/sphinx/nikola.plugins.compile.rst index e89de36..ece9a1b 100644 --- a/docs/sphinx/nikola.plugins.compile.rst +++ b/docs/sphinx/nikola.plugins.compile.rst @@ -49,4 +49,3 @@ nikola.plugins.compile.php module :members: :undoc-members: :show-inheritance: - diff --git a/docs/sphinx/nikola.plugins.misc.rst b/docs/sphinx/nikola.plugins.misc.rst index 2cab79e..1a5aba9 100644 --- a/docs/sphinx/nikola.plugins.misc.rst +++ b/docs/sphinx/nikola.plugins.misc.rst @@ -24,4 +24,3 @@ nikola.plugins.misc.taxonomies\_classifier module :members: :undoc-members: :show-inheritance: - diff --git a/docs/sphinx/nikola.plugins.rst b/docs/sphinx/nikola.plugins.rst index f3e8680..86a4d7a 100644 --- a/docs/sphinx/nikola.plugins.rst +++ b/docs/sphinx/nikola.plugins.rst @@ -28,4 +28,3 @@ nikola.plugins.basic\_import module :members: :undoc-members: :show-inheritance: - diff --git a/docs/sphinx/nikola.plugins.task.rst b/docs/sphinx/nikola.plugins.task.rst index 327887a..cf6b71b 100644 --- a/docs/sphinx/nikola.plugins.task.rst +++ b/docs/sphinx/nikola.plugins.task.rst @@ -168,4 +168,3 @@ nikola.plugins.task.taxonomies module :members: :undoc-members: :show-inheritance: - diff --git a/docs/sphinx/nikola.plugins.task.sitemap.rst b/docs/sphinx/nikola.plugins.task.sitemap.rst deleted file mode 100644 index 774b09a..0000000 --- a/docs/sphinx/nikola.plugins.task.sitemap.rst +++ /dev/null @@ -1,10 +0,0 @@ -nikola.plugins.task.sitemap package -=================================== - -Module contents ---------------- - -.. automodule:: nikola.plugins.task.sitemap - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/sphinx/nikola.plugins.template.rst b/docs/sphinx/nikola.plugins.template.rst index 3d4b05e..984644b 100644 --- a/docs/sphinx/nikola.plugins.template.rst +++ b/docs/sphinx/nikola.plugins.template.rst @@ -24,4 +24,3 @@ nikola.plugins.template.mako module :members: :undoc-members: :show-inheritance: - diff --git a/docs/sphinx/nikola.rst b/docs/sphinx/nikola.rst index 28a15c3..710ca02 100644 --- a/docs/sphinx/nikola.rst +++ b/docs/sphinx/nikola.rst @@ -113,4 +113,3 @@ nikola.winutils module :members: :undoc-members: :show-inheritance: - diff --git a/docs/sphinx/nikola_titles_for_sphinx.py b/docs/sphinx/nikola_titles_for_sphinx.py new file mode 100644 index 0000000..06b76dc --- /dev/null +++ b/docs/sphinx/nikola_titles_for_sphinx.py @@ -0,0 +1,32 @@ +import sphinx.parsers +from docutils.statemachine import StringList +from typing import TYPE_CHECKING, Any, Dict, List, Type, Union + +if TYPE_CHECKING: + from sphinx.application import Sphinx + +TITLE_MARKER = ".. title:" + + +class NikolaTitlesRSTParser(sphinx.parsers.RSTParser): + def decorate(self, content: StringList) -> None: + """Preprocess reST content before parsing.""" + super().decorate(content) + for line in content[:20]: + if line.startswith(TITLE_MARKER): + title = line[len(TITLE_MARKER) :].strip() + fence = "=" * len(title) + content.insert(0, "", "<generated>", 0) + content.insert(0, fence, "<generated>", 0) + content.insert(0, title, "<generated>", 0) + content.insert(0, fence, "<generated>", 0) + + +def setup(app: "Sphinx") -> Dict[str, Any]: + app.add_source_parser(NikolaTitlesRSTParser, override=True) + + return { + "version": "0.1.0", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/docs/sphinx/requirements-docs.txt b/docs/sphinx/requirements-docs.txt index 443470f..22bb6a1 100644 --- a/docs/sphinx/requirements-docs.txt +++ b/docs/sphinx/requirements-docs.txt @@ -1,2 +1,2 @@ --r ../../requirements-extras.txt pyparsing>=2.0.2 +Sphinx>=4.2.0 diff --git a/docs/support.rst b/docs/support.rst index 52a7560..d25a4d4 100644 --- a/docs/support.rst +++ b/docs/support.rst @@ -4,7 +4,7 @@ .. description: Get help using Nikola, or contact us. .. author: The Nikola Team -:Version: 8.1.3 +:Version: 8.2.0 .. class:: alert alert-primary float-md-right @@ -14,9 +14,9 @@ Help and Support ================ 1. A `mailing list`_, nikola-discuss on Google Groups exists. -2. There is an IRC channel: #nikola on Freenode. You can find many - developers and volunteers (users) there which are there to provide - help, if they are around and read your message. The channel is +2. There’s an IRC channel: #nikola on Libera.Chat. You can + find many developers and volunteers (users) there which are there to provide + help, if they are around and read your message. The channels are `publicly logged <https://irclogs.getnikola.com/>`_. 3. You can also contact `@GetNikola <https://twitter.com/GetNikola>`_ on Twitter. diff --git a/docs/template-variables.rst b/docs/template-variables.rst index b9d3a9d..aeb254a 100644 --- a/docs/template-variables.rst +++ b/docs/template-variables.rst @@ -3,7 +3,7 @@ .. date: 2017-04-13 12:00:00 .. author: The Nikola Team -:Version: 8.1.3 +:Version: 8.2.0 :Author: Chris Warrick <chris@getnikola.com> Variables available in templates are listed below. @@ -41,45 +41,45 @@ Name Type Descript ================================== ================================== ================================================================================ ``_link`` function ``Nikola.link`` function ``abs_link`` function ``Nikola.abs_link`` function -``atom_path`` TranslatableSetting<str> ``ATOM_PATH`` setting +``atom_path`` TranslatableSetting[str] ``ATOM_PATH`` setting ``author_pages_generated`` bool False -``blog_author`` TranslatableSetting<str> ``BLOG_AUTHOR`` setting +``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_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 +``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 +``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 +``date_format`` TranslatableSetting[str] ``DATE_FORMAT`` setting ``exists`` function ``Nikola.file_exists`` function -``extra_head_data`` TranslatableSetting<str> ``EXTRA_HEAD_DATA`` setting +``extra_head_data`` TranslatableSetting[str] ``EXTRA_HEAD_DATA`` setting ``favicons`` tuple ``FAVICONS`` setting -``front_index_header`` TranslatableSetting<str> ``FRONT_INDEX_HEADER`` 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 +``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 +``js_date_format`` TranslatableSetting[str] ``MOMENTJS_DATE_FORMAT`` setting, JSONified ``katex_auto_render`` str ``KATEX_AUTO_RENDER`` setting -``license`` TranslatableSetting<str> ``LICENSE`` setting +``license`` TranslatableSetting[str] ``LICENSE`` setting ``logo_url`` str ``LOGO_URL`` setting -``luxon_date_format`` TranslatableSetting<str> ``LUXON_DATE_FORMAT`` setting, JSONified +``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}}``) +``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 +``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 @@ -90,24 +90,24 @@ Name Type Descript ``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 +``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 +``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 +``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 +``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 +``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 @@ -131,7 +131,7 @@ 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)`__ +``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) @@ -161,7 +161,7 @@ Variables available in post lists ============== ============= ============================================== Name Type Description ============== ============= ============================================== -``posts`` list<Post> List of post objects that appear in this list +``posts`` list[Post] List of post objects that appear in this list ``prevlink`` str Link to previous page ``nextlink`` str Link to next page ============== ============= ============================================== @@ -175,11 +175,11 @@ Variables available in indexes ============================== ============== =============================================================================== Name Type Description ============================== ============== =============================================================================== -``posts`` list<Post> List of post objects that appear in this list +``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 +``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 @@ -191,7 +191,7 @@ Name Type Description Variables available in taxonomies --------------------------------- -Variable names enclosed in ``<>`` are dependent on the taxonomy. +Variable names enclosed in ``{}`` are dependent on the taxonomy. .. class:: table table-bordered table-striped @@ -238,11 +238,11 @@ Hierarchy-related variables are available if and only if ``has_hierarchy`` is Tr ================================================================== ====== ============================================================================================================================================================================== 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)* +``{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 ================================================================== ====== ============================================================================================================================================================================== @@ -257,9 +257,9 @@ 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 +``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)`` +``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. @@ -274,7 +274,7 @@ 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)`` +``other_languages`` list[tuple] List of triples ``(other_lang, other_classification, title)`` =================== =========== ============================================================= Hierarchical lists @@ -336,7 +336,7 @@ 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 +``other_languages`` list[tuple] List of tuples ``(lang, author, name)`` of same author in other languages =================== =========== ========================================================================= @@ -350,11 +350,11 @@ Name Type Description =================== =========== ============================================================================= ``kind`` str Always ``"category"`` ``category`` str Category name -``category_path`` list<str> Category hierarchy +``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 +``other_languages`` list[tuple] List of tuples ``(lang, category, name)`` of same category in other languages =================== =========== ============================================================================= Variables available in galleries @@ -386,8 +386,8 @@ 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 +``folders`` list[str] List of subfolders +``files`` list[str] List of files in the folder ``source_link`` str Link to the source file ================== ========== ======================================== @@ -401,7 +401,7 @@ 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 +``other_languages`` list[tuple] List of tuples ``(lang, section, name)`` of same section in other languages =================== =========== =========================================================================== Variables available in tag pages @@ -414,7 +414,7 @@ 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 +``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``) @@ -422,12 +422,16 @@ 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)* -============== ====== =========================================================================================================== +========================= ====== =========================================================================================================== +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)* +``category_titles`` dict ``CATEGORY_TITLES`` setting (dict for the current language only) +``category_descriptions`` dict ``CATEGORY_DESCRIPTIONS`` setting (dict for the current language only) +``tag_titles`` dict ``TAG_TITLES`` setting (dict for the current language only) +``tag_descriptions`` dict ``TAG_DESCRIPTIONS`` setting (dict for the current language only) +========================= ====== =========================================================================================================== For more details about hierarchies, see `Hierarchical lists`_ @@ -442,7 +446,7 @@ Variables available in shortcodes Name Type Description ================== ========== =========================================================================== ``lang`` str Current language -``_args`` list<str> Arguments given to the shortcode +``_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`` @@ -458,7 +462,7 @@ Variables available in post lists ================== ========== ===================================== Name Type Description ================== ========== ===================================== -``posts`` list<Post> Posts that are on the list +``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 @@ -478,7 +482,7 @@ More docs: `nikola.post.Post on ReadTheDocs <https://nikola.readthedocs.io/en/la =================================================================== ========== ============================================================= Name Type Description =================================================================== ========== ============================================================= -``alltags`` list<str> All tags for the post +``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`` @@ -509,11 +513,11 @@ Name Type ``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 +``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 +``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 =================================================================== ========== ============================================================= diff --git a/docs/theming.rst b/docs/theming.rst index f875104..957e68e 100644 --- a/docs/theming.rst +++ b/docs/theming.rst @@ -6,7 +6,7 @@ .. description: .. author: The Nikola Team -:Version: 8.1.3 +:Version: 8.2.0 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> .. class:: alert alert-primary float-md-right |