diff options
Diffstat (limited to 'docs/manual.rst')
| -rw-r--r-- | docs/manual.rst | 63 |
1 files changed, 48 insertions, 15 deletions
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: |